Client Credentials Flow

The Admin API uses the OAuth Client Credentials flow to obtain an Access Token. An External Application can use its credentials to directly obtain an Access Token. Once the Access Token expires, the External Application requests a new one when necessary.

The Client Credentials flow requires authenticating with a signed JSON Web Token (JWT) that uses a public key + private key pair.

Obtaining an Access Token

Using the Client Credentials flow requires authenticating to the /token endpoint with a signed JWT that has been signed using a public + private key pair.

Public Key + Private Key

See the Public Key + Private Key topic.

Configuration

See the Configuration topic.

Signed JWT

Authenticating to the /token endpoint requires the developer to create a signed JWT with the following properties:

• jti – a unique id used as a nonce to prevent replay attacks
• aud – this must be the exact URL of the /token endpoint
• sub – the Client ID of the application
• iss – the Client ID of the application
• exp – the timestamp (in milliseconds) when the JWT is no longer valid (this should be no more than 5 minutes in the future)

Example JWT payload

Example JWT Payload

{ 
  "jti": "bfbaaa5b-aa91-45d0-aba2-999d57f08500",
  "aud": "https://banno.com/a/oidc-provider/api/v0/token",
  "sub": "199e6f35-4e9a-482e-b980-b10308aa428a",
  "iss": "199e6f35-4e9a-482e-b980-b10308aa428a",
  "exp": 1606396546977
}

The JWT must be signed with the Private Key. The following algorithms are supported:

1. ES256 - ECDSA using P-256 and SHA-256
2. PS256 - RSASSA-PSS using SHA-256 with MGF1 with SHA-256
3. RS256 - RSASSA-PKCS1-v1_5 using SHA-256

Example of a properly signed JWT

Example Signed JWT

eyJhbGciOiJSUzI1NiIsImtpZCI6Im9wc2RIaUliWVR6WDE1MFRVM0ZiWTJs
NVJIWkppOWxqQVdUcFZ3WFJIbkUifQ.eyJqdGkiOiJ1bmlxdWUgaWQgMTYwN
jM5NjkyMTkzNSIsImF1ZCI6Imh0dHBzOi8vMTI3LjAuMC4xOjg0NDMvYS9va
WRjLXByb3ZpZGVyL2FwaS92MC8iLCJzdWIiOiJjbGllbnRJZCIsImlzcyI6I
mNsaWVudElkIiwiZXhwIjoxNjA2Mzk3MjIxOTM1fQ.iHqIngIZMOc-BZQcjs
WCzZMJJtk4qT40JGeX9IqKYtPQVnc6to1cafU2V8YKamqJKH8RxeZw072klQ
bmgMx05YBmggmRTtdt3kz0Liw87qz2waexDNtB7C5jyCpjVVISandT877F3X
5dct4aLV0J7zPKJaRTCqpRe_ozoU75bHEHIFdlNAXHp9i2VyupA2qaUIindI
GqkeSzFJlCd2zPP9DfcrJ520qvQBL2WAXeTZiUrdGP4z2nD8GDjpNpVZIRbj
I_PQQ-OM5GCmza3qKeYl9fpRYk0_JQiOepYyv9XHKdtwk6T1vgsIr-9kDyFz
TZe5_ZmsVGVV7xtf7esD9-ng

Token Request

Using a properly signed JWT, make an HTTP POST request to the https://banno.com/a/oidc-provider/api/v0/token endpoint.

The HTTP POST should use a content-type of application/x-www-form-urlencoded.

The HTTP POST request body must include the following parameters:

• client_assertion – this value is the signed JWT
• client_assertion_type – the string urn:ietf:params:oauth:client-assertion-type:jwt-bearer
• grant_type – the string client_credentials
• scope – the string openid

The parameters in the request body should be properly encoded.

Access Token Usage and Lifetime

The Authentication Framework - Tokens article has information on the various Tokens.

Command Line Utility

The @jkhy/banno-client-creds-helper command line utility is available via npm. The @jkhy/banno-client-creds-helper demonstrates the Client Credentials flow and can be used to obtain an Access Token.