@shoutem/fetch-token-intercept

fetch-token-intercept

Library for easy renewing of access tokens in OAuth's refresh token flow. This library will monkey patch fetch on your target environment and will try to resolve unauthorized requests automatically by renewing the current access token and then retrying an initial fetch operation.

If you are not familiar with refresh token flow you should check some of the following resources:

• RFC standards track regarding refresh token flow
• Auth0 blog - Refresh Tokens: When to Use Them and How They Interact with JWTs
• Shoutem blog - Keeping your tokens fresh

Note: This library expects that fetch and promise api's are available at target environment. You should provide a polyfill when necessary.

Installation

fetch-token-intercept is available on npm.

$ npm install @shoutem/fetch-token-intercept --save

Getting started

Before making any fetch requests you should configure and authorize this library to support interception.

Configuration is provided via config object:

config: {
  // (Required) Prepare fetch request for renewing new access token
  createAccessTokenRequest: (refreshToken) => request,
   
  // (Required) Parses access token from access token response
  parseAccessToken: (response) => accessToken,
   
  // (Required) Defines whether interceptor will intercept this request or just let it pass through
  shouldIntercept: (request) => boolean,
   
  // (Required) Defines whether access token will be invalidated after this response
  shouldInvalidateAccessToken: (response) => boolean,
  
  // When set, response which invalidates token will be resolved after the token has been renewed
  // in effect, token will be loaded in sync with response, otherwise renew will run async to response
  shouldWaitForTokenRenewal: boolean,
  
  // Checks if response should be considered unauthorized (by default only 401 responses are 
  // considered unauthorized). Override this method if you need to trigger token renewal for 
  // other response statuses. Check API reference for helper method which defines default behaviour
  isResponseUnauthorized: (response) => boolean,
   
  // (Required) Adds authorization for intercepted requests
  authorizeRequest: (request, accessToken) => authorizedRequest,
   
  // Number of retries after initial request was unauthorized
  fetchRetryCount: 1,
  
  // Event invoked when access token has changed
  onAccessTokenChange: null,
   
  // Event invoked when response is resolved
  onResponse: null,
}

All required methods return a promise to enable reading of request or response body. You should avoid reading the body directly on provided requests and responses and instead clone them first. The library does not clone objects to avoid unnecessary overhead in cases where reading a body is not required to provide data.

To configure the interceptor you should import and call configure function. And when you obtain a refresh token you should call authorize, which accepts refresh and access tokens.

   import { configure, authorize } from '@shoutem/fetch-token-intercept';

   ...
   configure(configuration);
   // perform authentication with user credentials against your auth server
   // when you recieve refresh token (and optionally access token) provide them to interceptor lib
   authorize(refreshToken, accessToken);
   ...

User is now logged in with provided refresh token. If refresh token invalidates interceptor will automatically clear both tokens and further requests won't be intercepted. You should redirect user to authentication screen and re-authorize interceptor on successful authentication.

To manually clear tokens you can call clear method. You should call this when user log outs manually to stop fetch interception.

   import { clear } from '@shoutem/fetch-token-intercept';

   ...
   clear();
   ...

API reference

Exports

configure(configuration)

Configures fetch token interceptor with provided configuration object.

authorize(refreshToken, accessToken)

Authorizes fetch token interceptor with provided tokens.

clear()

Clears all tokens from interceptor.

unload()

Completely unloads the library and restores initial state.

isResponseUnauthorized(response)

Utility method which determines if given response should be considered unauthorized. By default, responses with status code 401 are considered unauthorized. You can use this method in isResponseUnauthorized of config object when you want to extend default behaviour.

Tests

$ npm install && npm run test

License

BSD