Bedrock OAuth 2.0 Client (@bedrock/oauth2-client)

A bedrock module that creates and manages an OAuth2 client, that will make it easy to make http-client API calls to OAuth2-protected endpoints.

Table of Contents

• Background
• Security
• Install
• Usage
• Contribute
• Commercial Support
• License

Background

A Bedrock helper library intended to work with OAuth 2.0 bearer token protected API endpoints (see for example authorize-access-token-middleware). For use with client_credentials grant types only, for Server-to-Server use cases.

• RFC6749 The OAuth 2.0 Authorization Framework specification.

Security

TBD

Install

• Node.js 14+ is required.

NPM

To install via NPM:

npm install --save @bedrock/oauth2-client

Development

To install locally (for development):

git clone https://github.com/digitalbazaar/bedrock-oauth2-client.git
cd bedrock-oauth2-client
npm install

Usage

Configuration

Create a configs/authorization.js config file. For example:

import * as bedrock from '@bedrock/core';
const {config} = bedrock;

config['your-bedrock-project'].authorization = [{
  issuer: config['your-bedrock-project'].services.issuerUrl,
  protocol: 'oauth2_client_grant',
  // Pre-registered CLIENT_ID and CLIENT_SECRET
  client_id: '...',
  client_secret: '...',
  // API endpoint to make a Client Credentials grant POST request to
  token_endpoint: `${config['your-bedrock-project'].services.issuerUrl}/token`,
  pkce: false,
  grant_type: 'client_credentials',
  scope: ['your.custom.scope']
}];

And add the corresponding entry to lib/config.js:

await import(path.join(config.paths.config, 'authorization.js'));

Requesting an Access Token on startup

On the bedrock.start event, for example in lib/config.js, request the access token from the required issuer.

if(!process.env.CI) {
  bedrock.events.on('bedrock.start', async () => {
    const issuer = config['bedrock-oauth2-client'].services.issuerUrl;
    config['bedrock-oauth2-client'].exampleIssuerOAuth2Access.accessToken =
      await refreshAccessToken({issuer});
  });
}

On Access Token Expiration/Revocation

Fetching a new access token on server startup (and re-authorizing another access token when the LRU Cache expires) should prevent tokens from expiring. However, there are other events beyond the client control -- issuer keys being rotated, scopes being changed or revoked, etc. For these cases, you also need automated logic that tries to refresh an access token if it encounters an appropriate error.

When to Retry

If error is invalid_token AND name is ConstraintError (this covers Expired, Revoked, and Issuer Key Rotated cases), check to see if max number of retries is exceeded (for that issuer). If not, retry the authorization flow and fetch another access token.

If name is DataError or on any other error encountered during authorization flow -- do not retry. Continue throwing a 503 Service Unavailable error any time an access token is required for this issuer.

Expanded Errors

Example OAuth 2 error response (the error, error_description and error_uri fields are dictated by the OAuth 2.0 spec, and the name property is Bedrock-specific):

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="invalid_token"
  error_description="The access token expired"
Content-type: application/json

{
  "error": "invalid_token",
  "error_description": "The access token expired",
  "name": "ConstraintError"
}

Bedrock-specific invalid_token conditions:

• Expired - ConstraintError
• Not found - NotFoundError
• Malformed JSON - DataError
• Malformed JWT (access token) - DataError
• Invalid signature (issuer key rotated, for example) - ConstraintError (was: DataError)
• Revoked - ConstraintError

Contribute

See the contribute file!

PRs accepted.

If editing the Readme, please conform to the standard-readme specification.

Commercial Support

Commercial support for this library is available upon request from Digital Bazaar: [email protected]

License

Apache-2.0 © Digital Bazaar