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 attacksaud
– this must be the exact URL of the/token
endpointsub
– theClient ID
of the applicationiss
– theClient ID
of the applicationexp
– 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:
- ES256 - ECDSA using P-256 and SHA-256
- PS256 - RSASSA-PSS using SHA-256 with MGF1 with SHA-256
- 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 JWTclient_assertion_type
– the stringurn:ietf:params:oauth:client-assertion-type:jwt-bearer
grant_type
– the stringclient_credentials
scope
– the stringopenid
The parameters in the request body should be properly encoded.
A successful token request will have a response with a JSON payload containing an
Access Token
.
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
.