Bedrock OAuth2 Token Request Handler (@digitalbazaar/oauth2-token-endpoint-handler)

OAuth2 Token endpoint handler for custom authorization servers.

Table of Contents

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

Background

Limitations / design constraints:

• Only supports the client_credentials grant.
• Only supports client_secret_post endpoint authentication method.
• Does not support Refresh Tokens (clients can just perform the token exchange again, when their original Access Token expires).

Inspired by:

• oauth2orize and @passport-next/oauth2orize
• oauth2orize-jwt-bearer
• node-oidc-provider

Relevant specifications:

• OAuth 2.0 Authorization Framework
• Resource Indicators for OAuth 2.0

Security

TBD

Install

• Node.js >= 16 is required.

To install locally (for development):

git clone https://github.com/digitalbazaar/oauth2-token-endpoint-handler.git
cd oauth2-token-endpoint-handler
npm install

Usage

import {tokenExchangeHandler} from '@digitalbazaar/oauth2-token-endpoint-handler';

app.post('/token',
  // ... make sure to mount url-encoded body parser such as express.urlencoded()
  tokenExchangeHandler({
    defaults: {
      // (Optional) token expiration in seconds. Defaults to 2 weeks
      defaultMaxAge: 1209600
    },
    logger: console,
    getClient: async ({clientId}) => {
      // callback to load client from the db, then:
      return {client};
    },
    authenticateClient: async ({client, clientSecret}) => {
      // callback to authenticate client (compare hash of clientSecret to
      // what's stored, etc).
    },
    issue: async ({client, resource, scopeRequested, body, defaultMaxAge}) => {
      // callback to issue JWT access token
      return {accessToken, expiresIn};
    }
  })
);

Example request:

POST /token HTTP/1.1
Host: as.example.com
Content-Type: application/x-www-form-urlencoded

client_id=s6BhdRkqt3
&client_secret=7Fjfp0ZBr1KtDRbnfVdmIw
&grant_type=client_credentials
&scope=some.resource.read
&resource=https%3A%2F%2Fcalendar.example.com%2F
&resource=https%3A%2F%2Fcontacts.example.com%2F

Example response:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
  "access_token": "eyJhbGciOiJFUzI1NiIsImtpZCI6Ijc3In0.eyJpc3MiOiJodHRwOi8vYXV0aG9yaXphdGlvbi1zZXJ2ZXIuZXhhbXBsZS5jb20iLCJzdWIiOiJfX2JfYyIsImV4cCI6MTU4ODQyMDgwMCwic2NvcGUiOiJjYWxlbmRhciIsImF1ZCI6Imh0dHBzOi8vY2FsLmV4YW1wbGUuY29tLyJ9.nNWJ2dXSxaDRdMUKlzs-cYIj8MDoM6Gy7pf_sKrLGsAFf1C2bDhB60DQfW1DZL5npdko1_Mmk5sUfzkiQNVpYw",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "some.resource.read"
}

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

New BSD License (3-clause) © Digital Bazaar