PKCE support documentation

[shrihari-prakash]

Is there any documentation available for enabling PKCE support that was added recently to this package?

[shrihari-prakash]

Hello @jankapunkt , if there is no documentation about this, is it possible to list the steps required to enable PKCE?

[jankapunkt]

Hi @shrihari-prakash sorry for the late response I am looking into this. I seems that we forgot to add a documentation.

The PKCE integration is based on RFC 7636 and integrates with the authorization code grant workflow. The abstract workflow looks like the following:

                                                 +-------------------+
                                                 |   Authz Server    |
       +--------+                                | +---------------+ |
       |        |--(A)- Authorization Request ---->|               | |
       |        |       + t(code_verifier), t_m  | | Authorization | |
       |        |                                | |    Endpoint   | |
       |        |<-(B)---- Authorization Code -----|               | |
       |        |                                | +---------------+ |
       | Client |                                |                   |
       |        |                                | +---------------+ |
       |        |--(C)-- Access Token Request ---->|               | |
       |        |          + code_verifier       | |    Token      | |
       |        |                                | |   Endpoint    | |
       |        |<-(D)------ Access Token ---------|               | |
       +--------+                                | +---------------+ |
                                                 +-------------------+

                     Figure 2: Abstract Protocol Flow

A. The client creates and records a secret named the "code_verifier"
and derives a transformed version "t(code_verifier)" (referred to
as the "code_challenge"), which is sent in the OAuth 2.0
Authorization Request along with the transformation method "t_m".

In this project the authorize endpoint usually calls OAuth2Server.prototype.authorize which itself uses AuthorizeHandler.
If your Request body contains code_challenge and code_challenge_method then PKCE is automatically included.

const server = new OAuth2Server({ model })


// this could be added to express or other middleware
const authorizeEndpoint = function (req, res, next) {
  const request = new Request(req)
  server.authorize(request, response, options)
        .then(function (code) {
          // add code to response, code should contain 
        })
        .catch(function (err) {
          // handle error condition
        })
}

The request from the client must contain code_challenge and code_challenge_method.
As an example you could generate a random code challenge like so:

const base64URLEncode = str => str.toString('base64')
      .replace(/\+/g, '-')
      .replace(/\//g, '_')
      .replace(/=/g, '')

// this is the code_verifier, which is kept secret on the client
// and which is later passed as request param to the token endpoint
const codeVerifier = base64URLEncode(crypto.randomBytes(32))

// this is the hashed version of the verifier, which is sent to the authorization endpoint
// this is named t(code_verifier) in the above workflow
const codeChallenge = base64URLEncode(crypto.createHash('sha256').update(codeVerifier).digest())

// this is the name of the code challenge method
// this is named t_m in the above workflow
const codeChallengeMethod = 'S256'

// add these to the request that is fired from the client

B. The Authorization Endpoint responds as usual but records
"t(code_verifier)" and the transformation method.

The AuthorizeHandler.prototype.handle saves code challenge and code challenge method automatically via saveAuthorizationCode. Note that this calls your model and you have to update your validation schema, if you use any.

C. The client then sends the authorization code in the Access Token
Request as usual but includes the "code_verifier" secret generated
at (A).

This is usually done in your token endpoint, that should use OAuth2Server.prototype.token.
Note that your client should have kept codeVerifier a secret until this step and now includes it
to the token endpoint.

D. The authorization server transforms "code_verifier" and compares
it to "t(code_verifier)" from (B). Access is denied if they are
not equal.

This is done by the package internally.

const server = new OAuth2Server({ model })

// ...

// this could be added to express or other middleware
const tokenEndpoint = function (req, res, next) {
  const request = new Request(req)
  server.token(request, response, options)
        .then(function (code) {
          // add code to response, code should contain 
        })
        .catch(function (err) {
          // handle error condition
        })
}

[shrihari-prakash]

Hello @jankapunkt ,
Thanks much for the very detailed explanation. However, is there a change required in the method implementations in the model itself? For instance, the saveAuthorizationCode receives code, client and user as the input for the moment, in such cases should it also receive codeChallenge and codeChallengeMethod? If yes, what are the other methods that need to accept such new parameters in the model?

[shrihari-prakash]

This seems to be everything I am getting with the code 🤔:

Even though the request contains all these parameters:

[shrihari-prakash]

Oh so the OAuth Server seems to retrieve the code challenge and challenge method from the body, and returns nothing if it is in query string:

I suggest that we do something like:

return request.body.code_challenge || return request.query.code_challenge;;

Which would make it consistent with other parameters in the authorize method.

[shrihari-prakash]

For instance, see getClient method of

node-oauth2-server/lib/handlers/authorize-handler.js

Line 168 in 4494564

const clientId = request.body.client_id || request.query.client_id;

[jankapunkt]

you are right, PR incoming

[jankapunkt]

Please review: #197