ConfigureAuthenticationAuthentication methods

Multi-step authentication

Multi-step authentication (MSA) is a verification process that requires two or more sequential steps before the adapter obtains the token needed for subsequent requests. Each step can pass data from its response into the next step’s request.

Configure MSA

MSA is configured entirely 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.

Set auth_method to "multi_step_authentication".

Each step in the authentication sequence is defined as an entry in the multiStepAuthCalls array. Every step can have corresponding schema files in /entities/.system:

  • Request schema: schemaTokenReq_MFA_Step_[number]
  • Response schema: schemaTokenResp_MFA_Step_[number]

After all steps complete, auth_field and auth_field_format define where and how the final token is placed in subsequent requests.

Step fields

FieldDescription
nameA unique name for the step. Other steps reference this step’s response values using this name.
requestFieldsThe fields to include in this step’s request. Field names prefixed with header. are sent as HTTP headers (for example, header.jx-session sends the value as the jx-session request header). All other fields are placed in the request body.
responseFieldsThe fields from this step’s response that are exposed for use by subsequent steps. The value of each field must match the external_name set in the corresponding schemaTokenResp_MFA_Step_[number] file.
successfulResponseCodeThe expected HTTP response code for this step. Intermediate steps may return codes outside the standard success range (200–299, 300–308). Set the expected code here so the adapter does not treat it as an error.

Configure token caching

Use the following properties to control how the final token is cached:

FieldDescription
token_cacheStorage location for the token. Supported values: local (in-memory) or redis.
token_timeoutHow long the token is valid, in milliseconds. When set to a value greater than zero, the token is refreshed each time the timeout elapses. Must be greater than one minute (60000 ms). When set to 0, caching is based on the expiry date returned in the expires attribute of the final step’s response schema.

Example

This example shows a two-step MSA flow. The first step (getSession) authenticates with credentials and receives a session token. The second step (getToken) uses that session token, along with a one-time password, to retrieve the final authorization token.

1"authentication": {
2  "auth_method": "multi_step_authentication",
3  "token_URI_path": "/v3/auth/tokens",
4  "multiStepAuthCalls": [
5    {
6      "name": "getSession",
7      "requestFields": {
8        "username": "Alice",
9        "password": "Alice-secret",
10        "grant_type": "gt-1",
11        "client_secret": "cs-1",
12        "client_id": "cid-1"
13      },
14      "responseFields": {
15        "session": "session"
16      },
17      "successfulResponseCode": 401
18    },
19    {
20      "name": "getToken",
21      "requestFields": {
22        "header.jx-session": "{getSession.responseFields.session}",
23        "timedOneTimePassword": "123456"
24      },
25      "responseFields": {
26        "token": "token"
27      },
28      "successfulResponseCode": 201
29    }
30  ],
31  "auth_field": "header.headers.xsx-authorization",
32  "auth_field_format": "Bearer {token}",
33  "token_cache": "local",
34  "token_timeout": 120000,
35  "invalid_token_error": 401,
36  "auth_logging": true
37}