feature(pkce): added pkce support

Merge pull request #86 from node-oauth/feature-pkce

Contributors: @martinssonj @jankapunkt @Uzlopak

Author: jankapunkt

index.d.ts

@@ -306,7 +306,7 @@ declare namespace OAuth2Server {
          *
          */
         saveAuthorizationCode(
-          code: Pick<AuthorizationCode, 'authorizationCode' | 'expiresAt' | 'redirectUri' | 'scope'>,
+          code: Pick<AuthorizationCode, 'authorizationCode' | 'expiresAt' | 'redirectUri' | 'scope' | 'codeChallenge' | 'codeChallengeMethod'>,
           client: Client,
           user: User,
           callback?: Callback<AuthorizationCode>): Promise<AuthorizationCode | Falsey>;
@@ -410,6 +410,8 @@ declare namespace OAuth2Server {
         scope?: string | string[] | undefined;
         client: Client;
         user: User;
+        codeChallenge?: string;
+        codeChallengeMethod?: string;
         [key: string]: any;
     }
 

lib/grant-types/authorization-code-grant-type.js

@@ -13,6 +13,7 @@ const promisify = require('promisify-any').use(Promise);
 const ServerError = require('../errors/server-error');
 const isFormat = require('@node-oauth/formats');
 const util = require('util');
+const pkce = require('../pkce/pkce');
 
 /**
  * Constructor.
@@ -118,6 +119,36 @@ AuthorizationCodeGrantType.prototype.getAuthorizationCode = function(request, cl
         throw new InvalidGrantError('Invalid grant: `redirect_uri` is not a valid URI');
       }
 
+      // optional: PKCE code challenge
+
+      if (code.codeChallenge) {
+        if (!request.body.code_verifier) {
+          throw new InvalidGrantError('Missing parameter: `code_verifier`');
+        }
+
+        const hash = pkce.getHashForCodeChallenge({
+          method: code.codeChallengeMethod,
+          verifier: request.body.code_verifier
+        });
+
+        if (!hash) {
+          // notice that we assume that codeChallengeMethod is already
+          // checked at an earlier stage when being read from
+          // request.body.code_challenge_method
+          throw new ServerError('Server error: `getAuthorizationCode()` did not return a valid `codeChallengeMethod` property');
+        }
+
+        if (code.codeChallenge !== hash) {
+          throw new InvalidGrantError('Invalid grant: code verifier is invalid');
+        }
+      }
+      else {
+        if (request.body.code_verifier) {
+          // No code challenge but code_verifier was passed in.
+          throw new InvalidGrantError('Invalid grant: code verifier is invalid');
+        }
+      }
+
       return code;
     });
 };

lib/handlers/authorize-handler.js

@@ -21,6 +21,7 @@ const UnauthorizedClientError = require('../errors/unauthorized-client-error');
 const isFormat = require('@node-oauth/formats');
 const tokenUtil = require('../utils/token-util');
 const url = require('url');
+const pkce = require('../pkce/pkce');
 
 /**
  * Response types.
@@ -110,8 +111,10 @@ AuthorizeHandler.prototype.handle = function(request, response) {
         })
         .then(function(authorizationCode) {
           ResponseType = this.getResponseType(request);
+          const codeChallenge = this.getCodeChallenge(request);
+          const codeChallengeMethod = this.getCodeChallengeMethod(request);
 
-          return this.saveAuthorizationCode(authorizationCode, expiresAt, scope, client, uri, user);
+          return this.saveAuthorizationCode(authorizationCode, expiresAt, scope, client, uri, user, codeChallenge, codeChallengeMethod);
         })
         .then(function(code) {
           const responseType = new ResponseType(code.authorizationCode);
@@ -289,13 +292,20 @@ AuthorizeHandler.prototype.getRedirectUri = function(request, client) {
  * Save authorization code.
  */
 
-AuthorizeHandler.prototype.saveAuthorizationCode = function(authorizationCode, expiresAt, scope, client, redirectUri, user) {
-  const code = {
+AuthorizeHandler.prototype.saveAuthorizationCode = function(authorizationCode, expiresAt, scope, client, redirectUri, user, codeChallenge, codeChallengeMethod) {
+  let code = {
     authorizationCode: authorizationCode,
     expiresAt: expiresAt,
     redirectUri: redirectUri,
     scope: scope
   };
+
+  if(codeChallenge && codeChallengeMethod){
+    code = Object.assign({
+      codeChallenge: codeChallenge,
+      codeChallengeMethod: codeChallengeMethod
+    }, code);
+  }
   return promisify(this.model.saveAuthorizationCode, 3).call(this.model, code, client, user);
 };
 
@@ -365,6 +375,27 @@ AuthorizeHandler.prototype.updateResponse = function(response, redirectUri, stat
   response.redirect(url.format(redirectUri));
 };
 
+AuthorizeHandler.prototype.getCodeChallenge = function(request) {
+  return request.body.code_challenge;
+};
+
+/**
+ * Get code challenge method from request or defaults to plain.
+ * https://www.rfc-editor.org/rfc/rfc7636#section-4.3
+ *
+ * @throws {InvalidRequestError} if request contains unsupported code_challenge_method
+ *  (see https://www.rfc-editor.org/rfc/rfc7636#section-4.4)
+ */
+AuthorizeHandler.prototype.getCodeChallengeMethod = function(request) {
+  const algorithm = request.body.code_challenge_method;
+
+  if (algorithm && !pkce.isValidMethod(algorithm)) {
+    throw new InvalidRequestError(`Invalid request: transform algorithm '${algorithm}' not supported`);
+  }
+
+  return algorithm || 'plain';
+};
+
 /**
  * Export constructor.
  */

lib/handlers/token-handler.js

@@ -18,6 +18,7 @@ const TokenModel = require('../models/token-model');
 const UnauthorizedClientError = require('../errors/unauthorized-client-error');
 const UnsupportedGrantTypeError = require('../errors/unsupported-grant-type-error');
 const auth = require('basic-auth');
+const pkce = require('../pkce/pkce');
 const isFormat = require('@node-oauth/formats');
 
 /**
@@ -114,12 +115,14 @@ TokenHandler.prototype.handle = function(request, response) {
 TokenHandler.prototype.getClient = function(request, response) {
   const credentials = this.getClientCredentials(request);
   const grantType = request.body.grant_type;
+  const codeVerifier = request.body.code_verifier;
+  const isPkce = pkce.isPKCERequest({ grantType, codeVerifier });
 
   if (!credentials.clientId) {
     throw new InvalidRequestError('Missing parameter: `client_id`');
   }
 
-  if (this.isClientAuthenticationRequired(grantType) && !credentials.clientSecret) {
+  if (this.isClientAuthenticationRequired(grantType) && !credentials.clientSecret && !isPkce) {
     throw new InvalidRequestError('Missing parameter: `client_secret`');
   }
 
@@ -174,6 +177,7 @@ TokenHandler.prototype.getClient = function(request, response) {
 TokenHandler.prototype.getClientCredentials = function(request) {
   const credentials = auth(request);
   const grantType = request.body.grant_type;
+  const codeVerifier = request.body.code_verifier;
 
   if (credentials) {
     return { clientId: credentials.name, clientSecret: credentials.pass };
@@ -183,6 +187,12 @@ TokenHandler.prototype.getClientCredentials = function(request) {
     return { clientId: request.body.client_id, clientSecret: request.body.client_secret };
   }
 
+  if (pkce.isPKCERequest({ grantType, codeVerifier })) {
+    if(request.body.client_id) {
+      return { clientId: request.body.client_id };
+    }
+  }
+
   if (!this.isClientAuthenticationRequired(grantType)) {
     if(request.body.client_id) {
       return { clientId: request.body.client_id };

lib/pkce/pkce.js

@@ -0,0 +1,77 @@
+'use strict';
+
+/**
+ * Module dependencies.
+ */
+const { base64URLEncode } = require('../utils/string-util');
+const { createHash } = require('../utils/crypto-util');
+const codeChallengeRegexp = /^([a-zA-Z0-9.\-_~]){43,128}$/;
+/**
+ * Export `TokenUtil`.
+ */
+
+const pkce = {
+  /**
+   * Return hash for code-challenge method-type.
+   *
+   * @param method {String} the code challenge method
+   * @param verifier {String} the code_verifier
+   * @return {String|undefined}
+   */
+  getHashForCodeChallenge: function({ method, verifier }) {
+    // to prevent undesired side-effects when passing some wird values
+    // to createHash or base64URLEncode we first check if the values are right
+    if (pkce.isValidMethod(method) && typeof verifier === 'string' && verifier.length > 0) {
+      if (method === 'plain') {
+        return verifier;
+      }
+
+      if (method === 'S256') {
+        const hash = createHash({ data: verifier });
+        return base64URLEncode(hash);
+      }
+    }
+  },
+
+  /**
+   * Check if the request is a PCKE request. We assume PKCE if grant type is
+   * 'authorization_code' and code verifier is present.
+   *
+   * @param grantType {String}
+   * @param codeVerifier {String}
+   * @return {boolean}
+   */
+  isPKCERequest: function ({ grantType, codeVerifier }) {
+    return grantType === 'authorization_code' && !!codeVerifier;
+  },
+
+  /**
+   * Matches a code verifier (or code challenge) against the following criteria:
+   *
+   * code-verifier = 43*128unreserved
+   * unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~"
+   * ALPHA = %x41-5A / %x61-7A
+   * DIGIT = %x30-39
+   *
+   * @see: https://datatracker.ietf.org/doc/html/rfc7636#section-4.1
+   * @param codeChallenge {String}
+   * @return {Boolean}
+   */
+  codeChallengeMatchesABNF: function (codeChallenge) {
+    return typeof codeChallenge === 'string' &&
+      !!codeChallenge.match(codeChallengeRegexp);
+  },
+
+  /**
+   * Checks if the code challenge method is one of the supported methods
+   * 'sha256' or 'plain'
+   *
+   * @param method {String}
+   * @return {boolean}
+   */
+  isValidMethod: function (method) {
+    return method === 'S256' || method === 'plain';
+  }
+};
+
+module.exports = pkce;

lib/utils/crypto-util.js

@@ -0,0 +1,24 @@
+'use strict';
+
+const crypto = require('crypto');
+
+/**
+ * Export `StringUtil`.
+ */
+
+module.exports = {
+  /**
+   *
+   * @param algorithm {String} the hash algorithm, default is 'sha256'
+   * @param data {Buffer|String|TypedArray|DataView} the data to hash
+   * @param encoding {String|undefined} optional, the encoding to calculate the
+   *    digest
+   * @return {Buffer|String} if {encoding} undefined a {Buffer} is returned, otherwise a {String}
+   */
+  createHash: function({ algorithm = 'sha256', data = undefined, encoding = undefined }) {
+    return crypto
+      .createHash(algorithm)
+      .update(data)
+      .digest(encoding);
+  }
+};

lib/utils/string-util.js

@@ -0,0 +1,19 @@
+'use strict';
+
+/**
+ * Export `StringUtil`.
+ */
+
+module.exports = {
+  /**
+   *
+   * @param str
+   * @return {string}
+   */
+  base64URLEncode: function(str) {
+    return str.toString('base64')
+      .replace(/\+/g, '-')
+      .replace(/\//g, '_')
+      .replace(/=/g, '');
+  }
+};

lib/utils/token-util.js

@@ -4,8 +4,8 @@
  * Module dependencies.
  */
 
-const crypto = require('crypto');
 const randomBytes = require('bluebird').promisify(require('crypto').randomBytes);
+const { createHash } = require('../utils/crypto-util');
 
 /**
  * Export `TokenUtil`.
@@ -19,10 +19,7 @@ module.exports = {
 
   generateRandomToken: function() {
     return randomBytes(256).then(function(buffer) {
-      return crypto
-        .createHash('sha256')
-        .update(buffer)
-        .digest('hex');
+      return createHash({ data: buffer, encoding: 'hex' });
     });
   }
 

test/integration/handlers/authorize-handler_test.js

@@ -1301,4 +1301,67 @@ describe('AuthorizeHandler integration', function() {
       response.get('location').should.equal('http://example.com/cb?state=foobar');
     });
   });
+
+  describe('getCodeChallengeMethod()', function() {
+    it('should get code challenge method', function() {
+      const model = {
+        getAccessToken: function() {},
+        getClient: function() {},
+        saveAuthorizationCode: function() {}
+      };
+      const handler = new AuthorizeHandler({ authorizationCodeLifetime: 120, model: model });      
+      const request = new Request({ body: {code_challenge_method: 'S256'}, headers: {}, method: {}, query: {} });
+
+      const codeChallengeMethod  = handler.getCodeChallengeMethod(request);
+      codeChallengeMethod.should.equal('S256');
+    });
+
+    it('should throw if the code challenge method is not supported', async function () {
+      const model = {
+        getAccessToken: function() {},
+        getClient: function() {},
+        saveAuthorizationCode: function() {}
+      };
+      const handler = new AuthorizeHandler({ authorizationCodeLifetime: 120, model: model });
+      const request = new Request({ body: {code_challenge_method: 'foo'}, headers: {}, method: {}, query: {} });
+
+      try {
+        handler.getCodeChallengeMethod(request);
+
+        should.fail();
+      } catch (e) {
+        // defined in RFC 7636 - 4.4
+        e.should.be.an.instanceOf(InvalidRequestError);
+        e.message.should.equal('Invalid request: transform algorithm \'foo\' not supported');
+      }
+    });
+
+    it('should get default code challenge method plain if missing', function() {
+      const model = {
+        getAccessToken: function() {},
+        getClient: function() {},
+        saveAuthorizationCode: function() {}
+      };
+      const handler = new AuthorizeHandler({ authorizationCodeLifetime: 120, model: model });      
+      const request = new Request({ body: {}, headers: {}, method: {}, query: {} });
+
+      const codeChallengeMethod  = handler.getCodeChallengeMethod(request);
+      codeChallengeMethod.should.equal('plain');
+    });
+  });
+
+  describe('getCodeChallenge()', function() {
+    it('should get code challenge', function() {
+      const model = {
+        getAccessToken: function() {},
+        getClient: function() {},
+        saveAuthorizationCode: function() {}
+      };
+      const handler = new AuthorizeHandler({ authorizationCodeLifetime: 120, model: model });      
+      const request = new Request({ body: {code_challenge: 'challenge'}, headers: {}, method: {}, query: {} });
+
+      const codeChallengeMethod  = handler.getCodeChallenge(request);
+      codeChallengeMethod.should.equal('challenge');
+    });
+  });
 });