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 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.

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']
create new api client
1
PUT /Client/api-client
2
Accept: text/yaml
3
Content-Type: text/yaml
4
5
secret: verysecret
6
grant_types:
7
- client_credentials
Copied!
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.token_expiration
int (seconds)
token expiration time from issued at
auth.client_credentials.refresh_token
true/false
enable refresh_token
create new api client
1
PUT /Client/api-client
2
Accept: text/yaml
3
Content-Type: text/yaml
4
5
secret: verysecret
6
grant_types:
7
- client_credentials
8
auth:
9
client_credentials:
10
access_token_expiration: 600
11
token_format: jwt
12
refresh_token: true
Copied!
Since by default new client has no access to any resources, you probably want to configure AccessPolicy for this specific client:
create policy
1
PUT /AccessPolicy/api-client
2
Accept: text/yaml
3
Content-Type: text/yaml
4
5
engine: allow
6
link:
7
- id: api-client
8
resourceType: Client
Copied!

Get Access Token

The next step is to exchange client id and secret for Access Token.
Using Basic & form-url-encoded:
using-basic
1
POST /auth/token
2
Authorization: Basic base64(client.id, client.secret)
3
Content-Type: application/x-www-form-urlencoded
4
5
grant_type=client_credentials
Copied!
Or by JSON request:
json-request
1
POST /auth/token
2
Content-Type: application/json
3
4
{ "grant_type": "client_credentials",
5
"client_id": "api-client",
6
"client_secret": "verysecret"
7
}
Copied!
For simple client configuration you will get JSON with access_token in response:
token-response
1
status: 200
2
3
{
4
"token_type": "Bearer",
5
"access_token": "ZjQyNGFhY2EtNTY2MS00NjVjLWEzYmEtMjIwYjFkNDI5Yjhi"
6
}
Copied!
For JWT with refresh token you will get something like this:
1
status: 200
2
3
{
4
"token_type": "Bearer",
5
"expires_in": 3000,
6
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODEiLCJzdWIiOiJhdXRoLWNsaWVudCIsImlhdCI6MTU1NDQ3MDA3NCwianRpIjoiOWJlMTY1YzMtOTQzZS00NGU0LTkxMWEtYzk1OGY3MWRhMTdkIiwiYXVkIjoiaHR0cDovL3Jlc291cmNlLnNlcnZlci5jb20iLCJleHAiOjE1NTQ0NzMwNzR9.cR9N1Z-pKidENTrtYu5aVADRzAigZM6RvoFAzbeLkBecRcY03j4VVXnqRG1yJo744FvJ0qfetHQ2JTSQFxLrtQ",
7
"refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODEiLCJzdWIiOiJhdXRoLWNsaWVudCIsImp0aSI6IjliZTE2NWMzLTk0M2UtNDRlNC05MTFhLWM5NThmNzFkYTE3ZCIsInR5cCI6InJlZnJlc2gifQ.lsxtjkW0MVku4lh1W-vOEz-4wJjRN-Dkmbt2NpjezPAGj-z7FBGVyKVfH8Q0nY0smuvUnkXEAxajIb_zZdXQtw"
8
}
Copied!

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.
1
The "aud" (audience) claim identifies the recipients that the JWT is
2
intended for. Each principal intended to process the JWT MUST
3
identify itself with a value in the audience claim. If the principal
4
processing the claim does not identify itself with a value in the
5
"aud" claim when this claim is present, then the JWT MUST be
6
rejected. In the general case, the "aud" value is an array of case-
7
sensitive strings, each containing a StringOrURI value. In the
8
special case when the JWT has one audience, the "aud" value MAY be a
9
single case-sensitive string containing a StringOrURI value. The
10
interpretation of audience values is generally application specific.
Copied!

Using Access Token

You can use access token in Authorization header for Aidbox API calls:
authorized-request
1
GET /Patient
2
Authorization: Bearer ZjQyNGFhY2EtNTY2MS00NjVjLWEzYmEtMjIwYjFkNDI5Yjhi
Copied!
1
curl -H 'Authorization: Bearer ZjQyNGFhY2EtNTY2MS00NjVjLWEzYmEtMjIwYjFkNDI5Yjhi' /Patient
Copied!

Revoke Access Token (Close Session)

Aidbox create Session (resource) for each Access Token that can be closed with the special endpoint DELETE /Session with the token in the Authorization header:
close-session
1
DELETE /Session
2
Authorization: Bearer ZjQyNGFhY2EtNTY2MS00NjVjLWEzYmEtMjIwYjFkNDI5Yjhi
Copied!
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