If your service does not support one of the standard authentication methods provided by the driver, you can define custom authentication requests to retrieve and exchange access tokens using the input REST file. Multiple authentication requests can be defined in a single entry, allowing you to implement authentication flows that consist of multiple steps.
A custom authentication request is defined in the REST file using two entries:
#authentication: defines the initial request in an authentication flow.
#reauthentication: defines the request used to refresh the access token retrieved through the #authentication entry.
Important: In authentication request entries, special characters, such as ampersands (&), must be escaped using a back slash (\).
The #authentication and #reauthentication entries are comprised of the following components:
Header: Defines the header to be included in the HTTP request used to retrieve an access token. The header applies to the next HTTP request defined in the entry. A header must be defined for each HTTP request that retrieves a token.
Payload: Contains the request body, in JSON format, that must be passed to the service to generate the access token. The payload applies to the next HTTP request defined in the entry. A payload should be defined only if a request body is required by the service for that HTTP request.
HTTP request: Defines the HTTP request to the endpoint that is used to exchange authentication credentials for access tokens. An HTTP request must be defined each time a token is retrieved.
Data request credentials: Defines the header or parameter used in requests for data. There is only one of these definitions per entry. The data request credentials take the following form, where service_reponse is the service response containing the access token:
To allow you to modify parameter values and payloads on a per connection basis, the REST file supports using variables to reference connection property values specified in the connection string or data source definition. This provides you with a secure method to specify unique values for each connection without having to edit the REST file. For most properties, you can create a variable by enclosing the property name in { } brackets. For example, to reference the value of the password property in the connection string, specify {password}.
The exception to this behavior is the CustomAuthParams property. The value of the CustomAuthParams property is a semicolon-separated list of parameter values. To indicate the correct value in the list, in addition to the property name, you must also specify the ordinal location of the parameter you want to reference in [ ] brackets. For example, to reference www.example.com in the following CustomAuthParams value, you would use a variable of {CustomAuthParams[3]}.
CustomAuthParams=123XYZ456abc789;My Company Inc;www.example.com
Example: Simple token request
The following is an example of a simple token request, where access-token is the server response that contains the payload with the access token. Most custom authentication requests will take this form.
"#authentication" : [
//Header
"api-key={CustomAuthParams[1]}",
//Payload
{
"credentials": {
"username": "{user}",
"password": "{password}",
"company": "{customAuthParams[2]}"
}
},
//HTTP request
"POST http://{serverName}/bearertoken",
//Data request credentials. "{/access-token}" refers to the service
//response from the preceding HTTP request.
"HEADER Authentication=Bearer {/access-token}"
]
Example: Two-step token request
The following example demonstrates a two-step authentication, where the service response from the initial request, UserToken, is passed in the request header of the second stage of authentication. The principles demonstrated in this example apply to authentication flows requiring two or more requests.
"#authentication" : [
//Header request for first request
"accept=application/json",
"content-type=application/json",
"kmauthtoken=\\{sitename:\"{customAuthParams[1]}\",localeId:\"en_US\"\\}\\}",
//Payload for first request
{
"login": "{user}",
"password": "{password}",
"siteName": "{customAuthParams[1]}" },
//HTTP request for first token
"POST https://{serverName}/getusertoken",
//Header for second request. "{/authenticationToken}" refers to the value of
//the service response from the preceding HTTP request.
"accept=application/json",
"content-type=application/json",
"kmauthtoken=\\{sitename:\"{CustomAuthParams[1]}\",localeId:\"en_US\",
UserToken:\"{/authenticationToken}\"\\}",
//Payload for second request
{
"userName": "{user}",
"password": "{password}",
"siteName": "{customAuthParams[1]}",
"userExternalType": "ACCOUNT"
},
//HTTP request for second token
"POST https://{serverName}/getaccesstoken",
//Data request credentials. "{/customAuthToken}" refers to the value in
//the service response from the preceding HTTP request.
"HEADER Authentication=Bearer
\\{sitename:\"{customAuthParams[1]}\",localeId:\"en_US\",
userToken:\"{/authenticationToken}\",integrationUserToken:\
"{/accessToken}\"\\}"]
#authentication: defines the initial request in an authentication flow.