Note: In addition to directly modifying the Model file, you can also specify the entries discussed in this section using the Autonomous REST Composer. See Configuring custom authentication with the Configuration Manager for more information.
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 Model 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 Model 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:

    For headers:

    "HEADER <header_name>=<header_value> {/<service_response>}"

    For parameters: 

    "PARAM <parameter_name>=<parameter_value> {/<service_response>}"

Modifying unique parameters and credentials

To allow you to modify parameter values and payloads on a per connection basis, the Model 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 Model 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
Note:
  • The property name variables enclosed in brackets are case insensitive. For example, both {password} and {Password} reference the Password connection property.
  • If you specify a property name that does not resolve, the driver returns an error when attempting to issue a request. For example, this could occur if the property specified is not supported or if there is a typographical error in the specified variable.
  • When using CustomAuthParams variables, if the specified ordinal position does not correlate to a value in the CustomAuthParams connection property, the driver returns an error when attempting to issue a request. For example, if specifying {CustomAuthParams[3]}, but only two values are specified by the connection property, such as CustomAuthParams=123XYZ456abc789;My Company Inc.

Base64 encoded values

If basic authentication is required for your custom authentication, you can configure the driver to calculate Base64-encoded user name and password values at runtime. Use the following syntax in the payload to use Base64 encoding:
"Authorization=Basic BASE64({user}:{password})",

When issuing a request, the driver encodes the values specified for the user and password connection properties and uses them to authenticate to the service. If Base64 encoding is not used, the driver passes the user and password values in plain text.

Examples

The following are some common examples using custom authentication:

Example: Authorization header authentication

The following example demonstrates a simple form of authentication where three headers are sent to authenticate to the service. Unlike other examples in this section, there is no request for access tokens.

In this example, the authorization header must pass a value that contains Basic followed by a Base64-encoded value set of the user name and password. Because the example is using variables for the user and password, the values are supplied by the setting of the User and Password connection properties. The following two headers pass hard-coded values for the client ID and client secret. These values are provided using arguments in the customAuthParams connection property value. 

"#authentication": [
//Authorization header 
    "HEADER Authorization=Basic (BASE64)({user}/{password})",
//Client ID value specified as the first argument of the customAuthParams connection 
//property
    "HEADER X-Client-Id={customAuthParams[1]}",
//Client secret value specified as the second argument of the customAuthParams connection 
//property
    "HEADER X-Client-Secret={customAuthParams[2]}"
]

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 {/customAuthToken}"
]