OAuth authentication

OAuth authentication follows the two-step token pattern but has its own standards. This page covers the client_credentials grant type, a common OAuth flow used for system-to-system authentication.

In a typical OAuth client_credentials flow:

The adapter sends a client_id, client_secret, and grant_type in the initial token request. The request body is usually URL-encoded.
The external system returns a bearer token in the access_token field of the response.
Subsequent requests include this token, prefixed with Bearer, in the Authorization header.

Configure the service instance configuration

Update the authentication section of theItential Platform service instance configuration for the adapter inItential Platform Admin Essentials with the following properties:

Set client_id to the client ID provided by the external system.
Set client_secret to the client secret provided by the external system.
Set grant_type to "client_credentials".
Set auth_field to "header.headers.Authorization" — the location of the token on all subsequent requests.
Set auth_field_format to "Bearer {token}" — the format of the token on all subsequent requests.

1 "authentication": {
2   "auth_method": "request_token",
3   "username": "username",
4   "password": "password",
5   "token": "",
6   "invalid_token_error": 401,
7   "token_timeout": 180000,
8   "token_cache": "local",
9   "auth_field": "header.headers.Authorization",
10   "auth_field_format": "Bearer {token}",
11   "client_id": "client-id-you-get-for-system",
12   "client_secret": "client-secret-you-get-for-system",
13   "grant_type": "client_credentials"
14 }

Configure the endpoint configuration

The endpoint configuration is located at /adapter-home-dir/entities/.system. If OAuth support has already been contributed back to the adapter repository, these changes may already be in place.

If you are using an open-source adapter and make OAuth changes, consider contributing them back to the adapter repository.

action.json

The token request for OAuth uses URLENCODE as the requestDatatype. This causes the adapter library to URL-encode the request body before sending it, producing a payload like:

client_id=sdjdajdksj&client_secret=asdajdfklajd&grant_type=client_credentials

1 {
2   "name": "getToken",
3   "protocol": "REST",
4   "method": "POST",
5   "entitypath": "/oauth_token.do",
6   "requestSchema": "oAuthTokenRequest.json",
7   "responseSchema": "oAuthTokenResponse.json",
8   "timeout": 0,
9   "sendEmpty": false,
10   "requestDatatype": "URLENCODE",
11   "responseDatatype": "JSON",
12   "headers": {},
13   "responseObjects": [
14     {
15       "type": "default",
16       "key": "",
17       "mockFile": "mockdatafiles/getToken-default.json"
18     }
19   ]
20 }

The request and response schemas can be named differently from the defaults, but the values in action.json must be relative paths to existing files in the endpoint configuration.

Request schema

The request schema (oAuthTokenRequest.json) adds grant_type, client_secret, and client_id to the token request body. Although these values are defined in the service instance configuration, Adapter Builder does not add them to the schema automatically.

1 {
2   "$id": "oAuthTokenRequest.json",
3   "type": "object",
4   "schema": "http://json-schema.org/draft-07/schema#",
5   "translate": true,
6   "dynamicfields": true,
7   "properties": {
8     "ph_request_type": {
9       "type": "string",
10       "description": "type of request (internal to adapter)",
11       "default": "getToken",
12       "enum": ["getToken"],
13       "external_name": "ph_request_type"
14     },
15     "grant_type": {
16       "type": "string",
17       "description": "type of auth",
18       "external_name": "grant_type"
19     },
20     "client_secret": {
21       "type": "string",
22       "description": "secret used during login",
23       "external_name": "client_secret"
24     },
25     "client_id": {
26       "type": "string",
27       "description": "client ID",
28       "external_name": "client_id"
29     },
30     "username": {
31       "type": "string",
32       "description": "username to log in with",
33       "external_name": "username"
34     },
35     "password": {
36       "type": "string",
37       "description": "password to log in with",
38       "external_name": "password"
39     }
40   },
41   "definitions": {}
42 }

Response schema

The response schema (oAuthTokenResponse.json) maps the access_token field in the response to token for use by the adapter.

1 {
2   "$id": "oAuthTokenResponse.json",
3   "type": "object",
4   "$schema": "http://json-schema.org/draft-07/schema#",
5   "translate": true,
6   "properties": {
7     "ph_request_type": {
8       "type": "string",
9       "description": "type of request (internal to adapter)",
10       "default": "getToken",
11       "enum": ["getToken"],
12       "external_name": "ph_request_type"
13     },
14     "token": {
15       "type": "string",
16       "description": "the token returned from the system",
17       "external_name": "access_token"
18     }
19   },
20   "definitions": {}
21 }