Client Credentials Grant
Aidbox supports machine to machine (m2m) authentication via client credentials oAuth 2.0 flow
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.
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
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 |
create new api client
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:
create policy
PUT /AccessPolicy/api-client
Accept: text/yaml
Content-Type: text/yaml
engine: allow
link:
- id: api-client
resourceType: Client
The next step is to exchange client id and secret for Access Token.
Using Basic & form-url-encoded:
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"
}
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 isintended for. Each principal intended to process the JWT MUSTidentify itself with a value in the audience claim. If the principalprocessing the claim does not identify itself with a value in the"aud" claim when this claim is present, then the JWT MUST berejected. In the general case, the "aud" value is an array of case-sensitive strings, each containing a StringOrURI value. In thespecial case when the JWT has one audience, the "aud" value MAY be asingle case-sensitive string containing a StringOrURI value. Theinterpretation of audience values is generally application specific.
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
To get new access token using refresh token
request
response
POST /auth/token
Content-Type: application/json
{
"grant_type": "refresh_token",
"client_id": "webapp",
"refresh_token": "eyJhb..PloA"
}
status: 200
{
"access_token": "eyJh..D8YA", # new access_token
"expores_id": 600
}
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
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 /SessionLast modified 18d ago