The letter A styled as Alchemists logo. lchemists
Brooke Kuhlmann's Avatar Brooke Kuhlmann
Published June 25, 2022 Updated March 24, 2024
PKCE Icon

PKCE

2.1.0

Circe CI Status. Alchemists Style Guide. Git Badge Sponsor Badge

Proof Key for Code Exchange (PKCE) is an authorization code flow extension to 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 7636 specification so you can leverage PKCE in your own code.

Features

  • Implements the RFC 7636 specification.

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

  • Provides max length security by default.

  • Answers a monad result.

Requirements

  1. Ruby.

  2. OAuth.

Setup

To install with security, run:

# 💡 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:

gem install pkce

You can also add the gem directly to your project:

bundle add pkce

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

require "pkce"

Usage

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

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):

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:

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

Due to the fact that PKCE answers back a monad, you have all of the power of pattern matching at your fingertips as well:

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 Data object that you can easily test and interact with:

PKCE.call.success
#<data PKCE::Code challenge="ROMnfvHt04xhM80WB2PyPK67GGrG35UdFEf0DEBkes0", verify="cUq917cDIROAUkew-OjIdfIz1OYyv-ERt9NnSdzlxz4XSYzdbRycVuRDD2SBIDBiKnXUamxvpxNRsUMBQ1PvBdtziGs_oYe98MDWmM8J2_NJQBVg2kP-B2OqBdMp00qh">

Development

To contribute, run:

git clone https://github.com/bkuhlmann/pkce
cd pkce
bin/setup

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

bin/console

Architecture

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

Sequence Diagram

Tests

To test, run:

bin/rake

License

Security

Code of Conduct

Contributions

Versions

Community

Credits