js-pkce

A package that makes using the OAuth2 PKCE flow easier.

This package is implemented according to the specification: rfc7636.

Use from CDN

Since version 1.3.0 this package is available to be used from a CDN:

https://cdn.jsdelivr.net/npm/js-pkce/dist/browser.js

Explicit version example:

https://cdn.jsdelivr.net/npm/js-pkce@1.5/dist/browser.js

Installation

npm i js-pkce

Create a new instance

Create a new instance of js-pkce with all of the details needed.

1import PKCE from 'js-pkce';
2const pkce = new PKCE({
3  client_id: 'myclientid',
4  redirect_uri: 'http://localhost:8080/auth',
5  authorization_endpoint: 'https://authserver.com/oauth/authorize',
6  token_endpoint: 'https://authserver.com/oauth/token',
7  revoke_endpoint: 'https://authserver.com/oauth/revoke', // optional
8  requested_scopes: '*',
9  storage: sessionStorage // optional
10});

Start the authorization process

Typically you just need to go to the authorization url to start the process. This example is something that might work in a SPA.

1window.location.replace(pkce.authorizeUrl());

You may add additional query parameters to the authorize url by using an optional second parameter:

1const additionalParams = {test_param: 'testing'};
2window.location.replace(pkce.authorizeUrl(additionalParams));

Trade the code for a token

After logging in with the authorization server, you will be redirected to the value in the redirect_uri parameter you set when creating the instance. Again, this is an example that might work for a SPA.

When you get back here, you need to exchange the code for a token.

1const url = window.location.href;
2pkce.exchangeForAccessToken(url).then((resp) => {
3  const token = resp.access_token;
4  // Do stuff with the access token.
5});

As with the authorizeUrl method, an optional second parameter may be passed to the exchangeForAccessToken method to send additional parameters to the request:

1const url = window.location.href;
2const additionalParams = {test_param: 'testing'};
3
4pkce.exchangeForAccessToken(url, additionalParams).then((resp) => {
5  const token = resp.access_token;
6  // Do stuff with the access token.
7});

Refreshing the token

Get a new access token using a refresh token

1pkce.refreshAccessToken(refreshToken).then((resp) => {
2  const accessToken = resp.access_token;
3  const refreshToken = resp.refresh_token;
4  // Do stuff with the access & refresh token.
5});

Revoking a token

Revoke a token. Note that the specification for this functionality in the context of PKCE is not very well defined. This may not work for all authorization servers.

You may optionally pass a token_type_hint as the second parameter.

1pkce.revokeToken(tokenToExpire, 'access_token')

Cors credentials

When using httpOnly cookies, there is some additional configuration required. The method enableCorsCredentials can be called to allow sending credentials.

1pkce.enableCorsCredentials(true);

A note on Storage

By default, this package will use sessionStorage to persist the pkce_state. On (mostly) mobile devices there's a higher chance users are returning in a different browser tab. E.g. they kick off in a WebView & get redirected to a new tab. The sessionStorage will be empty there.

In this case it you can opt in to use localStorage instead of sessionStorage:

1import PKCE from 'js-pkce';
2const pkce = new PKCE({
3  // ...
4  storage: localStorage, // any Storage object, sessionStorage (default) or localStorage 
5});