https://github.com/bkuhlmann/pkce

An OAuth Proof Key for Code Exchange (PKCE) challenge and code verifier.
https://github.com/bkuhlmann/pkce

oauth oauth2 pkce pkce-authentication security

Last synced: about 4 hours ago
JSON representation

An OAuth Proof Key for Code Exchange (PKCE) challenge and code verifier.

• Host: GitHub
• URL: https://github.com/bkuhlmann/pkce
• Owner: bkuhlmann
• License: other
• Created: 2022-06-25T14:17:44.000Z (over 2 years ago)
• Default Branch: main
• Last Pushed: 2024-10-28T14:13:43.000Z (11 days ago)
• Last Synced: 2024-10-28T17:13:43.514Z (11 days ago)
• Topics: oauth, oauth2, pkce, pkce-authentication, security
• Language: Ruby
• Homepage: https://alchemists.io/projects/pkce
• Size: 166 KB
• Stars: 2
• Watchers: 3
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.adoc
  • Funding: .github/FUNDING.yml
  • License: LICENSE.adoc
  • Citation: CITATION.cff

Awesome Lists containing this project

README

        
:rfc_link: link:https://datatracker.ietf.org/doc/html/rfc7636[RFC 7636]

:toc: macro

:toclevels: 5

:figure-caption!:

= Proof Key for Code Exchange (PKCE)

Proof Key for Code Exchange (PKCE) is an authorization code flow extension to link:https://oauth.net[OAuth] which is necessary for mobile authentication but works well for web flows because the added security is transparent to the user. Specifically, PKCE prevents the following types of attacks:

* Authorization code interception

* Authorization code injection

This gem is an implementation of the {rfc_link} specification so you can leverage PKCE in your own code.

toc::[]

== Features

- Implements the {rfc_link} specification.

- Provides a simple object API for obtaining a challenge and verify code.

- Provides max length security by default.

- Answers a monad result.

== Requirements

. link:https://www.ruby-lang.org[Ruby].

. link:https://www.oauth.com[OAuth].

== Setup

To install _with_ security, run:

[source,bash]

----

# 💡 Skip this line if you already have the public certificate installed.

gem cert --add <(curl --compressed --location https://alchemists.io/gems.pem)

gem install pkce --trust-policy HighSecurity

----

To install _without_ security, run:

[source,bash]

----

gem install pkce

----

You can also add the gem directly to your project:

[source,bash]

----

bundle add pkce

----

Once the gem is installed, you only need to require it:

[source,ruby]

----

require "pkce"

----

== Usage

The object API is simple to work with as you only need to interact with the `PKCE` constant. Example:

[source,ruby]

----

code = PKCE.call.success

code.challenge  # e2tGChTfGON-C55i0yu13-urIgDFuMCmo73F7TZmoiw

code.verify     # hYnx2WTJo7Bgu1-GqPUIYtRkb2W7pRBawkmdDi3omPdramb27Fp4rps_w6ozns-gbVCKFC2-Kno4P_b1H3FuxnlYIOd9Bo5yoTXq_xEHDJaB_fOfn2NaiCtcWQ8Bs91I

----

You can also pass in a custom length (default is maximum):

[source,ruby]

----

code = PKCE.call(length: 35).success

code.challenge  # R1b1Ka3jmrLKvQ7xW5QmP5MsCSEWtdoA2lo3r-SZDfg

code.verify     # ucKkqwoMzc9cyPcSGMbuVf3ivr4sep2mq15hGN9sVzl4X7g

----

In case of a failure, you'll get a proper error message:

[source,ruby]

----

PKCE.call(length: 100).failure  # Invalid PKCE verifier length: 100. Must be between 32..96.

----

Due to the fact that PKCE answers back a link:https://dry-rb.org/gems/dry-monads[monad], you have all of the power of link:https://alchemists.io/talks/ruby_pattern_matching[pattern matching] at your fingertips as well:

[source,ruby]

----

include Dry::Monads[:result]

case PKCE.call

  in Success(code) then puts code.inspect

  in Failure(message) then puts message

end

----

Finally, since the code answered back is a link:https://alchemists.io/articles/ruby_data[Data] object that you can easily test and interact with:

[source,ruby]

----

PKCE.call.success

#

----

== Development

To contribute, run:

[source,bash]

----

git clone https://github.com/bkuhlmann/pkce

cd pkce

bin/setup

----

You can also use the IRB console for direct access to all objects:

[source,bash]

----

bin/console

----

=== Architecture

The following documents the workflow used to process and build authorization codes.

image::https://alchemists.io/images/projects/pkce/doc/sequence_diagram.svg[Sequence Diagram]

== Tests

To test, run:

[source,bash]

----

bin/rake

----

== link:https://alchemists.io/policies/license[License]

== link:https://alchemists.io/policies/security[Security]

== link:https://alchemists.io/policies/code_of_conduct[Code of Conduct]

== link:https://alchemists.io/policies/contributions[Contributions]

== link:https://alchemists.io/policies/developer_certificate_of_origin[Developer Certificate of Origin]

== link:https://alchemists.io/projects/pkce/versions[Versions]

== link:https://alchemists.io/community[Community]

== Credits

* Built with link:https://alchemists.io/projects/gemsmith[Gemsmith].

* Engineered by link:https://alchemists.io/team/brooke_kuhlmann[Brooke Kuhlmann].