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.
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.
TBD
- Node.js 14+ is required.
To install via NPM:
npm install --save @bedrock/oauth2-client
To install locally (for development):
git clone https://github.com/digitalbazaar/bedrock-oauth2-client.git
cd bedrock-oauth2-client
npm install
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'));
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});
});
}
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.
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.
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
See the contribute file!
PRs accepted.
If editing the Readme, please conform to the standard-readme specification.
Commercial support for this library is available upon request from Digital Bazaar: support@digitalbazaar.com
Apache-2.0 © Digital Bazaar