Two Step Token

The dynamic Two Step Token process is one of the more common methods for API authentication between systems and has many different varieties which are discussed throughout the authentication articles. Attributes of standard Two Step Token authentication are:

• A username and password to authenticate with the system are provided in the body of an initial token request.
• The user is authenticated by the system which will return a token in the response body.
• This token will then be used in subsequent requests to the system by placing it into a header in the request.

How to set up Two Step Token in Adapters

Two-step token is handled in both the IAP Service Instance Configuration for the adapter and in the adapter endpoint configuration within the .system entity.

You can find the IAP Service Instance Configuration for the adapter within IAP Admin Essentials and the properties we are talking about are in the authentication section. The authentication section includes other properties that are described in detail in the IAP Service Instance Configuration articles.

You can find the endpoint configuration for the adapter within the adapter files on the IAP server. The authentication files are located in the /adapter-home-dir/entities/.system directory.

Two Step Token in IAP Service Instance Configuration for the Adapter

Example Two Step Token in IAP Service Instance Configuration for the Adapter

"authentication": {
  "auth_method": "request_token",
  "username": "systemuser",
  "password": "systempassword", 
  "token_timeout": 180000,
  "token_cache": "local",
  "invalid_token_error": 401,
  "auth_field": "header.headers.Authorization",
  "auth_field_format": "{token}" 
},

Two Step Token in the Endpoint Configuration for the Adapter

Here are some other key pieces of information to know when the two-step token is handled in the .system entity (located at /adapter-home-dir/entities/.system:

Action.json File - The action.json file tells the Adapter Library how it is going to get the token. The information in the action is:

action.json Example

{
  "name": "getToken", 
  "protocol": "REST",
  "method": "POST",  
  "entitypath": "/api/{version}/authentication/signin",
  "requestSchema": "schemaTokenReq.json",
  "responseSchema": "schemaTokenResp.json", 
  "timeout": 0,
  "sendEmpty": false,
  "requestDatatype": "JSON",
  "responseDatatype": "JSON",
  "headers": {
    "Accept": "*/*"
  },
  "sso": {
    "protocol": "",
    "host": "",
    "port": 0
  },
  "responseObjects": [
    {
      "type": "default",
      "key": "",
      "mockFile": "mockdatafiles/gettoken.json"
    }
  ]
},

Request Schema File - The schemaTokenReq.json file (as named in the action.json) tells the Adapter Library what data should be included in the token request and what fields the data should be in.

Most of the data in this file should be unchanged. The fields that you can alter are mentioned here:

Other fields may also be added to this schema for client_id, client_secret and grant_type. They should be similar to the username and password to take advantage of information in the IAP Service Instance Configuration for the adapter. Additional static data sent on the request can be added to the schema and have default data that will be passed with the request.

Request Schema Example

{
  "$id": "reqTokenSchema.json",
  "type": "object", 
  "schema": "http://json-schema.org/draft-07/schema#",
  "translate": true,
  "dynamicfields": true,
  "properties": {
    "ph_request_type": { 
      "type": "string", 
      "description": "type of request(internal to adapter)",
      "default": "getToken",
      "enum": [
        "getToken",
        "healthcheck"
      ],
      "external_name": "ph_request_type"
    },  
    "username": {
      "type": "string",
      "description": "username to login with",
      "external_name": "user"
    },
    "password": {
      "type": "string",
      "decription": "password to login with", 
      "external_name": "passwd"
    }
  },
  "definitions": {}
}

Response Schema File - The schemaTokenResp.json file (as named in the action.json) tells the Adapter Library what data is included in the token response and what field the token should be in.

Most of the data in this file should be unchanged. The fields that you can alter are mentioned here:

Response Schema Example

{
  "$id": "respTokenSchema.json",
  "type": "object", 
  "$schema": "http://json-schema.org/draft-07/schema#",
  "translate": true,
  "properties": {
    "ph_request_type": {
      "type": "string", 
      "description": "type of request(internal to adapter)",
      "default": "getToken",
      "enum": [
        "getToken"
      ],
      "external_name": "ph_request_type"
    }, 
    "token": {
      "type": "string",
      "description": "the token returned from system",
      "external_name": "access_token"
    }
  },
  "definitions": {}
}

Other Options for Two Step Token

There are many variations of two-step token. The adapters service instance and entity configurations are flexible enough to handle many variations including:

Other Options Examples

Sample Properties

"authentication": {
  "auth_method": "request_token",
  "username": "systemuser",
  "password": "systempassword", 
  "token_timeout": 3600000,
  "token_cache": "local",
  "invalid_token_error": 401,
  "auth_field": "header.headers.X-AUTH-TOKEN",
  "auth_field_format": "Bearer {token}" 
},

action.json Example

{
  "name": "getToken", 
  "protocol": "REST",
  "method": "POST",  
  "entitypath": "/api/{version}/authentication/signin",
  "requestSchema": "schemaTokenReq.json",
  "responseSchema": "schemaTokenResp.json", 
  "timeout": 0,
  "sendEmpty": false,
  "requestDatatype": "URLENCODE",
  "responseDatatype": "PLAIN",
  "headers": {
    "Accept": "*/*"
  },
  "sso": {
    "protocol": "https",
    "host": "DNSname or IP",
    "port": 443
  },
  "responseObjects": [
    {
      "type": "default",
      "key": "",
      "mockFile": "mockdatafiles/gettoken.json"
    }
  ]
},