Skip to content

Connecting SailPoint and SCIM 2.0

To connect SailPoint with SCIM 2.0, 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

Provide the information required to connect and interact with the source.

Screenshot

alt text

  1. Enter the Connection Timeout in minutes. This is the duration of inactivity the connector allows before terminating the connection. By default, it is one minute.
  2. Enter the Host URL of the SCIM 2.0 compliant managed system.
  3. Select the Authentication Type and then enter the required information. For more information on each authentication method, refer to the following topics:
  4. Select Save.

Basic Authentication

Screenshot

alt text

  1. Enter the Username for basic authentication.
  2. Enter the corresponding Password.
  3. Select Save.

API Token

You can use an API Token for authentication on the SCIM 2.0 source. Only bearer tokens are supported, and they either come with a long validity period or do not expire.

Screenshot

alt text

  1. Enter the API Token.

  2. Select Save.

OAuth 2.0

OAuth 2.0 authentication uses an access token for a connection. An access token is generated based on the selected grant type, which then allows the generated token to be used.

The following grant types are supported:

Password

Screenshot

alt text alt text

  1. Enter the OAuth 2.0 Token URL for generating access token.
  2. Enter the OAuth 2.0 Username and the corresponding Password.

  3. The Additional Payload field accepts additional body parameters in the JSON format.

    For example, you can use:

    {
    "client_id":"xxxx",
    "client_secret":"xxxx"
}

    If you need optional parameters in the payload, then add these via the Additional Payload field. For example, if the managed system expects client_id or client_secret in the payload then it must be provided in the Additional Payload field.

  4. Select Save.

Refresh Token

Screenshot

alt text alt text

  1. Enter the OAuth 2.0 Token URL for generating access token.
  2. Enter the Client ID for OAuth 2.0 authentication.
  3. Enter the Client Secret for OAuth 2.0 authentication.
  4. Enter the Refresh Token used to generate an access token.
  5. Select Save.

Client Credentials

Screenshot

alt text

  1. Enter the OAuth 2.0 Token URL for generating access token.
  2. Enter the Client ID for OAuth 2.0 authentication.
  3. Enter the Client Secret for OAuth 2.0 authentication.
  4. Select Save.

Refer to Additional Settings in the OAuth 2.0 authentication section for additional instructions.

JWT Grant

Screenshot

alt text alt text

  1. Enter the OAuth 2.0 Token URL for generating access token.
  2. In the JWT Header field, you can add additional headers in JSON format if required. The header consists of the type of the token (JWT) and the signing algorithm being used. For example, you can use: { "typ" : "JWT", "alg" : "RS256" }
  3. Enter the JWT Issuer and Subject for authorization.
  4. Enter the JWT Audience for authorization. This is the recipient for which the JWT is intended.
  5. Enter the Private Key and the corresponding Private Key Password to be used to sign JWT.

  6. The Additional Payload can be used in the systems where authentication may require additional parameters along with mandatory fields. You can provide those details in JSON format.

    As an example, you can use the following for additional payload:

    {
    "client_id":"xxxx",
    "client_secret":"xxxx"
}

  7. Select Save.

Enable No Authentication

If your system configuration is set to use no authentication, the SCIM 2.0 source executes the test configuration operation without any authentication. Set the connector to use no authentication when connecting to the SCIM 2.0 source. Refer to Additional Settings in the No Authentication section for additional configuration information.

Screenshot

alt text

  1. Select the No Authentication type.
  2. Select Save.

Aggregation Settings

Configure settings related to account and group aggregation processes.

For more information about aggregation, refer to Loading Account Data.

Screenshot

alt text alt text alt text

  1. Enter the Filter Condition For Accounts to aggregate the SCIM User resources. For example, you can use username sw "Admin".
  2. Enter the Filter Condition For Groups to aggregate the SCIM Group resources. For example, you can use DisplayName sw "SecGroup".
  3. (Optional) Enable Explicit Attribute Request to get the required attributes in a request. Required attributes are the attributes that are present in the schema. In certain instances the SCIM server, by default, does not return all attributes. To ensure you aggregate all attributes, you may want to get the required attributes in a request. This option adds the requested schema attributes in the URL. For example, the organizationId attribute is present in the schema but it is not returned, by default. You may need to request it. In this case the URL will be {host}/Users?attributes=firstName,organizationId. If not selected the URL is {host}/Users.

  4. (Optional) Enable Delta Aggregation Mode to configure the connector to only aggregate accounts which have received updates since the last aggregation process. This can speed up the aggregation process.

    Note

    Delta Aggregation does not bring the accounts which are deleted on the SCIM system. The SCIM 2.0 source supports the 'AND' operator in delta aggregation. Delta Aggregation is applicable only for those SCIM 2.0 systems that support the lastModified attribute and filter for it.

    • Enter a valid Server Time Zone in which the SCIM 2.0 system server is configured. For example, you can use GMT or PST. This timezone is used for performing delta aggregation. If any time zone type is not provided the default value will be UTC.

    • Enter the Server Timestamp Format. It is the date and time format supported by the SCIM server. By default the format is:

      YYYY-MM-dd'T'kk:mm:ss'Z'

  5. Enter a Account Page Size or Group Page Size as number of records that you can get in one request. The default page size is 50.

  6. Select Save.

Additional Aggregation Information

Accounts

After you create and test the connection and save the source, you can load accounts.

You must first discover the schema and identify attributes to use for required identity data before you load the accounts.

Important

SCIM 2.0 compliant server supports the schema and ResourceType endpoint according to the SCIM 2.0 specification.

Discovering the Schema

You must discover the schema and identify the attributes to use for the required identity data before doing any other operation.

  1. Select the Import Data tab.
  2. Select Account Schema in the left menu.
  3. Select Discover.
  4. Identify the attributes to be used for Account Name and Account ID. Mark them in the respective columns.

Note

To discover manager sub-attributes as separate attributes splitManagerAttribute should be set as true in the application.

Caution

If this source is going to be used as an authoritative source for an identity profile, both the Account Name and Account ID must be unique. If not, source accounts could correlate to the first Identity that includes that ID or Name instead of creating an additional Identity.

Loading Accounts

After you have discovered the schema and identified required attributes, you can load accounts by performing the following steps:

  1. In the Import Data tab, start a Manual Aggregation. Select Start.
  2. Check the results in the Aggregation Activity log.

Additional Settings

This section includes information for configuring custom headers for OAuth 2.0 No Authentication configurations, optional OAuth 2.0 parameters, as well as information on provisioning settings. Use this information to further customize your connector.

Screenshot

alt text alt text alt text

HTTP Request Headers

You have several options to configure HTTP headers as needed for your organization.

  • Configure the HTTP Content-type header value that you can use for the SCIM requests. The default value is application/scim+json.
  • In the Accept field enter the HTTP Accept header value that you can use for the SCIM requests. The default value is application/scim+json. The SCIM 2.0 source does not include the read-only attributes in HTTP PATCH requests.

OAuth Settings

Configure additional OAuth settings.

  • To send headers required for the No Authentication type, add a header key and its corresponding value into the No Authentication Headers sub-panel in the OAuth Settings section.

    For example, you can add customParamKey and the corresponding customParamValue:

    <entry key="noAuthHeaders">
<value>
<Map>
<entry key="customParamKey" value="customParamValue"/>
<entry key="password" value="$application.password_CA$"/>
</Map>
</value>
</entry>

    Caution

    Don't configure sensitive attributes through the No Authentication Headers sub-panel in the UI configuration. They should be added through the Update Source Partial REST API and used with placeholders. When you add sensitive attributes to the headers, ensure that the attributes are added with the suffix, _CA. If the attributes are not suffixed with _CA, the SCIM 2.0 source might display unusual behavior. For more information on using the Update Source Partial REST API, see REST API - Update Source (Partial).

    For example, to use a password in the header value, add the password_CA attribute using the source API and use $application.password_CA$ in header value. If the attribute updated is a password then it must be added to the header as follows:

    Before updating the encrypted list:

    {"encrypted":"refresh_token,oauthTokenInfo,client_secret,oauthBearerToken,additional_payload,private_key, private_key_password,oauth2password,noAuthHeaders"}

    After updating the encrypted list:

    {"encrypted":"refresh_token,oauthTokenInfo,client_secret,oauthBearerToken,additional_payload,private_key, private_key_password,oauth2password,noAuthHeaders,password_CA"}

  • To send additional parameters for token generation in the OAuth 2.0 Authentication type, in the OAuth Request Parameters sub-panel panel in the OAuth Settings section, you can add a key and its corresponding value.

    For example, you can add Content-Type as key and the corresponding value as application/x-www-form-urlencoded.

  • If you want to set up and add expected errors while generating a token, enter a list of retryable errors in the Retryable Errors field in the OAuth Settings section.

    For example, you can use "unauthorized", "401", "does not have access"

  • (Optional) Set the following parameters only when the Authentication Method is selected as OAuth2 and the Grant Type is either Client Credentials or Refresh Token. These parameters should be added through the Update Source Partial REST API.

    Note

    For more information on SailPoint's REST APIs, refer to Best Practices: REST API Authentication and REST API - Update Source (Partial) in the SailPoint Developer Community.

    • oauth_headers

      To have customized headers as a part of the access token generation request, add the oauth_headers parameter as follows:

      <entry key="oauth_headers">
<value>
<Map>
<entry key="Content-Type" value="application/x-www-form-urlencoded" />
</Map>
</value>
</entry>

      To send additional headers alongside the Authorization header for token generation, add the oauth_headers parameter as follows:

      <entry key="oauth_headers">
<value>
<Map>
<entry key="customHeaderKey" value="customHeaderValue"/>
</Map>
</value>
</entry>

    • oauth_headers_to_exclude

      SCIM 2.0 supports exclusion of headers in the OAuth2 header request. The keys for headers to exclude from the OAuth2 header request can be added as comma-separated values in the entry key as follows:

      <entry key="oauth_headers">
<value>
<Map>
<entry key="oauth_headers_to_exclude" value="Authorization,CUSTOM_HEADER"/>
</Map>
</value>
</entry>

    • oauth_request_parameters

      For some managed systems, additional custom request parameters may be required to be included in the access token generation request. To send additional parameters for token generation, add the following entry with your desired parameters:

      <entry key="oauth_request_parameters">
<value>
<Map>
<entry key="customParamKey" value="customParamValue"/>
</Map>
</value>
</entry>

    • oauth_body_attrs_to_exclude

      To delete any of the standard request parameters not supported by managed systems access token generation requests, add the following entry with your desired parameters:

      <entry key="oauth_body_attrs_to_exclude">
<value>
<Map>
<entry key="oauth_body_attrs_to_exclude"
value="customParamKey1,customParamKey2"/>
</Map>
</value>
</entry>

Provisioning Settings

Configure additional settings related to provisioning processes.

  • Enable the USE HTTP PATCH method if usePatch is required. While updating the existing attributes, the SCIM 2.0 source supports the Replacing operation instead of Adding, while using the PATCH method.

  • Enable Skip Group Update to skip the redundant group update call, and instead, to use a create account with entitlement request. The default behavior of SCIM 2.0 is to communicate with the Groups endpoint for modification of groups information, but you can configure the source to modify group information through the Users endpoint. To enable this feature, set the updateGroupsViaUsers attribute to true in the source XML file using the REST API.

    <entry key="updateGroupsViaUsers" value="true"/>

    Note

    Refer to Best Practices: REST API Authentication and REST API - Update Source (Partial) for more information on configuring via the REST API.

    When enabled, the SCIM 2.0 source adds all the attributes in the create/upload payload regardless of its mutability. If any attributes are read-only, and should not be included in the create/update payload, add them in a list. For example:

    <entry key="readOnlyAttrs">
<Value>
<List>
<String>groups</String>
<String>federationId</String>
</List>
</Value>
</entry>

  • Enable Multivalued RFC Compatibility to generate a more consolidated JSON format. This format is needed to provision multivalued extended schema attributes in a relaxed configuration.

    Example

    The following examples are for a multivalued extended schema attribute representing a user's address.

    When Multivalued RFC Compatibility is disabled, the JSON is generated as follows:

    "addresses": [
        {
                "country": "USA",
                "type": "work",
                "primary": true
        },
        {
                "locality": "Grand Island",
                "type": "work",
                "primary": true
        },
        {
                "type": "work",
                "region": "USA-NE",
                "primary": true
        }
]

    When Multivalued RFC Compatibility is enabled, the JSON is generated as follows:

    "addresses": [
    {
    "type": "work",
    "locality": "Austin",
    "region": "TX",
    "country": "USA",
    "primary": true
    }
]

  • To send the path for a Simple Core Complex Attribute during an HTTP request, enable the includePathForCoreAttributes parameter in the source XML via REST API as follows:

    <entry key="includePathForCoreAttributes" value="true"/>

    Note

    For more information on SailPoint's REST APIs, refer to Best Practices: REST API Authentication and REST API - Update Source (Partial) in the SailPoint Developer Community.

    Simple Core Complex Attributes include attributes such as name.familyName or name.givenName.

Non-Compliant Settings

Screenshot

alt text alt text alt text

The SCIM 2.0 source supports the configuration of a non-compliant SCIM server. In the SCIM 2.0 source UI, on the Relax Configuration sub-panel, enable the Non Compliant Server? option to skip SCIM 2.0 validation for each response from this server. Use this if your SCIM 2.0 Server is not fully compliant with SCIM 2.0 specifications.

The SCIM 2.0 source will not use the schema response; it will use the populated core or extended schema mentioned in the SCIM 2.0 specifications. Refer to the section for the list of attributes at https://datatracker.ietf.org/doc/html/rfc7643#section-4.1.

For any new attribute, you must add it in the schema and add its JSON path to the JSON Path Mapping.

For any other object type other than offered by default, such as Account, Group, Role, and Entitlement, you must manually add the schema and JSON path mapping in the source. Refer to Best Practices: REST API Authentication, REST API - Update Source (Partial), and Adding Attributes to a Source Schema.

If this configuration is enabled for an existing source, you must perform a Discover Schema operation to get the JSON path mapping from the source. The SchemaPropertyMapping configuration in the existing source will remain intact and can be removed manually, if required.

In the Aggregation Settings sub-panel, configure (Add, Remove, and Modify) the JSON path mapping.

If any attributes are read-only and don't need to be included in the create/update payload, add them in a list.

In the Provisioning Settings sub-panel, configure the read-only attributes.

You can configure a custom rootPath for aggregating Accounts if the rootPath of /Users does not comply with SCIM RFC. For example, if /Users rootPath is "resources" instead of the SCIM RFC standard "Resources", use the Update Source (Partial) API as shown below in the JSON Payload example:

[
{
"op": "add",
"path": "/attributes/aggregation_rootPath",
"value": "$.resources[*]"
}
]

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.