Client Credentials Grant

Description

The Client Credentials grant is used when applications request an access token to access their own resources, not on behalf of a user (for example, background services and daemons). It must be used only by confidential clients.

Basic scheme

Aidbox OAuth module support Client Credentials Grant flow in different formats. First- Strict adherence to specifications for better compatibility. Second - JSON request as a more modern and simple way. Also we have availability send all data in POST Body. Read official OAuth2.0 specification for more details.

Configure Client

To start use this flow you have to create and configure Client. Minimal required parameters is secret and you have to enable this flow for client by grant_types: ['client_credentials']

create-client-request
PUT /Client/api-client
secret: verysecret
grant_types:
- client_credentials

You also can configure token format and expiration, as well refresh token:

attribute

options

desc

auth.client_credentials.token_format

jwt

use access token in jwt format

auth.client_credentials.token_expiration

int (seconds)

token expiration time from issued at

auth.client_credentials.refresh_token

true/false

enable refresh_token

jwt-token-client
PUT /Client/api-client
secret: verysecret
grant_types:
- client_credentials
auth:
client_credentials:
access_token_expiration: 600
token_format: jwt
refresh_token: true

Probably you want to configure AccessPolicy for this specific client:

policy
PUT /AccessPolicy/api-client
engine: allow
link:
- id: api-client
resourceType: Client

Get Access Token

Next step is exchange client id and secret for Access Token.

Using Basic & form-url-encode:

using-basic
POST /auth/token
Authorization: Basic base64(client.id, client.secret)
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials

Or by JSON request:

json-request
POST /auth/token
Content-Type: application/json
{ "grant_type": "client_credentials",
"client_id": "api-client",
"client_secret": "verysecret"
}

For simple client configuration you will get JSON with access_token in response:

token-response
status: 200
{
"token_type": "Bearer",
"access_token": "ZjQyNGFhY2EtNTY2MS00NjVjLWEzYmEtMjIwYjFkNDI5Yjhi"
}

For JWT with refresh token you will get something like this:

status: 200
{
"token_type": "Bearer",
"expires_in": 3000,
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODEiLCJzdWIiOiJhdXRoLWNsaWVudCIsImlhdCI6MTU1NDQ3MDA3NCwianRpIjoiOWJlMTY1YzMtOTQzZS00NGU0LTkxMWEtYzk1OGY3MWRhMTdkIiwiYXVkIjoiaHR0cDovL3Jlc291cmNlLnNlcnZlci5jb20iLCJleHAiOjE1NTQ0NzMwNzR9.cR9N1Z-pKidENTrtYu5aVADRzAigZM6RvoFAzbeLkBecRcY03j4VVXnqRG1yJo744FvJ0qfetHQ2JTSQFxLrtQ",
"refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODEiLCJzdWIiOiJhdXRoLWNsaWVudCIsImp0aSI6IjliZTE2NWMzLTk0M2UtNDRlNC05MTFhLWM5NThmNzFkYTE3ZCIsInR5cCI6InJlZnJlc2gifQ.lsxtjkW0MVku4lh1W-vOEz-4wJjRN-Dkmbt2NpjezPAGj-z7FBGVyKVfH8Q0nY0smuvUnkXEAxajIb_zZdXQtw"
}

Audience

If you use JWT token format and provide in token request additional parameter audience, resulting token will set aud claim into value you've sent.

The "aud" (audience) claim identifies the recipients that the JWT is
intended for. Each principal intended to process the JWT MUST
identify itself with a value in the audience claim. If the principal
processing the claim does not identify itself with a value in the
"aud" claim when this claim is present, then the JWT MUST be
rejected. In the general case, the "aud" value is an array of case-
sensitive strings, each containing a StringOrURI value. In the
special case when the JWT has one audience, the "aud" value MAY be a
single case-sensitive string containing a StringOrURI value. The
interpretation of audience values is generally application specific.

Using Access Token

You can use access token in Authorization header for Aidbox API calls:

authorized-request
GET /Patient
Authorization: Bearer ZjQyNGFhY2EtNTY2MS00NjVjLWEzYmEtMjIwYjFkNDI5Yjhi
curl -H 'Authorization: Bearer ZjQyNGFhY2EtNTY2MS00NjVjLWEzYmEtMjIwYjFkNDI5Yjhi' /Patient

Revoke Access Token (Close Session)

Aidbox create Session (resource) for each Access Token, which can be closed with special endpoint DELETE /Session with token in Authorization header:

close-session
DELETE /Session
Authorization: Bearer ZjQyNGFhY2EtNTY2MS00NjVjLWEzYmEtMjIwYjFkNDI5Yjhi

Session is just Resource and you can inspect and manipulate with sessions by standard Search & CRUD API for example get all sessions - GET /Session

Auth Sandbox