Authentication Properties
  • 17 Nov 2022
  • Dark
  • PDF

Authentication Properties

  • Dark
  • PDF

Article summary


All authentication properties are contained within the authentication object in the IAP Service Instance Configuration for the adapter. If you are using request_token, there is also an action (getToken) defined in the .system entity that is used to define the token request. The path to the file is adapter-home-dir/enitites/.system/action.json.

Property Type Required Description
auth_method enum yes The authentication method used for the external system. The following methods are supported:

basic user_password: Authentication will always require a username and password.

static_token: Authentication is always done with a static token provided in the token property.

request_token: Authentication is initially done with a credentials which will return a token that can be used in subsequent requests.

no_authentication: No authentication is required to talk to the system or authentication will be done outside of the adapter library (e.g. custom within the adapter.js).
username string yes (basic user_password & request_token) The username for authenticating with the other system.
password string yes (basic user_password & request_token) The password for authenticating with the other system. It can be encrypted through the adapter encryptProperty method or through IAP. Note: You must use encyptProperty of the adapter that will be using the property.
token string yes (static_token only) The token to use when authenticating with the external system. This is only used when the authentication is static token and thus the token is known.
token_timeout integer no -> -1 How long a token is valid before it will timeout when using dynamic tokens. Measured in milliseconds. The system will request a new token prior to the defined timeout. Special values include:

-1 – Always get a new token.

0 – Use the expiration time returned with the token. Must be defined in the token schema response and have an acceptable format.
token_cache enum no -> local Tells the adapter where to store the token(s) that it has to the other system.

Local: In memory. Lost if adapter restarts.

Redis: Preserved across adapter restart. Not typically utilized due to IAP changes.
invalid_token_error integer no -> 401 Error returned when a request is rejected with invalid token. Adapter will request new token and automatically resubmit the call to the other system in an attempt to satisfy the original request.
auth_field string yes (except no_authentication) Defines the request field the authentication (e.g., token or basic auth credentials) needs to be placed in for all subsequent calls in order for the calls to satisfy the authentication requirements of the other system. This is not where any information is placed on the actual calls to get authentication information.
auth_field_format string yes (except no_authentication) The format of the field in the request that contains the authentication information. You can specify a combination of text and dynamic information.

Example: If you have b64 encoding for Basic Auth, this property may look like: {b64}Basic {username}:{password}{/b64}. This tells the adapter to b64 encode a string that will look like “Basic myuser:mypasswd”.

You can also combine text with tokens by setting this property to Token {token} or Bearer {token}.
auth_logging boolean no -> false This property turns on logging that includes the authenication information.

Note: Only use auth_logging when you are debugging authenication issues. It will log out sensitive information such as credentials.
client_id string no -> "" Some types of OAuth may require you to provide client identifcation. If client identification is required, this is the field where you would provide that information.
client_secret string no -> "" Some types of OAuth may require you to provide the client secret. If the client secret is required, this is the field where you would provide that information.
grant_type string no -> "" Some types of OAuth may require you to provide the grant type. If the grant type is required, this is the field where you would provide that information.

Commonly supported grant_types include password and client_crendentials.

Example Scenario

  • In this example, uses a two-step authentication process.
    • In this first step, you will authenticate with a username (IAP) and password (isTheBest!).
    • The system will then return a token that you need to put in every subsequent request.
  • On subsequent requests, the token will be placed in the header field called -My-Special-Token. The format of the authentication field is ”My Token is xxxx”
  • The response token that’s received is valid for 10 minutes (600s – 600000ms).
  • When the authentication fails or the token is no longer valid, you will receive a 401 error on the request.
  • Example of OAuth.

IAP Service Instance Configuration Properties for the Adapter

"authentication": {
  "auth_method": "request_token",
  "username": "IAP",
  "password": "isTheBest!",
  "token": "",
  "token_timeout": 600000,
  "token_cache": "local",
  "invalid_token_error": 401,
  "auth_field": "header.headers.My-Special-Token",
  "auth_field_format": "My Token is {token}",
  "auth_logging": false,
  "client_id": "",
  "client_secret": "",
  "grant_type": ""

For more in authentication examples see the Authentication articles.

Was this article helpful?

What's Next
Changing your password will log you out immediately. Use the new password to log back in.
First name must have atleast 2 characters. Numbers and special characters are not allowed.
Last name must have atleast 1 characters. Numbers and special characters are not allowed.
Enter a valid email
Enter a valid password
Your profile has been successfully updated.