Authorization Code Grant

Description

The Authorization Code Grant is an OAuth 2.0 flow that regular web apps use in order to access an API, typically as web applications with backend and frontend (browser-based SPA, for example).
This flow doesn't use client-secret due to security considerations - frontend application source code is available in a browser. Instead, user authorizes the application and gets redirected back to it with a temporary access code in the URL. Application exchanges that code for the access token. For more detailed information read OAuth 2.0 specification.
Basic scheme

Configure Client

The first step is to configure Client for Authorization Grant with secret and redirect_uri, as well code grant type:
Secret
PKCE
1
PUT /Client/webapp
2
Accept: text/yaml
3
Content-Type: text/yaml
4
​
5
secret: verysecret
6
first_party: true
7
grant_types:
8
- code
9
auth:
10
authorization_code:
11
redirect_uri: 'http://myapp.app'
12
access_token_expiration: 360
13
token_format: jwt
14
secret_required: true
15
refresh_token: true
Copied!
1
PUT /Client/webapp
2
Accept: text/yaml
3
Content-Type: text/yaml
4
​
5
secret: verysecret
6
first_party: true
7
grant_types:
8
- code
9
auth:
10
authorization_code:
11
redirect_uri: 'http://myapp.app'
12
access_token_expiration: 360
13
token_format: jwt
14
pkce: true
15
refresh_token: true
Copied!
Client will act on behalf of the user, which means Access Policies should be configured for User, not for Client.
You can configure Client for JWT tokens, set token expiration and enable refresh token:
auth.authorization_code.
options
desc
token_format
jwt
use access token in jwt format
token_expiration
int (seconds)
token expiration time from issued at
refresh_token
true/false
enable refresh_token
secret_required
true/false
require secret for token
pkce
true/false
enable PKCE flow
If you want to use Authorization Code Grant for Single Page Application you do not need to set the secret attribute!
If your application is a major consumer of Aidbox API, you can set first_party attribute as true. This means that the same User Session will be shared between Aidbox and client, so if you close the client session, Aidbox User Session will be closed too.

Get Code

The next step is to query an authorize endpoint with client_id and response_type with value code:
Secret
PKCE
1
POST /auth/authorize
2
Content-Type: application/json
3
​
4
{
5
"response_type": "code",
6
"client_id": "webapp",
7
"redirect_uri": "http://myapp.app",
8
"state": "somestate"
9
}
Copied!
1
POST /auth/authorize
2
Content-Type: application/json
3
​
4
{
5
"response_type": "code",
6
"client_id": "webapp",
7
"redirect_uri": "http://myapp.app",
8
"state": "somestate",
9
"code_challenge": "code_challenge",
10
"code_challenge_method": "S256"
11
}
Copied!
To keep your client stateless, you can send a state parameter with arbitrary content, which will be sent back in the redirect response.
If users are not logged in, they will see the default login screen.
If a client is not first_party or user not yet granted permissions to client, a user will see the grant page:
If a client granted permissions, a user agent will be redirected to url configured in Client.auth.authorization_code.redirect_uri with the authorization code parameter.
1
<redirect_uri>?code=****&state=***
Copied!

Get Access Token

With this code and client secret, you can request for Access Token withgrant_type: authorization_code.
Secret
PKCE
1
POST /auth/token
2
Content-Type: application/json
3
​
4
{
5
"client_id": "webapp",
6
"client_secret": "verysecret",
7
"code": <code>,
8
"grant_type": "authorization_code"
9
}
Copied!
1
POST /auth/token
2
Content-Type: application/json
3
​
4
{
5
"client_id": "webapp",
6
"code_verifier": <code_verifier>,
7
"code": <code>,
8
"grant_type": "authorization_code"
9
}
Copied!
If provided code is accurate, you will get access token, user information and refresh token (if enabled):
token-response
1
status: 200
2
​
3
{
4
"token_type": "Bearer",
5
"expires_in": 3600,
6
"access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODEiLCJzdWIiOiJ1c2VyIiwiaWF0IjoxNTU0NDczOTk3LCJqdGkiOiI0ZWUwZDY2MS0wZjEyLTRlZmItOTBiOS1jY2RmMzhlMDhkM2QiLCJhdWQiOiJodHRwOi8vcmVzb3VyY2Uuc2VydmVyLmNvbSIsImV4cCI6MTU1NDQ3NzU5N30.lCdwkqzFWOe4IcXPC1dIB8v7aoZdJ0fBoIKlzCRFBgv4YndSJxGoJOvIPq2rGMQl7KG8uxGU0jkUVlKxOtD8YA",
7
"refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODEiLCJzdWIiOiJwYXNzd29yZC1jbGllbnQiLCJqdGkiOiI0ZWUwZDY2MS0wZjEyLTRlZmItOTBiOS1jY2RmMzhlMDhkM2QiLCJ0eXAiOiJyZWZyZXNoIn0.XWHYpw0DysrqQqMNhqTPSdNamBM4ZDUAgh_VupSa7rkzdJ3uZXqesoAo_5y1naJZ31S92-DjPKtPEAyD_8PloA",
8
"userinfo": {
9
"email": "[email protected]",
10
"id": "user",
11
"resourceType": "User",
12
}
13
}
Copied!

Use Access Token

You can use access token in the 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 creates a Session resource for each Access Token which can be closed with a special endpoint DELETE /Session with the token in Authorization header:
close-session
1
DELETE /Session
2
Authorization: Bearer ZjQyNGFhY2EtNTY2MS00NjVjLWEzYmEtMjIwYjFkNDI5Yjhi
Copied!
Session is just a resource and you can inspect and manipulate sessions with standard Search & CRUD API. For example, use GET /Session to get all sessions.

Auth Sandbox Demo

​
Last modified 21h ago