OAuth Authentication

OAuth is a two-step token process, but it is a common one that has its own standards, so we want to discuss this as its own process.

Sample system has a two-step OAuth authentication process. In the intial request, you need to send a client_id, client_secret and grant_type. The grant type for this authentication is "client_credentials". Often the data on the token request will be urlencoded. The response includes a bearer token which is returned in the access_token field of the response object. In subsequent requests, this token is prefixed with the word Bearer and put into the Authorization header.

How to set up OAuth Authenication in Adapters

Changes to the authentication section of the IAP Service Instance Configuration for the adapter:

• The "client_id" field should include the client_id that is provided from the other system.
• The "client_secret" field should include the client_secret that is provided from the other system.
• The "grant_type" field should be set to "client_credentials".
• The "auth_field" is for where the token is on all subsequent requests so it needs to be set to header.headers.Authorization.
• The "auth_field_format" is the format of the Authorization information on all subsequent requests so it needs to be set to "Bearer {token}".

IAP Service Instance Configuration for Adapter Example

"authentication": {
  "auth_method": "request_token", 
  "username": "username",
  "password": "password",
  "token": "",
  "invalid_token_error": 401,
  "token_timeout": 180000,
  "token_cache": "local", 
  "auth_field": "header.headers.Authorization", 
  "auth_field_format": "Bearer {token}",
  "client_id": "client-id-you-get-for-system",
  "client_secret": "client-secret-you-get-for-system",
  "grant_type": "client_credentials"
},

Changes to Endpoint Configuration for the Adapter

There are also several changes potential required in the endpoint configuration for the adapter. The endpoint configuration for the adapter is in /adapter-home-dir/entities/.system. If the OAuth changes have been contributed back to the adapter repository these changes may already exist. If not and this is an opensource adapter, the Adapter Team would love for you to contribute these changes back.

Changes to Endpoint Configuration - action.json

Changes to the action.json file in the endpoint configuration for the adapter:

• The datatype on the request is no longer JSON. Setting it to URLENCODE means the adapter library will urlencode the body prior to sending it. Urlencoding will make the payload look something like client_id=sdjdajdksj&client_secret=asdajdfklajd&grant_type=client_credentials

action.json Example

{
  "name": "getToken",
  "protocol": "REST",
  "method": "POST",
  "entitypath": "/oauth_token.do",
  "requestSchema": "oAuthTokenRequest.json",
  "responseSchema": "oAuthTokenResponse.json",
  "timeout": 0,
  "sendEmpty": false,
  "requestDatatype": "URLENCODE",
  "responseDatatype": "JSON",
  "headers": {},
  "responseObjects": [
    {
       "type": "default",
       "key": "",
       "mockFile": "mockdatafiles/getToken-default.json"
    }
  ]
},

Note: the request and response schemas are named differently, they do not have to be but whatever the the values are in the action.json must be relative paths to existing files in the endpoint configuration for the adapter.

Changes to Endpoint Configuration - Request Schema

Changes to the oAuthTokenRequest.json file in the endpoint configuration for the adapter:

• This is where you define the new data that is part of the body:
  • grant_type
  • client_secret
  • client_id
  • while this data is now part of the IAP service instance configuration for the adapter it is not yet added to the schema by the builder.

Request Schema Example

{
  "$id": "oAuthTokenRequest.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"
      ],
      "external_name": "ph_request_type"
    },
    "grant_type": {
      "type": "string",
      "description": "type of auth"
      "external_name": "grant_type"
    },
    "client_secret": {
      "type": "string",
      "description": "secret used during login"
      "external_name": "client_secret"
    },
    "client_id": {
      "type": "string",
      "description": "client appreciation id",
      "external_name": "client_id"
    },
    "username": {
      "type": "string",
      "description": "username to login with",
      "external_name": "username"
    },
    "password": {
      "type": "string",
      "description": "password to login with", 
      "external_name": "password"
    }
  },
  "definitions": {}
}

Changes to Endpoint Configuration - Response Schema

Changes to the oAuthTokenResponse.json file in the endpoint configuration for the adapter:

• Changes could include a change to the external name in the token. This tells the adapter where in the response to find the token. In this case it is going to look for the token in the access_token field in the response.

Response Schema Example

{
  "$id": "oAuthTokenResponse.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": {}
}