# 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](<#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. > [!NOTE] > > **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: - [Basic Authentication](<#basic-authentication>) - [API Token](<#api-token>) - [OAuth 2.0](<#oauth-20>) - [Enable No Authentication](<#enable-no-authentication>) 4. Select **Save**. ### Basic Authentication > [!NOTE] > > **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. > [!NOTE] > > **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](<#password>) - [Refresh Token](<#refresh-token>) - [Client Credentials](<#client-credentials>) - [JWT Grant](<#jwt-grant>) #### Password > [!NOTE] > > **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: ```json { "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 > [!NOTE] > > **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 > [!NOTE] > > **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](<#additional-settings>) in the OAuth 2.0 authentication section for additional instructions. #### JWT Grant > [!NOTE] > > **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: ```json { "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](<#additional-settings>) in the No Authentication section for additional configuration information. > [!NOTE] > > **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](). > [!NOTE] > > **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. > [!NOTE] > > **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`: ```xml ``` > **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: > > ```text > {"encrypted":"refresh_token,oauthTokenInfo,client_secret,oauthBearerToken,additional_payload,private_key, private_key_password,oauth2password,noAuthHeaders"} > ``` > > After updating the encrypted list: > > ```text > {"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: ```xml ``` To send additional headers alongside the Authorization header for token generation, add the `oauth_headers` parameter as follows: ```xml ``` - **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: ```xml ``` - **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: ```xml ``` - **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: ```xml ``` ### 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. ```xml ``` > **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: ```xml groups federationId ``` - 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: > > ```json > "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: > > ```json > "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: ```xml ``` > **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 > [!NOTE] > > **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: ```json [ { "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.