ConfigureAuthenticationAuthentication methods

Two-step token authentication

Two-step token authentication is one of the most common API authentication methods. The adapter sends credentials in an initial request and receives a token, which it then uses in all subsequent requests.

In standard two-step token authentication:

  1. A username and password are sent in the body of an initial token request.
  2. The external system authenticates the credentials and returns a token in the response body.
  3. The token is placed in a header field on all subsequent requests.

Configure the service instance configuration

Two-step token authentication requires changes in two places: theItential Platform service instance configuration and the adapter’s endpoint configuration in the .system entity. This section covers the service instance configuration.

The relevant properties are in the authentication section of theItential Platform service instance configuration for the adapter, accessible throughItential Platform Admin Essentials. For a full description of all authentication properties, see Service instance configuration.

PropertyDescription
auth_methodSet to "request_token". Provide the username and password in their respective properties. The password field can be encrypted using Itential Platform’s encryption.
auth_fieldThe location where the token is placed on subsequent requests — not the initial token request. Headers are the most common placement. For the Authorization header, use header.headers.Authorization.
auth_field_formatThe format of the token on subsequent requests — not the initial token request. Use {token} as the variable.
token_timeoutHow long the token is valid, in milliseconds. Setting this prevents the adapter from performing the two-step exchange on every call.
token_cacheSet to local. The adapter caches the token in memory.
invalid_token_errorThe HTTP error code the external system returns when the token is invalid (typically 401). When this error is received, the adapter automatically requests a new token and retries the original call.

Example

1"authentication": {
2  "auth_method": "request_token",
3  "username": "systemuser",
4  "password": "systempassword",
5  "token_timeout": 180000,
6  "token_cache": "local",
7  "invalid_token_error": 401,
8  "auth_field": "header.headers.Authorization",
9  "auth_field_format": "{token}"
10}

Configure the endpoint configuration

The endpoint configuration for the adapter is located at /adapter-home-dir/entities/.system. This directory contains the action.json file and the request and response schema files that define how the adapter acquires a token.

action.json

The action.json file tells the adapter library how to make the token request.

PropertyDescription
nameMust be getToken.
protocolAlways REST.
methodThe HTTP method for the token request — typically POST or GET.
entitypathThe path for the token request. Supports global adapter variables such as {base_path} and {version}.
requestSchemaRelative path to the request schema file.
responseSchemaRelative path to the response schema file.
timeoutOptional timeout override for this call, if different from the global attempt_timeout.
sendEmptyWhether to send a body when there is no data to include.
requestDatatypeHow data is sent to the external system. Common values: JSON, URLENCODE.
responseDatatypeHow data is returned to the adapter. Common values: JSON, PLAIN.
headersAdditional headers to include with the token request. Can also override automatic adapter headers.
ssoAn alternate host to authenticate against. Provide protocol, host, and port when authentication is handled by a different server than the one defined in the service instance configuration.
responseObjectsHow to handle the token response and where to find mock data for stub mode.
1{
2  "name": "getToken",
3  "protocol": "REST",
4  "method": "POST",
5  "entitypath": "/api/{version}/authentication/signin",
6  "requestSchema": "schemaTokenReq.json",
7  "responseSchema": "schemaTokenResp.json",
8  "timeout": 0,
9  "sendEmpty": false,
10  "requestDatatype": "JSON",
11  "responseDatatype": "JSON",
12  "headers": {
13    "Accept": "*/*"
14  },
15  "sso": {
16    "protocol": "",
17    "host": "",
18    "port": 0
19  },
20  "responseObjects": [
21    {
22      "type": "default",
23      "key": "",
24      "mockFile": "mockdatafiles/gettoken.json"
25    }
26  ]
27}

Request schema

The request schema (schemaTokenReq.json) defines the data sent in the token request. Most fields should remain unchanged. The fields most commonly modified are:

PropertyDescription
translateSet to true whenever field names need to be translated (for example, username → user).
dynamicfieldsSet to true to allow fields not defined in the schema to be included in the request.
usernameMaps to the username in the service instance configuration. Do not change the property name. Change only external_name to match what the external system expects (common values: username, user, login).
passwordMaps to the password in the service instance configuration. Do not change the property name. Change only external_name to match what the external system expects (common values: password, passwd, pwd).

You can also add client_id, client_secret, and grant_type fields following the same pattern as username and password. Additional static fields with default values can also be added to send fixed data with every token request.

1{
2  "$id": "reqTokenSchema.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", "healthcheck"],
13      "external_name": "ph_request_type"
14    },
15    "username": {
16      "type": "string",
17      "description": "username to log in with",
18      "external_name": "user"
19    },
20    "password": {
21      "type": "string",
22      "description": "password to log in with",
23      "external_name": "passwd"
24    }
25  },
26  "definitions": {}
27}

Response schema

The response schema (schemaTokenResp.json) defines the data extracted from the token response. Most fields should remain unchanged. The fields most commonly modified are:

PropertyDescription
translateSet to true whenever field names need to be translated (for example, access_token → token).
dynamicfieldsSet to true to allow fields not defined in the schema to be included.
tokenDefines where the token is found in the response. Change external_name to match the field name the external system uses (common values: token, access_token).
tokenp2Defines where a secondary value is found in the response, when needed. Change external_name to match the field name (common values: session_id).
1{
2  "$id": "respTokenSchema.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}

Variations

Two-step token has many variations. The following table describes common options and how to configure them.

VariationConfiguration
Token in a different header fieldSet auth_field to "header.headers.X-AUTH-TOKEN".
Token in the URL path (before the ?)Set auth_field to "urlpath".
Token in the URL query (after the ?)Set auth_field to "url".
Token in the request bodySet auth_field to "body.field".
Different token formatSet auth_field_format to "{token}" or "Bearer {token}".
Different token lifetimeAdjust token_timeout to the appropriate value in milliseconds.
URL-encoded token requestSet requestDatatype to URLENCODE. Supported values: JSON, XML, PLAIN, FORM, URLENCODE, URLQUERY.
Non-JSON token responseSet responseDatatype to the appropriate value. Supported values: JSON, XML, PLAIN, XML2JSON.
Field names differ from defaultsUpdate external_name in schemaTokenReq.json or schemaTokenResp.json.
Override default headersSpecify header overrides in the headers object of action.json, for example "Accept": "*/*".
Authenticate against a different serverPopulate the sso object in action.json with the protocol, host, and port of the authentication server.

Example: token in a custom header with URL-encoded request and SSO server

Service instance configuration

1"authentication": {
2  "auth_method": "request_token",
3  "username": "systemuser",
4  "password": "systempassword",
5  "token_timeout": 3600000,
6  "token_cache": "local",
7  "invalid_token_error": 401,
8  "auth_field": "header.headers.X-AUTH-TOKEN",
9  "auth_field_format": "Bearer {token}"
10}

action.json

1{
2  "name": "getToken",
3  "protocol": "REST",
4  "method": "POST",
5  "entitypath": "/api/{version}/authentication/signin",
6  "requestSchema": "schemaTokenReq.json",
7  "responseSchema": "schemaTokenResp.json",
8  "timeout": 0,
9  "sendEmpty": false,
10  "requestDatatype": "URLENCODE",
11  "responseDatatype": "PLAIN",
12  "headers": {
13    "Accept": "*/*"
14  },
15  "sso": {
16    "protocol": "https",
17    "host": "DNSname or IP",
18    "port": 443
19  },
20  "responseObjects": [
21    {
22      "type": "default",
23      "key": "",
24      "mockFile": "mockdatafiles/gettoken.json"
25    }
26  ]
27}