# SailPoint SCIM 2.0 Connector Documentation > SCIM 2.0 Connector Documentation # Documentation # 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. # Integrating SailPoint with SCIM 2.0 The SCIM (System for Cross-Domain Identity Management) standard defines a schema and API to create, read, update, and delete identity and identity-related information on other systems. This standard creates a common language, by which a client system can communicate with many different servers in the same way. This guide is designed to give specific information about the requirements and field definitions needed to configure a working instance of a SCIM 2.0 connector. > [!NOTE] > > To view the latest features, enhancements, and fixes for all SaaS connectors, refer to the [SaaS Release Notes]() page. ## Supported Features Using this connector, you can manage any SCIM 2.0 compliant target system. The SCIM 2.0 connector supports the following features: > [!NOTE] > > Before you can use any item marked with an asterisk (\*), SailPoint must activate the feature for your site. - Load accounts - \*Provisioning - \*Password management - \*Access certifications (certification of entitlements connected to accounts) - Addition of groups and entitlements - Delete accounts For more information on features, refer to [Source Features](). The SCIM 2.0 connector supports multiple group objects such as `group`. Depending on the managed system to which you are connecting, you can configure entitlements and roles. You must add a new group schema and update the existing account schema using APIs. For more information, refer to [listSchema]() API and [createSchema]() 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. > [!NOTE] > > **Add new group schema** > > The following example adds the schema for a Role: > > ```json > Method: POST > Uri: beta/sources//schemas > JSON Payload: > { > "name": "Role", > "nativeObjectType": "Role", > "identityAttribute": "Id", > "displayAttribute": "Name", > "hierarchyAttribute": null, > "includePermissions": false, > "features": [], > "configuration": {}, > "attributes": [ > { > "name": "Id", > "type": "STRING", > "schema": null, > "description": "Role Id.", > "isMulti": false, > "isEntitlement": false, > "isGroup": false > }, > { > "name": "Name", > "type": "STRING", > "schema": null, > "description": "Role name.", > "isMulti": false, > "isEntitlement": false, > "isGroup": false > } > … > … > ] > } > ``` > > For example: > > ```xml > > > Role Id. > > > Role name. > > > ``` > [!NOTE] > > **Update existing account schema** > > When the new group schema for the role object type has been created, you need to update the relevant account schema attributes to point at the new group schema. This can be done by making changes in the account schema since SailPoint enables you to add the new entitlement in the account schema via UI. ### API Throttling The SCIM 2.0 connector supports API throttling. The following headers are supported for throttling, per the SCIM standards: - `x-rate-limit-remaining` - `x-rate-limit-limit` - `x-rate-limit-reset` - `x-rate-limit-retry-after-seconds` > [!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. To update the maximum API call threshold percentage, configure the following attribute to check the `x-rate-limit-reset` header after the threshold. The default value is `100`. ```json PATCH {apiUrl}/v3/sources/{sourceId} [ { "op": "add", "path": "/connectorAttributes/maxApiCallsThresholdPercentage", "value": "100" } ] ``` ### For Relax and Non Relax Configuration If any target system does not send the response headers in SCIM 2.0 specification, the following parameters can be used to update the entry. ```json PATCH {apiUrl}/v3/sources/{sourceId} [ { "op": "add", "path": "/connectorAttributes/rateLimitHeaders", "value": { "limitHeader": "rate-limit-limit", "remainingHeader": "rate-limit-remaining", "limitResetHeader": "rate-limit-reset", "retryAfterHeader": "rate-limit-retry-after-seconds" } } ] ``` ### Password Management **Prerequisites** - Purchase the Password Management feature - Work with SailPoint Services to implement the feature for your environment If Password Management is enabled for your organization, you can change the password for a user of the source. After enabling password management on the source, be aware of the following: - The password policy defined in SailPoint applies to accounts on this source. - If you change the password for an application connected to this source, the change will automatically be made to the source itself. For more information on configuring password management, refer to [Password Management Overview](). ## Supported Managed System The SCIM 2.0 connector only supports SCIM 2.0 compliant / non-compliant managed systems; it does not support SCIM 1.1 or SCIM 1.0 compliant target systems. > [!IMPORTANT] > > To ensure proper functionality of the SCIM-compliant server, core schemas and protocols must be configured according to the following RFCs: > > - Core Schemas - [RFC 7643]() > - Protocols - [RFC 7644]() ## Prerequisites - A SCIM 2.0 compliant target system should be up and running. - Configure at least one virtual appliance cluster and successfully test the connection. For more information, refer to the [Virtual Appliance Reference Guide](). - The SailPoint SCIM 2.0 connector requires the following endpoints with a valid response for connector execution: > **Note** > > Not applicable if **Non-compliant Server?** is enabled. - `/ServiceProviderConfig` - `/ResourceTypes` - `/Schemas` - `/ResourceTypes/User` - `/Schemas/urn:ietf:params:scim:schemas:core:2.0:User` ## Required Permissions The service account used for the SCIM 2.0 connector should have permission to execute the following operations: - get all users - add user - modify user # Provisioning Policy The SCIM 2.0 connector supports provisioning, allowing you to create and manage accounts and entitlements in SCIM 2.0 directly from SailPoint. **Prerequisite:** Your system is configured for provisioning. When SailPoint provisions new accounts to the source, it uses the attributes on the **Create Account** page as instructions or a template for what to include in the account. This page is also referred to as the *provisioning policy*. When new access is granted on a source where a user does not already have an account, SailPoint automatically includes account creation in the provisioning. This applies whether provisioning is started from an access request or from an automated role or lifecycle state assignment. For direct-connect sources, SailPoint automatically creates the account from this configuration. If the source is not configured as a direct-connect source, SailPoint creates and assigns a provisioning task to the source owner and includes the values for the source owner to use in manually creating the account. > [!IMPORTANT] > > This section describes the default **Create Account** configuration. SailPoint recommends that you work with Services to define a provisioning configuration specific to your company's needs. Be sure to verify large changes to the provisioning policy before implementation. Failure to do so might cause provisioning to fail. ## Default Create Account Attributes You can create an account configuration based on a SCIM 2.0 compliant server. The provisioning operation can update the attribute value to a blank value. The SCIM 2.0 source performs provisioning after regenerating an access token. The SCIM 2.0 source encodes the JSON during provisioning operations with special characters. > [!CAUTION] > > The SCIM 2.0 source doesn't have a default Create Account template. However, SailPoint recommends that you work with Services to define a provisioning policy specific to your company's needs. # Retry Configurations > [!IMPORTANT] > > Add a list of retryable error messages to the attributes map of the source configuration. The value must be specified as a list or array even when only a single error string is provided. ## Provisioning Retry Errors > [!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. SailPoint connectors that support provisioning operations have the ability to retry a failed operation based on configurable error messages. The `retryableErrors` entry in the connector configuration is a list of strings that the connector searches for in the error message received from the managed source. If any of the configured error strings are found in the error message, the connector will attempt to retry the provisioning operation. Add a list of retryable error messages to the attributes map of the source configuration. The value must be specified as a list or array even when only a single error string is provided. If the error message contains one of the specified strings, the connector will initiate a retry attempt. However, if the configured error string is not present in the error message, the connector will consider the operation as failed and will not attempt a retry. Add the following entry in the source XML using the SailPoint REST APIs: For example, Use the SailPoint API by sending a PATCH request to the /v3/sources/{id} endpoint: `PATCH https://{orgName}.api.identitynow.com/v3/sources/:id` In the body of the PATCH, enter the retryable errors as follows: ```json [ { "op": "add", "path": "/connectorAttributes/retryableErrors", "value": [ "", "" ] } ] ``` > [!NOTE] > > Error messages containing very specific information about date/time, sequence ID and so on must be avoided. Error codes or error message substrings would be good candidates for inclusion. ## Aggregation Retry Errors Aggregation retries can be set up for each source by configuring the `aggregationRetryErrors` attribute under the `connectorAttributes` section. Send a PATCH request to the `/v3/sources/{id}` endpoint: `PATCH https://{orgName}.api.identitynow.com/v3/sources/:id` In the body of the PATCH, enter the `aggregationRetryErrors` as follows: ```json { "op": "add", "path": "/connectorAttributes/aggregationRetryErrors", "value": ["Connection reset"] } ``` In addition to specifying the aggregation retry errors, you can also configure the following options: > [!NOTE] > > **retryWaitTime** > > A string specifying the amount of time (in milliseconds) to wait before attempting a retry. The default value is 5000 milliseconds (5 seconds). > > In the body of the PATCH, enter the `retryWaitTime` as follows: > > ```json > { > "op": "add", > "path": "/connectorAttributes/retryWaitTime", > "value": "5000" > } > ``` > [!NOTE] > > **maxRetryCount** > > A string defining the maximum number of retry attempts that will be performed. The default value is 3. > > In the body of the PATCH, enter the `maxRetryCount` as follows: > > ```json > { > "op": "add", > "path": "/connectorAttributes/maxRetryCount", > "value": "3" > } > ``` # Schema Reference The application schema is used to configure the objects returned from a connector. > [!NOTE] > > - The **Account Schema** tab is used to define the attributes for each object type in the application being configured. The schema attributes can be defined as **Entitlement** or **Multi-Valued**. Refer to [Managing Source Account Schemas]() for more information. > - The schema attributes that are not present by [default](<#default-account-schema>) must be defined as strings if not specified. The SCIM 2.0 connector uses the following default correlation and object configurations. ## Default Account Schema Each source supports a variety of details, or attributes, about each user who has an account, such as their name, email address, manager name, and location. The set of account attributes each source stores and how they're organized is known as the account's *schema*. To best represent your data, you can configure sources to use an account schema matching the one you use in the external connector. Refer to [Managing Source Account Schemas]() for more information. ### Default Account ID SailPoint requires that certain attributes remain in your configuration. These attributes are referred to as *account IDs*. > [!CAUTION] > > Changing the attribute marked as the account ID after aggregating accounts can result in duplicate accounts being created. To avoid this, either reset the accounts on this source before editing the account ID attribute or edit the account ID attribute before aggregating accounts. > > To resolve issues caused by changing account IDs, reconfigure them to their default values. The following table lists the default account IDs for this connector: | Account ID | Schema Object Type | | --- | --- | | id | Account | | id | Group | # Enable Connector Logging This topic provides the steps needed to enable logging on SailPoint using REST APIs. > [!NOTE] > > This topic only applies to VA-based integrations. > [!NOTE] > > The examples provided might not match your configuration. Use the logging levels and logging classes reference at the bottom of the topic to configure your API responses to match your connector. This process is broken up into four steps: 1. Identify the Virtual Appliance (VA) cluster on which you want to enable logging. 2. Get the logging configuration for the existing VA cluster. 3. Update the VA cluster to enable logging levels. 4. Observe logging changes to the logging levels. ### Identify the Virtual Appliance Cluster Select the VA on which you need to enable logging using REST API. If you already know the VA application's `id`, proceed to [Get the Logging Configuration](<#get-the-logging-configuration>). 1. Make the following call to the REST API to return a list of available VA clusters: GET /v3/managed-clusters The REST API returns a response that looks similar to the following: ```json [ { "id": "2c9180866166b5b0016167c32ef31a66", "name": "Development Cluster", "description": "Development Cluster", "clientType": "CCG", "ccgVersion": "373_535_70.2.0", "pinnedConfig": true, "logConfiguration": null }, { "id": "2c9180846a93ce60016ab29f039944de", "name": "Cloud Cluster", "description": "Cloud Cluster", "clientType": "CCG", "ccgVersion": "373_535_70.2.0", "pinnedConfig": true, "logConfiguration": { "clientId": null, "durationMinutes": 60, "expiration": "2020-12-15T19:13:36.079Z", "rootLevel": "DEBUG", "logLevels": { "sailpoint.connector.ADLDAPConnector": "DEBUG" } } } ] ``` > **Note** > > The previous example code shows two VA clusters. One VA cluster has a log configuration and the other does not (refer to the `logConfiguration` value in each returned VA cluster). This is because one of the clusters already has logging enabled. This is just an example configuration, and your environment may not have logging enabled on a cluster. 2. Identify the VA cluster that you want to enable logging on by its name or description and record its `id` attribute. ### Get the Logging Configuration Get your selected VA's cluster logging configuration and identify the values you need to update. 1. Make the following call to the REST API to return the VA cluster's logging configuration. Replace `{id}` with the VA cluster's `id` attribute value recorded earlier. GET /v3/managed-clusters/{id}/log-config - If the VA doesn't have a logging configuration currently set, it returns `204 No Content` as a response. - If the VA has an existing logging configuration, it returns something similar to the following: ```json { "clientId": null, "durationMinutes": 60, "expiration": "2020-12-15T19:13:36.079Z", "rootLevel": "DEBUG", "logLevels": { "sailpoint.connector.ADLDAPConnector": "DEBUG" } } ``` You'll need to configure the following information in the response: - `durationMinutes` is the number of minutes logging should remain enabled. - `rootLevel` is the default level for all logs. For more information, refer to [Logging Levels](<#logging-levels>). - `logLevels` is a map object with logging classes as keys and logging levels as values. - For keys, refer to [Logging Classes](<#logging-classes>) for commonly used logging classes. - For a list of available values, refer to [Logging Levels](<#logging-levels>). ### Update Logging Configuration Update the VA cluster configuration returned by the REST API to update the logging settings as needed. 1. Make the following call to the REST API to update the VA cluster's logging configuration. Replace `{id}` with the VA cluster's `id` attribute value recorded earlier. PUT /v3/managed-clusters/{id}/log-config 2. Submit your configuration changes to the REST API in a JSON body. - If the VA cluster did not already have a logging configuration and you received a `204 No Content` response, you can create a new one. - If the VA returned a configuration, you can edit it to include the changes. The JSON body should be as follows: ```json { "durationMinutes": 60, "rootLevel": "DEBUG", "logLevels": { "sailpoint.connector.ADLDAPConnector": "DEBUG" } } ``` Consider the following as you edit the JSON: - `durationMinutes` is the number of minutes logging should remain enabled. - `rootLevel` is the default level for all logs. For more information, refer to [Logging Levels](<#logging-levels>). - `logLevels` is a map object with logging classes as keys and logging levels as values. - For keys, refer to [Logging Classes](<#logging-classes>) for commonly used logging classes. - For a list of available values, refer to [Logging Levels](<#logging-levels>). If the update was successful, the REST API should return a response similar to the following: ```json { "clientId": null, "durationMinutes": 60, "expiration": "2020-12-15T19:13:36.079Z", "rootLevel": "DEBUG", "logLevels": { "sailpoint.connector.ADLDAPConnector": "DEBUG" } } ``` ### Observe Logging Changes Approximately five minutes after you update the configuration, the VA cluster starts generating log files you can review. You can view the log files in **ccg.log**. ### References The tables in this reference section list information that can be helpful when creating the JSON body you'll use to configure the VA cluster's configuration file. #### Logging Levels | Logging Level | Description | | --- | --- | | ERROR | Designates error events that might still allow the connector to continue. | | WARN | Designates potentially harmful situations. | | INFO | Designates information messages that highlight process at a coarse-grain level. | | DEBUG | Very verbose. Fine grain logging levels used for development and debugging. | | TRACE | Most verbose. Finer grain logging levels than debugging. | #### Logging Classes | Connector | Logging Class | | --- | --- | | Active Directory | sailpoint.connector.ADLDAPConnector sailpoint.connector.LDAPConnector | | AIX | openconnector.connector.unix.AIXConnector openconnector.connector.unix.UnixConnector | | Amazon Web Services | logger.aws.name=openconnector.connector.aws logger.aws.level=trace logger.aws.additivity = false logger.aws.appenderRef.rolling.ref = STDOUT | | Atlassian Suite Cloud | sailpoint.connector.OpenConnectorAdapter openconnector.connector.atlassian.AtlassianConnector | | Atlassian Data Center | sailpoint.connector.OpenConnectorAdapter openconnector.connector.atlassian.AtlassianDataCenterConnector | | Microsoft Entra ID | sailpoint.connector.AzureADConnector | | Box | openconnector.connector.BoxNetConnector sailpoint.connector.OpenConnectorAdapter | | Cerner | openconnector.connector.CernerConnector sailpoint.connector.OpenConnectorAdapter | | Delimited File | logger.DelimitedFileConnector.name = sailpoint.connector.DelimitedFileConnector logger.DelimitedFileConnector.level = debug logger.DelimitedFileConnector.additivity = false logger.DelimitedFileConnector.appenderRef.rolling.ref = STDOUT | | Dropbox | openconnector.connector.DropBoxConnector sailpoint.connector.OpenConnectorAdapter | | Epic | openconnector.connector.EPICConnector sailpoint.connector.OpenConnectorAdapter | | GE Centricity | openconnector.connector.GECentricity sailpoint.connector.OpenConnectorAdapter | | Google Apps / G Suite | openconnector.connector.GoogleAppsDirect sailpoint.connector.OpenConnectorAdapter | | IBM i | openconnector.connector.IBMiConnector | | Lotus Domino | sailpoint.connector.LotusDomino | | JDBC | sailpoint.connector.JDBCConnector | | Sun One LDAP | sailpoint.connector.LDAPConnector | | Linux | openconnector.connector.unix.LinuxConnector sailpoint.connector.OpenConnectorAdapter sailpoint.connector.UnixConnector | | Microsoft Office365 | sailpoint.connector.Office365Connector | | Microsoft SQL Server | sailpoint.connector.mssql.serviceimpl.MSSQLServerConnectorV2 | | Okta | logger.openconnector.name = openconnector.connector.okta.OktaConnector logger.openconnector.level = debug logger.openconnector.additivity = false logger.openconnector.appenderRef.rolling.ref = STDOUT | | Oracle Database | sailpoint.connector.OracleDBConnector sailpoint.connector.JDBCConnector | | Oracle E-Business | sailpoint.connector.OracleEBSConnector sailpoint.connector.JDBCConnector | | Oracle Fusion HCM | openconnector.connector.oraclefusionhcm.OracleFusionHCMConnector sailpoint.connector.OpenConnectorAdapter | | Oracle HCM Cloud | sailpoint.connector.oraclehcmcloud.OracleHCMCloudConnector | | Oracle HRMS | sailpoint.connector.OracleAppsHRMSConnector sailpoint.connector.JDBCConnector | | Oracle Netsuite | openconnector.connector.netsuite.NetsuiteConnector | | PeopleSoft ERP | openconnector.connector.PeopleSoftConnector sailpoint.connector.OpenConnectorAdapter | | PeopleSoft HRMS | sailpoint.connector.PeopleSoftHRMSConnector | | RemedyForce | sailpoint.connector.ForceConnector | | RSA Authentication Manager | openconnector.connector.RSAConnector openconnector.connector.rsa.RSAHTTPClient sailpoint.connector.OpenConnectorAdapter | | Salesforce | sailpoint.connector.ForceConnector | | SAP Concur | openconnector.connector.sapconcur.SAPConcurConnector | | SAP - Direct | sailpoint.connector.SAPConnector sailpoint.connector.SAPInternalConnector | | SAP GRC | logger.SAPGRCConnector.name = sailpoint.connector.sapgrc logger.SAPGRCConnector.level = debug logger.SAPGRCConnector.additivity = false logger.SAPGRCConnector.appenderRef.rolling.ref = STDOUT | | SAP HR/HCM | sailpoint.connector.SAPHRInternalConnector | | SCIM 1.1 | openconnector.connector.SCIMConnector sailpoint.connector.OpenConnectorAdapter | | SCIM 2.0 | openconnector.connector.scim2.SCIM2Connector sailpoint.connector.OpenConnectorAdapter | | ServiceNow | openconnector.connector.servicenow.ServiceNowConnector openconnector.connector.servicenow.ServiceNowRestClient sailpoint.connector.OpenConnectorAdapter | | ServiceNow Service Desk Integration | openconnector.connector.servicedesk.ServiceNowServiceDeskConnector sailpoint.connector.OpenConnectorAdapter | | Siebel | openconnector.connector.SiebelConnector sailpoint.connector.OpenConnectorAdapter | | Snowflake | openconnector.connector.snowflake.SnowflakeConnector sailpoint.connector.OpenConnectorAdapter | | Solaris | openconnector.connector.unix.SolarisConnector openconnector.connector.unix.UnixConnector sailpoint.connector.OpenConnectorAdapter | | SuccessFactors | sailpoint.connector.SuccessFactorsConnector | | Sybase | sailpoint.connector.SybaseDirectConnector sailpoint.connector.JDBCConnector | | Webex | openconnector.connector.Webex sailpoint.connector.OpenConnectorAdapter | | Workday | openconnector.connector.WorkDay sailpoint.connector.OpenConnectorAdapter | | Workday Accounts | openconnector.connector.workdayaccounts openconnector.connector.workdayaccounts.WorkdayAccountsConnector sailpoint.connector.OpenConnectorAdapter | | Web Services | sailpoint.connector.WebServices | | XML | openconnector.connector.XMLConnector sailpoint.connector.OpenConnectorAdapter | | Yammer | openconnector.connector.YammerConnector sailpoint.connector.OpenConnectorAdapter | | Zoom | openconnector.connector.zoom.ZoomConnector sailpoint.connector.OpenConnectorAdapter | # Troubleshooting If you encounter any of the following issues or errors, SailPoint recommends that you follow the guidance provided below to resolve the error before contacting SailPoint Support. For issues or errors that are not addressed in this connector guide, refer to the following resources for troubleshooting information: - [SailPoint Identity Services Documentation]() - [SailPoint Support Knowledge Base]() - [SailPoint Developer Community]() ## Create account operation fails while using recommended mappings in the Account Policy The create account operation fails even though the recommended attribute mappings are used in the Account Policy. **Resolution** - Ensure that the managed system is enabled to set the account attributes used by the Account Policy, then try the Create account operation again. ## Attribute values in Compliant Settings are not populated after aggregation and/or provisioning processes You try to add a new attribute to Compliant Settings from the SCIM server endpoint schema to the account schema, but aggregation processes don't fetch the attribute value, and/or provisioning processes don't send the attribute to the managed system. **Resolution** - Perform a [Discover Source]() operation, and then run an unoptimized account aggregation. ## Extended schema attributes for Group objects are not aggregated Additional attributes added for Group objects are not included in entitlement aggregation. **Resolution**: - **Compliant** - Add the required attributes to the group object schema and run an entitlement aggregation process. - **Non-Compliant** - Add the required attributes to the group object schema, and also properly map their respective JSON paths in the source, then run an entitlement aggregation process. ## Endpoint is required for Non-Compliant **Resolution**: If the Non-Compliant checkbox is enabled the connector will reach the following endpoints only from the SCIM server: ```text /Users - For Test Connection, Preview, Aggregation, and Provisioning. /Groups - For Aggregation and Provisioning. ``` The following endpoints are not required if Non-Compliant is enabled: ```text /Schemas /ResourceTypes /ServiceProviderConfigs ``` The schema that gets discovered when enabling the Non-Compliant setting is the default schema the connector provides Out-Of-the-Box (OOB). If any new attribute needs to be added, you must add it in the schema along with its valid JSON path in the JSON path attribute Mapping. ## ResourceObject error message displays during aggregation During aggregation the following error message displays: ```text ResourceObject is returned with null identity error ``` **Resolution**: Verify if the identity attribute is in the schema attribute else add the appropriate schema attribute name as identity attribute. ## Aggregation fails with SSL peer shut down errors Messages: ```text org.json.JSONException: SSL peer shut down incorrectly Remote host terminated the handshake ``` **Resolution**: Configure the following in the application via the REST API: 1. Set the `SSL_PROTOCOL_VERSION` to **TLSv1.2** or **TLSv1.3** to reflect your SSL version. 2. Set the `trustAllCert` attribute to `true`. 3. Set the `allowAllHosts` attribute to `true`. ## Groups (entitlements) aren't aggregated due to non-compliance **Resolution**: If the entitlement aggregation process doesn't aggregate groups then verify the following: - Check if the SCIM server has the `{host} /Group` endpoint available with the group's data. - If the group endpoint is not available, then groups can be aggregated using the `/User` endpoint. However, the group data should be in the `/User` endpoint's response. The following RFC shows the Representation of Users with group information. This has to be implemented in the SCIM server. [RFC 7643: System for Cross-domain Identity Management: Core Schema]() - Refer to the *Full User Representation* section. ## Incorrect JSON formed during Create/Modify account using multi-valued schema attributes **Resolution**: Ensure to enable the `provisionMultivaluedRFCCompatible` parameter to support the correct JSON for provisioning multivalued schema attributes. Add the following attribute using the REST API for updating the source in SailPoint and then, try modifying the system to date of a user: `key=provisionMultivaluedRFCCompatible` `value=true` > [!NOTE] > > `provisionMultivaluedRFCCompatible` is a boolean attribute. ## The manager attribute isn't included in provisioning The connector doesn't provision the `manager` attribute from SCIM-compliant sources. **Resolution**: 1. Add the `splitManager` attribute to the source.xml and set it to `true` using the REST API. 2. Remove `` from the source. 3. Run a **Discover Schema** process. > [!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. ## Account aggregation fails with ConnectorException: Resource doesn't exist Account aggregation fails with the following error: ```text ConnectorException: Resource doesn't exist ``` The SCIM 2.0 connector identifies payloads from `meta.resourceType`. If list-level `meta` exists without `resourceType` on `/ResourceTypes` or `/Users`, aggregation fails with `Resource doesn't exist`. Example: ```json { "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"], "meta": { "location": "https://example.com/Users" }, "Resources": [{ "id": "123", "userName": "jdoe" }] } ``` **Resolution**: Review the `/ResourceTypes` and `/Users` responses and verify that `meta.resourceType` is present. Contact the SCIM server team to add `meta.resourceType` to the response as described in [RFC 7643: System for Cross-domain Identity Management: Core Schema](). # Timeout Errors and Settings Timeout errors might occur when SailPoint is waiting for a response from the Virtual Appliance (VA). These errors are applicable to all connectors and tend to occur during the setup of sources or when sources are down. This document is designed to give specific information that can be used to resolve these errors. Each timeout attribute has a default time value that is listed in seconds or minutes. Increasing the time value may resolve the error as it will allow for longer communication time between the two systems, thus avoiding the timeout error. > [!IMPORTANT] > > Add the necessary attributes or values before performing the "replace" operation, as missing attributes will cause the operation to fail. To increase the communication time, increase the value of the appropriate timeout attribute. Then submit the change to the VA using the SailPoint 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. ### aggregateTimeout **Description:** This parameter is set for the aggregation timeout, measured in seconds. **Resolution:** Increase the `aggregateTimeout` value gradually to optimize aggregation. Start with 180, then increase to 600, 900, and finally 1800. The maximum value is 3600 seconds. For example: If your current time value is 180 seconds, update the `aggregateTimeout` attribute as follows: ```json [ { "op": "replace", "path": "/connectorAttributes/aggregateTimeout", "value": 600 } ] ``` ### healthCheckTimeout **Description:** This parameter is set for the test connection and health check timeout. **Resolution:** The default value is 30 seconds. If the timeout error continues, increase the value in 15 second increments and try again. For example: If your current time value is 30 seconds, update the `healthCheckTimeout` attribute as follows: ```json [ { "op": "replace", "path": "/connectorAttributes/healthCheckTimeout", "value": 45 } ] ``` ### provisioningTimeout **Description:** This parameter is set for provisioning timeout. **Resolution:** Increase the `provisioningTimeout` value gradually to optimize provisioning. Start with 180, then increase to 360, and finally 600. The maximum value is 600 seconds. For example: If your current time value is 180 seconds, update the `provisioningTimeout` attribute as follows: ```json [ { "op": "replace", "path": "/connectorAttributes/provisioningTimeout", "value": 360 } ] ``` ### timeout **Description:** This parameter is set for pass-through authentication timeout. **Resolution:** The default value is 15 seconds. If the timeout error continues, increase this value in 15 second increments and try again. For example: If your current time value is 15 seconds, update the `timeout` attribute as follows: ```json [ { "op": "replace", "path": "/connectorAttributes/timeout", "value": 30 } ] ``` ### apiTimeout **Description:** This parameter is set for API time tracking; customers can check it using an external tool. **Resolution:** The default value is 60 seconds. If the error continues, increase the value by 15 second increments and try again. For example: If your current time value is 60 seconds, update the `apiTimeout` attribute as follows: ```json [ { "op": "replace", "path": "/connectorAttributes/apiTimeout", "value": "75" } ] ``` ### timeoutInSeconds **Description:** This parameter helps prevent the VA from waiting indefinitely for an API response, ensuring efficient handling of API requests. For example: If your current time value is 30 seconds, update the `timeoutInSeconds` attribute as follows: ```json [ { "op": "replace", "path": "/connectorAttributes/timeoutInSeconds", "value": "15" } ] ```