PKCE implementation #205

aarongranick-okta · 2019-04-15T17:25:23Z

adds unit tests
includes a simple app (test/app) which performs the full PKCE flow
supports all getToken flows including auto renew
adds karma/webpack tests for in browser testing of crypto & login flows

TODO:

this has only been tested with the cross-fetch httpRequestClient. There were specific changes involving content type that may need to be duplicated in the other clients (jquery / reqwest). NEEDS to be tested with jquery/reqwest!

- generateIDtoken - bypassCrypto (will "ignoreSignature") - option for timeout on test - responseVars for XHR templates

reqwest/reqwestRequest.js

lib/http.js

lib/pkce.js

lib/token.js

test/app/src/testApp.js

jmelberg-okta

Took a quick first pass - but primarily need to address a few things:

The crypo library used should be revisited. This will need to be approved by our security team before this gets merged.
We need to account for basic validation for the code_verifier. We should have tests that assert it has sufficient entropy and meets the size boundary.

lib/pkce.js

package.json

test/app/README.md

test/app/src/testApp.js

lib/token.js

swiftone · 2019-05-23T21:35:14Z

fetch/fetchRequest.js

+  var body = args.data;
+
+  // JSON encode body (if appropriate)
+  if (body && args.headers && args.headers['Content-Type'] === 'application/json' && typeof body !== 'string') {


Are we sure it will be 'Content-Type' and never 'content-type'? IIRC the spec is not case sensitive.

The header can be either, but looking up the key 'Content-Type' in this object is case sensitive. We should probably check 'Content-Type'.toLower() too.

I can definitely make this change. But in reality we are the only users of this code. We use it as a pluggable utility wrapper around another xhr lib. Anything we do here, we must duplicate that logic in our jqueryRequest and reqwestRequest objects as well. Previously EVERYTHING was JSON encoded. I am creating a small pinhole for the token POST to succeed

Shouldn't we check these values to be safe? If our dependency on cross-fetch, an application and/or plugin modifies the headers to be lowercase, this check will fail.

test/app/src/testApp.js

swiftone · 2019-05-23T21:42:25Z

webpack.config.js

@@ -3,7 +3,7 @@
 * anywhere without any dependencies. It packages the SDK
 * with reqwest and Q. It also preserves license comments.
 */
-
+/* global __dirname */


stale comment.

our eslint is setup for client-side. I did not want to set node: true for the whole folder so just a single case here

swiftone

A few nits but nothing blocking

jmelberg-okta

Overall looking really good. Few nits and questions.

Only real blocker is whether or not to encourage devs to fallback to implicit versus throwing an error.

README.md

lib/token.js

jmelberg-okta · 2019-05-23T21:24:21Z

README.md

-Parses the access or ID Tokens from the url after a successful authentication redirect. If an ID token is present, it will be [verified and validated](https://github.com/okta/okta-auth-js/blob/master/lib/token.js#L186-L190) before available for use.
+Parses the authorization code, access, or ID Tokens from the URL after a successful authentication redirect. 
+
+If an authorization code is present, it will be exchanged for token(s) by posting to the `tokenUrl` endpoint. 


Just to clarify - the resolved return value from token.parseFromUrl will be an accessToken and/or idToken. The authorization_code will never be available to the developer, correct?

lib/builderUtil.js

jmelberg-okta · 2019-05-23T21:31:42Z

README.md

+
+var config = {
+  // use PKCE or implicit flow based on browser support
+  grantType: OktaAuth.features.isPKCESupported() ? 'authorization_code' : 'implicit',


From our conversation yesterday, I thought we didn't want to fall back to implicit if the browser doesn't support crypto.subtle, as PKCE is the safer approach.

Suggestion: Run the OktaAuth.features.isPKCESupported() function before crypto.subtle is called, so we can return an error message if the user is using an unsupported browser.

This is now being tested / will throw in the OktaAuth constructor

test/karma/spec/features.js

jmelberg-okta · 2019-05-23T22:33:38Z

test/karma/spec/pkce.js

+  });
+
+
+});


style-nit: A few files are missing newlines at the end

I've updated the eslint rules for the karma stuff

jmelberg-okta · 2019-05-23T22:34:09Z

test/karma/spec/pkce.js

+      .then(function(computed) {
+        expect(encodeURIComponent(computed)).toBe(computed);
+      });  
+    })


Is eslint configured for the karma specs? We're missing ; in a few places.

It is, but is using more "modern" settings which doesn't require. I'll add the "semi" rule in

I also aded the eol rule

test/karma/spec/renewToken.js

manueltanzi-okta

Looks great! Thank for addressing my comments.

Please add the error message for when PKCE is not supported, then 🚀

README.md

manueltanzi-okta · 2019-05-23T23:22:51Z

README.md

@@ -212,7 +234,8 @@ var config = {
    //   headers: {
    //     headerName: headerValue
    //   },
-    //   data: postBodyData
+    //   data: postBodyData,
+    //   withCredentials: true|false,


nit: Maybe throw a line to explain why they might need withCredentials set to false or true.

If they are providing the httpRequest agent, they just need to honor the setting. It is a common flag for ajax libraries.

haishengwu-okta

couple of questions and looks good to me, plus echo Jordan's comments.

lib/http.js

haishengwu-okta · 2019-05-24T18:25:48Z

lib/token.js

@@ -464,53 +511,81 @@ function getWithoutPrompt(sdk, oauthOptions, options) {
 function getWithPopup(sdk, oauthOptions, options) {
  var oauthParams = util.clone(oauthOptions) || {};
  util.extend(oauthParams, {
-    display: 'popup'
+    display: 'popup',
+    responseMode: 'okta_post_message'


why you have to add responseMode: 'okta_post_message'?

In an earlier version of this PR, I was changing the default responseMode, so this line was necessary. That breaking change has been removed. Also I have discovered the true reason okta_post_message is the default, is because token.renew() cannot take any parameters, so must use defaults or values set in the constructor.

aarongranick-okta · 2019-05-29T23:57:52Z

@jmelberg-okta Please take another look when you have a chance. I believe I have addressed all feedback / requests. Thanks!

jmelberg-okta

Couple more questions related to older comments. Can you please ensure all comments have been acknowledged and answered?

jmelberg-okta · 2019-05-31T16:25:20Z

fetch/fetchRequest.js

+  var body = args.data;
+
+  // JSON encode body (if appropriate)
+  if (body && args.headers && args.headers['Content-Type'] === 'application/json' && typeof body !== 'string') {


lib/token.js

test/karma/spec/renewToken.js

jmelberg-okta · 2019-05-31T23:47:21Z

README.md

@@ -1367,14 +1392,15 @@ The following configuration options can **only** be included in `token.getWithou
 | :-------: | ----------|
 | `sessionToken` | Specify an Okta sessionToken to skip reauthentication when the user already authenticated using the Authentication Flow. |
 | `responseMode` | Specify how the authorization response should be returned. You will generally not need to set this unless you want to override the default values for `token.getWithRedirect`. See [Parameter Details](https://developer.okta.com/docs/api/resources/oidc#parameter-details) for a list of available modes. |
-| `responseType` | Specify the [response type](https://developer.okta.com/docs/api/resources/oidc#request-parameters) for OIDC authentication. Defaults to `id_token`. |
+| `responseType` | Specify the [response type](https://developer.okta.com/docs/api/resources/oidc#request-parameters) for OIDC authentication. Defaults to `id_token`. Supported values are `id_token` and `token`. |


We also need to support code. To kick off the PKCE flow the developer needs to pass in the grant type of authorization_code and the response type is required to be code. The only thing we need to restrict is the combination of response types when using PKCE.

Suggestion:

Supported values are id_token, token, and code. Hybrid flows (code token, code id_token) are not supported.

jmelberg-okta · 2019-05-31T23:48:48Z

fetch/fetchRequest.js

 function fetchRequest(method, url, args) {
+  var body = args.data;
+  var headers = args.headers || {};
+  var contentType = (headers['Content-Type'] || headers['content-type'] || '').toLowerCase();


The extra toLowerCase() isn't needed here. We only need to assert that the dictionary key is case sensitive.

jmelberg-okta · 2019-05-31T23:55:26Z

lib/token.js

+  if (typeof responseType === 'string') {
+    responseType = [responseType];
+  }
+  if (responseType.includes('code')) {


Left a comment in the README, but we need to remove this check. Our documentation mentions that you must have this value when using this grant.

Instead - when we obtain values for the grant_type and response_type, we should assert that if grant_type is authorization_code then response_type is code. If it isn't, we can add that for them as the default value.

Therefore:

grant_type=authorization_code && response_type=token: Fails

grant_type=authorization_code && response_type=id_token: Fails

grant_type=authorization_code && response_type=code: Succeeds

grant_type=authorization_code && response_type=undefined: Succeeds as we populate this value for them.

Yes this definitely makes sense. The refactor is here: 24deee5

jmelberg-okta

Once feedback is addressed - 🚀

My primary ask is since we've refactored a bit of our existing getToken method and token renewal functions, can we please test this against the Widget inside of the monolith? Assuming those tests pass, I think this is safe to release.

jmelberg-okta · 2019-06-03T05:15:52Z

lib/TokenManager.js

-        // renewed token, we verify the promise key doesn't exist and return.
-        return;
+    .then(function(freshTokens) {
+      // We may receive more tokens than we requested


I'm not sure this is necessarily correct - developers configuring the scope and grant_type should always know what tokens will be returned.

For example, when scope=openid: The response should contain an access and identity token.
When scope=foobar (non-OIDC scope): The response should contain only an access token.

While scope validation can infer which token types will be minted, one option could be to make the change there. However this is probably the right way to handle this.

I'd suggest removing this comment and keeping your logic below.

What's happening here is the caller is saying something like:

var token = tokenManager.get('accessToken')

This triggers the renew token logic. If we are using authorization code then we will receive all tokens (as defined by the scope). This logic is (trying) to allow all tokens to be refreshed but return only the one requested.

I think, as written, it may not work for token types other than idToken and accessToken (these are the only we have defined in the token manager). - does this library support other token types?

jmelberg-okta · 2019-06-03T05:19:39Z

lib/pkce.js

+    throw new AuthSdkError('A clientId must be specified in the OktaAuth constructor to get a token');
+  }
+
+  if (!oauthOptions.redirectUri) {


FYI: According to the spec this value should be checked against the original redirect URI:

redirect_uri REQUIRED, if the "redirect_uri" parameter was included in the authorization request as described in Section 4.1.1, and their values MUST be identical.

I believe the server is doing this check. This validation here is around the API call - it is saying redirectUri is a required parameter to the api (the server will fail the call if it is not present).

jmelberg-okta · 2019-06-03T05:24:04Z

lib/token.js

+      return (responseType.indexOf(key) !== -1);
+    }).forEach(function(key) {
+      if (!tokenDict[key]) {
+        throw new AuthSdkError('Unable to parse OAuth flow response: ' + key + ' was not returned.');


Probably OK for now, but ideally we'll concat an error message with both all keys instead of throwing on the first encounter.

jmelberg-okta · 2019-06-03T15:44:06Z

README.md

@@ -162,8 +162,10 @@ tokenManager: {
 | `issuer`       | Specify a custom issuer to perform the OIDC flow. Defaults to the base url parameter if not provided. |
 | `clientId`     | Client Id pre-registered with Okta for the OIDC authentication flow. |
 | `redirectUri`  | The url that is redirected to when using `token.getWithRedirect`. This must be pre-registered as part of client registration. If no `redirectUri` is provided, defaults to the current origin. |
+| `grantType`  | Specify grantType for this Application. Supported types are `implicit` and `authorization_code`. Defaults to `implicit` |


style-nit: Adhere to the existing style of surrounding grantType in the description with back-ticks.

jmelberg-okta · 2019-06-03T15:45:31Z

README.md

@@ -191,6 +193,28 @@ var config = {
 var authClient = new OktaAuth(config);
 ```

+##### PKCE OAuth flow


OAuth -> OAuth 2.0

We don't need to replace all other occurrences of this, but we should make sure we're referencing the correct protocol in our headings.

jmelberg-okta · 2019-06-03T15:46:14Z

README.md

@@ -1367,14 +1392,15 @@ The following configuration options can **only** be included in `token.getWithou
 | :-------: | ----------|
 | `sessionToken` | Specify an Okta sessionToken to skip reauthentication when the user already authenticated using the Authentication Flow. |
 | `responseMode` | Specify how the authorization response should be returned. You will generally not need to set this unless you want to override the default values for `token.getWithRedirect`. See [Parameter Details](https://developer.okta.com/docs/api/resources/oidc#parameter-details) for a list of available modes. |
-| `responseType` | Specify the [response type](https://developer.okta.com/docs/api/resources/oidc#request-parameters) for OIDC authentication. Defaults to `id_token`. |
+| `responseType` | Specify the [response type](https://developer.okta.com/docs/api/resources/oidc#request-parameters) for OIDC authentication. The default value is based on the configured `grantType`. If `grantType` is `implicit` (the default setting), `responseType` will have a default value of `id_token`. If `grantType` is `authorization_code`, the default value will be `code`. |


Great description! 👍

jmelberg-okta · 2019-06-03T16:00:58Z

lib/TokenManager.js

+        var inferredKey = freshToken.idToken ? 'idToken' : freshToken.accessToken ? 'accessToken' : key;
+        map[inferredKey] = freshToken;
+
+        var oldToken = get(storage, inferredKey);


nit: This is a duplicate call. You can use the token variable above instead.

If you look at the code being replaced, this extra call was there before, I believe it is to prevent an error where the token existed before refresh attempt but was cleared while the request was in flight. In the case that the token may have changed while the request was in flight, I am taking the freshest "old" token

jmelberg-okta · 2019-06-03T16:02:43Z

lib/browser/browser.js

    redirectUri: args.redirectUri,
    httpRequestClient: args.httpRequestClient,
    storageUtil: args.storageUtil,
    transformErrorXHR: args.transformErrorXHR,
    headers: args.headers
  };

+  if (this.options.grantType === 'authorization_code' && !sdk.features.isPKCESupported()) {


Don't we also need this statement whenever token.getWith* methods are called? Developers should be able to init their authClient with some config but override it when calling getWith*.

A developer CAN override grantType in these calls, but we are not checking for PKCE support. I did have this logic + tests, but after talking with @robertdamphousse-okta we decided to leave it out until requested, as we want to encourage setting grantType up front so that token auto-renew works properly.

It would be trivial to bring it back: dc1adca#diff-2c8402d8ca2c5c319eb971f5bdf5ac4dR37

adding this back in.

aarongranick-okta added 13 commits April 9, 2019 18:14

wip

b0624fa

cleanup, fix

8a4e4c8

cleanup / reduce

c140fd0

simple test app, performs PKCE flow

839139c

lint

23857b6

fix tests

3901d65

npm start

2e89506

save / load code verifier

1f26bfa

polyfill webcrypto, TextEncoder to test computeChallenge

8421b1c

Add options to util:

6ee3148

- generateIDtoken - bypassCrypto (will "ignoreSignature") - option for timeout on test - responseVars for XHR templates

test exchangeFortoken, fix minor bug

0f3cc7b

Merge branch 'master' into pkce

aa9ccc7

cleanup, fix tests

06b8dfa

aarongranick-okta requested a review from manueltanzi-okta April 15, 2019 20:37

Merge branch 'master' into pkce

7650c24

aarongranick-okta requested a review from swiftone April 17, 2019 23:25