Custom Authentication

When you select Custom Authentication as the Authentication Type, Web Services aggregates the authentication details for all other endpoints.

In custom authentication, the Web Services source doesn't authenticate requests and doesn't add any authorization to the HTTP header. To accomplish this, the REST application requires a new token to authenticate the request from the Authentication Server.

1. From the Authentication Type drop-down list, select Custom Authentication.

   Important
   If an endpoint does not require authentication at all, you only need to select Custom Authentication. Continue to the following steps to set up custom authentication.

2. In the Base URL field, enter the base URL to connect to the target managed system.
   For example:

   https://api.testurl.com

3. (Optional) Several optional fields display which you can configure as your authentication configuration requires.

   • Username

   • Password

   • API Token

   • Resource Owner Username

   • Resource Owner Password

   • Private Key

   • Private Key Password

   • Client ID

   • Client Secret

   • Refresh Token

4. Select Save.

5. Go to the HTTP Operations tab, and select Add Operation. Set the Operation Type to Custom Authentication.

   For more information on using the HTTP Operations fields, refer to HTTP Operations.

6. Configure the following for endpoints:

   • Authentication URL – From the endpoint details page, enter the full URL in the Authentication URL field.

     Note
     Ensure that you enter the full URL in this field unlike the other endpoints where this field takes in the context URL.

   • Header and Body:

     1. Configure the Header and Body with the required fields for the token generation.

     2. Keys for sensitive attributes updated in the Header and Body must be appended in the encrypted list in the application.

        Caution

        Don't configure sensitive attributes for the Header and Body through the configuration UI. They should be added using the SailPoint Update Source Partial REST API.

        For more information on using the SailPoint Update Source Partial REST API, refer to SailPoint REST API - Update Source (Partial).

        When you add sensitive attributes to the header, ensure that the attributes are added with the suffix, _CA. For example, to use a password in the request, add password_CA.

        Note
        If the attributes are not suffixed with _CA, the Web Services source might display unusual behavior.

        For example, if the attribute updated is a password then it must be added to the header as follows:

        Before updating the encrypted list:

        {"encrypted":"accesstoken,password,refresh_token,oauth_token_info,client_secret,private_key,private_key_password,clientCertificate,clientKeySpec,resourceOwnerPassword,custom_auth_token_info"}

        After updating the encrypted list:

        {"encrypted":"accesstoken,password,refresh_token,oauth_token_info,client_secret,private_key,private_key_password,clientCertificate,clientKeySpec,resourceOwnerPassword,custom_auth_token_info,password_CA"}

        After the attributes are added, their values can be used as placeholders in the Header and Body.

        For example:

        $application.password_CA$

        • Use the password_CA attribute key with value as xyz123 (for example).

        • Add the password_CA key to the existing encrypted attribute (comma-separated) using SailPoint REST API.

        • Use the encrypted attribute key and append ,password_CA to the existing value.

   • Response Mapping – Configure Response Attribute Mapping to obtain access details from the response. Response mapping is the same as in other endpoints where the key is added under the Response Attribute value. Its respective path must be added under Attribute Path.

     Note

     • The Response Attribute value must not be present in the application configuration attributes. After response parsing the value is stored in key value format as follows:

       <entry key="customaccesstoken" value="access_token"/>

     • Be sure to use a custom name for the Response Attribute Key other than the default name. For example, instead of using accesstoken you can define it as customaccesstoken.

     • The accesstoken entry can't be used in response mapping for custom authentication. You must use a different, unique entry to save the response.

7. The token value generated after executing Custom Authentication endpoint can be utilized in all other endpoints using placeholders as follows:

   "$application.<your key>$"

   For example:

   "$application.customaccesstoken$".

   If the token type is for Bearer instance, then it can be used as the following:

   "<your token type> $application.<your key>$"

   For example:

   "Bearer $application.customaccesstoken$"

Operational Trigger Timing

The point within an operation that custom authentication is triggered may vary depending on the operation you configure.

• When performing a Test Connection, the system first executes the custom authentication operation or endpoint. This step is important as it retrieves the customaccesstoken or other authentication-related attributes, which are then utilized in the headers or body of the Test Connection operation.

• For other operations, the system first verifies whether the customaccesstoken or any related authentication attributes are saved. If they are, it utilizes them. If not, it executes the custom authentication operation or endpoint to generate the customaccesstoken or any related authentication attributes.

If an operation fails, the system checks the returned exception code. If the code is 401 or if the error code/message matches one is configured in the HTTP Error field on the Additional Settings menu page, it triggers a custom authentication operation or endpoint. This process generates a customaccesstoken or any related authentication attributes. For more information on the HTTP Error field, refer to HTTP Errors.