Client Credentials Grant

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 supports Client Credentials Grant flow in different formats. The first one is in strict adherence to specification for better compatibility. The second one uses JSON request as a more modern and simple way. Read the official OAuth 2.0 specification for more details.

Easy way

The easiest way to test Client Credentials Grant flow is to run through the Authentication Flows (_Auth -> Sandbox -> Client Credentials_).

Configure Client

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

PUT /Client/api-client Accept: text/yaml Content-Type: text/yaml

secret: verysecret grant_types: - client_credentials

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

attribute	options	desc
auth.client\credentials_.token\_format	jwt	use access token in jwt format
auth.client\credentials._access\_token\_expiration	int (seconds)	token expiration time from issued at
auth.client\credentials_.refresh\_token	true/false	enable refresh\_token
auth.client\credentials_.refresh\_token\_expiration	int (seconds)	refresh token expiration time from issued or last usage

yaml

PUT /Client/api-client
Accept: text/yaml
Content-Type: text/yaml

secret: verysecret
grant_types:
  - client_credentials
auth:
  client_credentials:
    access_token_expiration: 600 # 10 minutes
    token_format: jwt
    refresh_token: true
    refresh_token_expiration: 86400 # 1 day

Since by default new client has no access to any resources, you probably want to configure AccessPolicy for this specific client:

yaml

PUT /AccessPolicy/api-client
Accept: text/yaml
Content-Type: text/yaml

engine: allow
link:
  - id: api-client
    resourceType: Client

Get Access Token

The next step is to exchange client id and secret for Access Token.

Using Authorization header {base64(Client.id + ':' + Client.secret)} or by JSON request with client_id and client_secret in body:

yaml

POST /auth/token
Authorization: Basic YXBpLWNsaWVudDp2ZXJ5c2VjcmV0
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials

yaml

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:

status: 200  {  "token_type": "Bearer",  "access_token": "ZjQyNGFhY2EtNTY2MS00NjVjLWEzYmEtMjIwYjFkNDI5Yjhi" }

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

yaml

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:

yaml

GET /Patient
Authorization: Bearer ZjQyNGFhY2EtNTY2MS00NjVjLWEzYmEtMjIwYjFkNDI5Yjhi

curl -H 'Authorization: Bearer ZjQyNGFhY2EtNTY2MS00NjVjLWEzYmEtMjIwYjFkNDI5Yjhi' /Patient

Refresh Access Token

To get new access token using refresh token

yaml

POST /auth/token
Content-Type: application/json

{
  "grant_type": "refresh_token",
  "client_id": "webapp",
  "refresh_token": "eyJhb..PloA"
}

yaml

status: 200

{
  "access_token": "eyJh..D8YA", # new access_token
  "expores_id": 600
}

Revoke Access Token (Close Session)

Aidbox create Session (resource) for each Acce∂ss Token that can be closed with the special endpoint DELETE /Session with the token in the Authorization header:

close-session

yaml

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