Skip to content

Connecting SailPoint and Web Services

To connect SailPoint with Web Services, perform the following tasks:

Adding the Source in SailPoint

To connect to SailPoint, perform the following steps. Once the connection is made, you can configure it to meet your company's needs.

Important

By default, the provisioning feature is disabled, and the connector only supports read-only operations. To support provisioning operations, you must manually enable the feature in the source configuration.

To configure a new source:

  1. Sign in to SailPoint.
  2. Go to Admin > Connections > Sources.
  3. Select Create New.
  4. Search for the connector by entering the name in the search box, and then select Configure.
  5. In the Source Name field, enter a unique and descriptive name for your source. Source names cannot exceed 128 characters.
  6. In the Description field, provide additional details about the source to help distinguish it from similar sources. This field allows a maximum of 2,000 characters.
  7. In the Source Owner field, begin typing the name of an owner. Matches appear after you type two or more letters. For more information, refer to Assigning a Source Owner.

  8. Under Connection Type, select Direct Connection or Flat File.

    • Direct Connection - A direct connection fetches data from the Virtual Appliance Cluster you choose as the application connector for the source. A direct connection configuration allows for real-time updates. For more information about configuring and deploying virtual appliances, refer to the Virtual Appliance Reference Guide.
    • Flat File - Select the flat file if no connector is available, or if another system restricts the connection. This option allows only reading and aggregating data as a generic/delimited application. Provisioning activity is unsupported, and additional configuration pages like connection settings and aggregation settings are unavailable.

  9. If you selected Direct Connection, in Virtual Appliance Cluster, select the virtual appliance cluster that will be used as the application connector for the source.

  10. (Optional) Select a governance group to grant its members source or role sub-admin level oversight of the source and its access. For more information, refer to Creating and Managing Governance Groups.
  11. If this source represents a primary system containing your organization's personnel records, select the Authoritative Source checkbox. For more information, refer to Creating Identity Profiles.
  12. Select Continue. The source is created, and you are navigated to the Source Setup > Base Configuration page. Continue to configure your connected source there.

Base Configuration

Provide the base configuration parameters. Information you entered in the Create New Source dialog is automatically entered into the fields in the Base Configuration page. You can edit this information if necessary.

  1. Enter a unique name and description for the source.

  2. In the Source Owner dropdown list, select the identity that owns this source.

    • To find a source owner, begin entering their name.

  3. In the Virtual Appliance Cluster dropdown list, select the virtual appliance to use when communicating with your organization's systems. For more information, refer to SailPoint Virtual Appliances.

  4. (Optional) If enabled for your organization, select the Use a Credential Provider checkbox to manage the source's authentication using a credential provider.

    Note

    To add a credential provider, go to Admin > Connections > Credential Providers. For more information about credential providers, refer to Credential Providers.

  5. Configure the authentication to allow SailPoint to connect to the source. Refer to Connection Settings for more information.

  6. (Optional) In the Governance Group for Source Management dropdown list, select a governance group to associate with this source. For more information about governance groups, refer to Associating Governance Groups with a Source.

  7. (Optional) Choose whether to enable or disable provisioning for the source. Provisioning is disabled by default.

    • Enable Provisioning - Set the toggle to Enabled to allow the source to create, update, and deactivate accounts in the connected source system.

    • Disable Provisioning - Set the toggle to Disabled to disable provisioning for the source. Disabling provisioning will prevent the creation, updating, or deactivating of accounts on this source.

  8. Select Save.

Connection Settings

This section has the configuration details on authentication types, common configurations, and delta aggregation settings.

Select the authentication type your source uses. You can enter the supporting authentication information in the fields provided below your selection. The supporting fields that display change depending on your selected authentication type.

The SailPoint Web Services connector supports the following authentication types:

Basic Authentication

Screenshot

Basic Authentication

  1. From the Authentication Type dropdown list, select Basic 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. Enter the Username and Password for the account with the required permissions to execute Web Services.

  4. Configure the Aggregation Settings and Common Configuration settings that apply, then select Save.

API Token

The connector can authenticate with the source using an API token. The API token you provide is saved to the accesstoken attribute in the application configuration. API tokens are given in the following format:

token_type API_token

For example:

Bearer ********

Note

If the token type is not provided, then the connector automatically uses Bearer.

API Token Placeholders

You can reference a saved API token using a placeholder. The token placeholder can be provided as a variable across all endpoints for request components such as:

  • Request URL
  • HTTP Headers
  • Request Body

The following is an example of an API token placeholder:

$application.accesstoken$

You can define and use multiple API token placeholders if your configuration requires it. Refer to Custom Authentication for more information on API token placeholders.

Screenshot

API Token

  1. Select API Token as the Authentication Type.

  2. Enter the Base URL to connect to the managed system. For example:

    https://api.testurl.com

  3. Enter the API Token specific to the managed system.

  4. Configure the Aggregation Settings and Common Configuration settings that apply, then select Save.

OAuth 2.0

For all the grant types that you can select, the following fields are common configuration. Other grant type details are described in the following subsections.

Screenshot

OAuth 2.0

  1. Select OAuth 2.0 as the Authentication Type.

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

    https://api.testurl.com

  3. Enter the Token URL. The format is:

    https://{your domain}/token

    Web Services supports the replacement of attributes in the OAuth 2.0 token URL. For example, if you want to prepare a token URL with sensitive information such as client_secret, $application.client_secret$ can be used. The corresponding value is determined from the replaced location in the token URL.

  4. For OAuth Headers, set up the custom headers as part of the access token. Web Services adheres to the generalized specifications of the OAuth 2.0 grant types. However, for some managed target systems, custom headers may be required to be part of the access token generation request. You can add the custom headers as an attribute.

    Note

    The Content-Type value can only be application/x-www-form-urlencoded when Authentication Type is selected as OAuth 2.0. If the managed system expects a Content-Type other than application/x-www-form-urlencoded, use Custom Authentication instead of OAuth 2.0.

  5. In OAuth Headers to Exclude, enter the headers that you want to exclude. By default, an Authorization BASIC header with a Base64-encoded client ID and client secret is part of the access token generation request. Some managed target systems do not support this header. If there is no Authorization BASIC header required for such managed target systems, it can be excluded from the request.

  6. For OAuth Request Parameters, set up the custom parameters for an access token. For some managed target systems, custom request parameters may be required to be part of the access token generation request. You can add the custom request parameter as an attribute.
  7. For OAuth Body Attributes to Exclude, enter the attributes that you want to exclude. To remove any of the standard request parameters that are not supported by managed target systems' access token generation requests, configure the request parameters to exclude from the access token request.

  8. Select a Grant Type and complete its configuration:

  9. Configure the Aggregation Settings and Common Configuration settings that apply, then select Save.

Password Grant Type

For the Password Grant Type:

Screenshot

Password Grant Type

  1. Select Password as the Grant Type.
  2. Enter the Username and Password to authorize with the source.

Client Credentials

For the Client Credentials Grant Type:

Screenshot

Client Credentials

  1. Select Client Credentials as the Grant Type.
  2. Enter the Client ID and its associated Client Secret. These are the client identification and secret for OAuth 2.0 authentication.

Refresh Token

For the Refresh Token Grant Type:

Screenshot

Refresh Token

  1. Select Refresh Token as the Grant Type.
  2. Enter the Client ID and the associated Client Secret for OAuth 2.0 authentication.
  3. Enter the Refresh Token used to generate the access token. Web Services supports OAuth 2.0 Refresh Tokens for the managed target system. The refresh tokens either don't expire or come with a long validity period.

JWT Bearer Token

For the JWT Bearer Token Grant Type:

Screenshot

JWT Bearer Token

  1. Select JWT Bearer Token as the Grant Type.
  2. Enter the Private Key and Private Key Password to be used for JWT authentication.
  3. Enter the Client ID and the associated Client Secret for OAuth 2.0 authentication.

  4. In JWT Header, enter the following:

    • Key - The Key is the algorithm that is used for signing the JWT assertion. It must be the same algorithm that you use for generating the private key. For example, you can use alg.
    • Value - The Value is the JWT headers key. For example, you can use the value RS256. If required, additional header attributes can be provided in the key-value pair mentioned above.

  5. In JWT Payload, enter the following:

    • Key - The Payload Key enables you to include information on the JWT Claim. For JWT authentication, it is mandatory to have the payload key for a successful test connection and other operations. The mandatory attributes are:

      • aud (Audience)
      • exp (Expiry of the JWT assertion)
      • iss (Issuer)
      • sub (Subject)

      If required, additional payload attributes can be provided in this key-value pair based on the target system.

    • Value - The value of the Payload Key.

SAML Bearer Assertion

For the SAML Bearer Assertion Grant Type:

Screenshot

SAML Bearer Assertion

  1. Select SAML Bearer Assertion as the Grant Type.
  2. Enter the Client ID and the associated Client Secret for OAuth 2.0 authentication.
  3. Enter the SAML Assertion URL for generating a SAML Assertion. The SAML Assertion URL supports placeholders for replacement of the source attribute dynamically. For example, if a SAML Assertion URL is required to be prepared with some sensitive information such as a password, use $application.saml_password$. The corresponding value is determined from the source and replaced at the appropriate location in the SAML Assertion URL.
  4. Enter the SAML Request Body that generates a SAML Assertion. SailPoint recommends that you use $application.saml_username$ and $application.saml_password$ placeholders in the request body to prevent exposing any sensitive data.
  5. Enter the Username and Password for the service account with required permissions to execute Web Services.
  6. In SAML Headers, enter the Key and respective Value. These are used for SAML assertion generation.
  7. Enter any SAML Headers to Exclude which apply. By default, an Authorization BASIC header with a Base64-encoded resource username and resource password is part of the SAML Assertion generation request. Some managed target systems do not support such a header. If there is no Authorization BASIC header requirement for such target systems, it can be excluded from the request.

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.

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.

Screenshot

Custom Authentication

  1. From the Authentication Type dropdown list, select 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 HTTP Operations, and select Add Operation. Set the Operation Type to Custom Authentication. Refer to HTTP Operations for more information about using the HTTP Operations fields.

  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. Refer to SailPoint REST API - Update Source (Partial) for more information.

        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 a value such as xyz123.
        • Add the password_CA key to the existing encrypted attribute (comma-separated) using the SailPoint REST API.
        • Use the encrypted attribute key and append ,password_CA to the existing value.

    • Response Mapping - Configure Response Attribute Mapping to obtain the access details from the response. Response mapping is the same as the other endpoints; the key is added under Response Attribute and its respective path must be added under Attribute Path.

      Notes

      • 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 the 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 a Bearer instance, then it can be used as follows:

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

    For example:

    "Bearer $application.customaccesstoken$"

  8. Configure the Aggregation Settings and Common Configuration settings that apply, then select Save.

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 configured in the HTTP Error field on the Additional Settings page, it triggers a custom authentication operation or endpoint. This process generates a customaccesstoken or any related authentication attributes. Refer to HTTP Errors for more information on the HTTP Error field.

Review and Test

Perform a test to confirm the connection to SailPoint.

  1. Go to Review and Test.

  2. Confirm that the entries in each field are correct.

    If you note any mistakes, return to the section and make corrections.

  3. Select Test Connection.

SailPoint Application Onboarding

SailPoint application onboarding enables you to easily onboard new applications and create sources following the successful onboarding of a discovery source. To use this feature, continue to Discovered Applications in the SailPoint user interface.

For more information, refer to Application Onboarding in the SailPoint SaaS documentation.

Documentation Feedback

Feedback is provided as an informational resource only and does not form part of SailPoint’s official product documentation. SailPoint does not warrant or make any guarantees about the feedback (including without limitation as to its accuracy, relevance, or reliability). All feedback is subject to the terms set forth at https://developer.sailpoint.com/discuss/tos.