# Identity Security Cloud Governance SaaS Connector > SailPoint Identity Security Cloud Governance SaaS Connector Documentation # Documentation # Connecting SailPoint and Identity Security Cloud Governance SaaS To connect SailPoint with Identity Security Cloud Governance, 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. (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](). 9. 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](). 10. Select **Continue**. The source is created, and you are navigated to the **Source Setup \> Base Configuration** page. Continue to configure your connected source there. ## Connection Settings The following information is required for SailPoint to connect and interact with Identity Security Cloud Governance. > [!NOTE] > > **Screenshot** > > [![Connection Settings]()]() 1. Enter the **API URL** path used to connect to the target tenant. 2. Select the **Grant Type** as Client Credentials. 3. Enter the **Client ID** of the managed system. 4. Enter the **Client Secret** of the managed system. 5. Enter the time span in **Connection Timeout** after which an aggregation operation terminates. 6. Select **Save**. ## Aggregation Settings This section provides the details required for aggregating the user accounts. For more information about aggregation, refer to [Loading Account Data](). > [!NOTE] > > **Screenshot** > > [![Aggregation Settings]()]() 1. Go to **Aggregation Settings \> Filter Settings**. 2. Enter the appropriate **Account Aggregation Filter**. For more information, refer to [Account Aggregation Filter](<#account-aggregation-filter>). 3. Enter the appropriate **Governance Group Aggregation Filter**. For more information, refer to [Governance Group Aggregation Filter](<#governance-group-aggregation-filter>). 4. Enter the number of records in **Page Size** to aggregate in a single page when iterating over large datasets. You can set it from 1 to 250. The default is 200. 5. Select **Enable User Level Caching** to create cache objects of user levels for faster access during account aggregation. > **Note** > > During update, it may create additional cache, which can affect aggregation and get object operation. 6. Select **Save**. > [!NOTE] > > If no filters are applied, the system will fetch all available data. ### Account Aggregation Filter Following operators and attributes are supported. | Attribute | Operator | | --- | --- | | id | eq, in | | Name | eq, sw | | email | eq, sw | | First Name | eq, sw | | Last Name | eq, sw | For example, to filter account names starting with ISCUser, use `name sw "ISCUser"`. ### Governance Group Aggregation Filter Following operators and attributes are supported. | Attribute | Operator | | --- | --- | | id | eq, in | | Name | eq, sw | For example, to filter Governance Groups with names starting with "ISCGroup," use `name sw "ISCGroup"`. ## Reassignment Settings > [!NOTE] > > **Screenshot** > > [![Reassignment Settings]()]() 1. Select the **Objects** and **Tasks** owned by a user to reassign to their Identity Manager after the governance account user is disabled. Your selections apply to all objects and tasks of that type. > **Note** > > The **Pending Request Decisions** checkbox reassigns access request decisions (approvals) only if the disabled user is also the owner of an access item, such as an access profile. 2. Select **Save**. > [!NOTE] > > To ensure the effective functioning of reassignment, it is essential for the identities to have a direct line manager. Without this, the objects and tasks cannot be reassigned. ## 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. # Enable/Disable Statuses of Accounts The SailPoint Identity Security Cloud Governance connector resolves enable/disable statuses of accounts using customizers. For more information, refer to [Customizers]() and follow the steps to create, deploy, and link the customizer to the source using the SailPoint CLI. > [!IMPORTANT] > > Manually enabling or disabling the Identity Security Cloud Governance connector may produce unreliable results. SailPoint recommends performing these actions only through lifecycle status changes. To use the customizer for the Identity Security Cloud Governance connector, follow these steps: 1. Add the following attributes to the Account Schema of the Identity Security Cloud Governance connector: | Attribute Name | Type | | --- | --- | | identityState | String | | identityStatus | String | > **Note** > > These attributes are mandatory for the customizer to function properly. 2. Update the `index.ts` file according to your requirements from the initial project source directory. Refer to the provided [customizers\_example.ts]() file for making any changes. > **Note** > > If a customizer is already deployed, integrate the sample changes into the existing customizer instead of deploying a new one. # Integrating SailPoint with Identity Security Cloud Governance SaaS The SailPoint Identity Security Cloud Governance connector extends governance and access management capabilities to identities in a SailPoint Human Fabric tenant. This connector treats the tenant as a governed system and manages identities as accounts. The connector also manages user levels (permissions), roles, and governance groups as entitlements. This guide is designed to give specific information about the requirements and field definitions needed to get a working instance of the Identity Security Cloud Governance connector. > [!NOTE] > > To view the latest features, enhancements, and fixes for all SaaS connectors, refer to the [SaaS Release Notes]() page. ## Supported Features #### Account Management - Manages identities as accounts - Aggregate and Refresh Accounts - Full Account Aggregation - Single Account Aggregation - Account Aggregation Filters (Governance Groups Aggregation) - Create Accounts - Enable/Disable Accounts - Add/Remove Entitlements #### Entitlement Management - Manages Governance Groups, and User levels (Permissions) as Entitlements - Aggregation > [!IMPORTANT] > > Due to API limitations, the Identity Security Cloud Governance connector aggregates user levels in entitlement aggregation, and these levels are predefined within the connector. However, during account aggregation, the connector retrieves all the user levels assigned to the account. For more information, refer to [User Levels in Entitlement Aggregation](). - Entitlement Aggregation Filters (Governance Groups Aggregation) ## Prerequisites The Identity Security Cloud Governance connector uses a personal access token for authentication. To use this authentication method, create a client ID and client secret in your tenant. > [!NOTE] > > **Steps for creating Client ID and Client Secret** > > 1. Select **Preferences** from the dropdown menu under your username, then select **Personal Access Tokens**. You can also go directly to the page by using this URL : `https://{tenant}.identitynow.com/ui/d/user-preferences/personal-access-tokens` Replace `{tenant}` with your tenant name. > 2. Select **New Token** and enter a meaningful description to help differentiate the token from others. > 3. Provide required permissions under **Scopes**. > 4. Select **Create Token** to generate and view the two components that comprises the token: `Client ID` and `Client Secret`. > 5. Copy and save **Client ID** and **Client Secret** at a safe and accessible place to retrieve later whenever needed. For more information, refer to [Authentication](). ## Required Permissions A user with ORG\_ADMIN user level access is required with the following scopes to perform necessary operations: | Operations | Scopes | | --- | --- | | Test Connection | sp:scopes:default | | Aggregation | idn:identity:read
idn:identity:manage
idn:workgroup:read | | Enable/Disable | sp:search:read
idn:accounts:read
idn:accounts:manage
idn:accounts-state:manage
idn:account-provisioning:manage | | Governance Groups Aggregation | idn:workgroup:read | | Add/Remove Identity Security Cloud Governance Groups | idn:workgroup:manage | | Add/Remove User Levels | sp:auth-user:manage | | Add/Remove Roles | idn:role-unchecked:manage | | Disable with Reassign | idn:access-profile:manage
idn:sources:manage
idn:workgroup:manage
idn:entitlement:manage
sp:workflow:manage
idn:campaign:manage
idn:access-request-approvals:manage | # Provisioning The Identity Security Cloud Governance SaaS connector supports provisioning, allowing you to create and manage accounts and entitlements in Identity Security Cloud Governance 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 | Account Attribute | Type | Generator | Description | | --- | --- | --- | --- | | id | String | Identity Attribute | The unique ID (username) used as login. | > [!NOTE] > > The id attribute under the Create Account profile should contain the ID of an identity from the SailPoint Human Fabric tenant configured in the **Connection Settings** of the Identity Security Cloud Governance source. # Retry Configurations The connector can retry an operation if it fails. The `retryMessages` and `retryCodes` attributes are a list of strings and codes respectively, through which the connector searches when it receives a message from the source. To take advantage of this feature, configure a list of messages and codes to the attributes map in a source. If one of the strings or codes in the entry is in the error list, the connector attempts to retry the operation. If the configured error string or code is not a part of the error message, then the connector will not reattempt the operation. Add the following entry in the source XML using the SailPoint REST APIs. For example: ```http PATCH https://{orgName}.api.cloud.sailpoint.com/v3/sources/{SourceID} [ { "op": "replace", "path": "/connectorAttributes/retryMessages", "value": [ "Connection reset" ] } ] ``` ```http PATCH https://{orgName}.api.cloud.sailpoint.com/v3/sources/{SourceID} [ { "op": "replace", "path": "/connectorAttributes/retryCodes", "value": [ "503 Service Unavailable" ] } ] ``` > [!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] > > 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. # 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 Identity Security Cloud Governance SaaS connector uses the following default correlation and object configurations. ## Default Correlation Configuration Before you aggregate accounts from this source, you can map account attributes with their corresponding identity attributes based on your requirements. You can customize the correlation configuration. Refer to [Assigning Source Accounts to Identities]() for more information. When you first create the Identity Security Cloud Governance SaaS source, the default correlation mapping is: | Account Attribute | Operation | Identity Attribute | | --- | --- | --- | | uid | Equals | SailPoint Username (uid) | | email | Equals | Work email | ## 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 Attributes The Identity Security Cloud Governance SaaS connector supports the following default account schema attributes and customer configurable attributes. The attributes must be defined as strings if not specified. | Attribute Name | Description | | --- | --- | | id | The user ID. This is an account ID that must not be changed. | | name | The user name | | firstName | The user's first name | | lastName | The user's last name | | isManager | Identifies whether account is manager or not Type: Boolean | | email | The user's work email | | displayName | The user's display name | | Governance Groups | Governance Group Associated With Account (Entitlement, Multi-Valued) Type: Governance Groups | | Roles | Roles associated with Account (Entitlement, Multi-Valued) Type: Roles | | UserLevels | Capabilities associated with Account (Entitlement, Multi-Valued) Type: UserLevels | | uid | The user name | > [!NOTE] > > By default, the Identity Security Cloud Governance Connector supports the following 2 entitlement attributes: "Governance Groups" and "UserLevels". These can be removed as per requirement. For example, if you want to manage only **User Levels** as entitlements, you can remove "**Governance Groups**" from the account schema, and remove the respective object types from the Entitlement schema page. ## Default Entitlement Attributes Entitlement attributes define the entitlements, such as groups or roles, that can be assigned to the managed system's user accounts. Refer to [Managing Entitlements]() for more information. > [!CAUTION] > > Changing the attribute marked as the Entitlement ID after aggregating accounts or entitlements can result in duplicate entitlements being created, or access profiles and roles breaking. To avoid this, edit the entitlement schema before performing any aggregations. ### Default Group Attributes The Identity Security Cloud Governance SaaS connector also supports groups. The following attributes must be configured on the managed system and in the SailPoint source schema to manage groups. #### Entitlement Type: Governance Groups | Attribute Name | Description | | --- | --- | | id | Governance Group ID This is an Entitlement ID which must not be changed. | | name | Governance Group Name | | description | Governance Group description | #### Entitlement Type: UserLevels | Attribute Name | Description | | --- | --- | | name | User Level Name | | id | User level ID This is an Entitlement ID which must not be changed. | | description | User levels description | # 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]() ## Debug Logs For information about managing additional source settings, including debug logging and downloading connector logs, refer to [Managing Additional Settings](). > [!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. ## Multiple access error **Issue**: SailPoint Identity Security Cloud Governance connector does not provision multiple access simultaneously. **Resolution**: This is an API limitation wherein more than one entitlement cannot be requested simultaneously. You may either send a request for two entitlements one after another or include all required entitlements in a single access profile and then, provision it. ## Test connection fails while generating token **Issue**: The following error appears during test connection: `[ConnectorError] Error while generating token: xxxxxxx Bad client credentials (requestId: xxxxxxxxx)` **Resolution**: Create an IP Address Allow List to enable access to the API. For more information regarding the steps to configure the IP Address Allow List, refer to [IP Address Allow List](). ## Aggregation filters other than those documented are not working **Resolution**: The connector supports only the filters listed on [this page](); any other filters, such as "like" is not supported. ## Command timed out error during provisioning **Issue**: The following error appears during any provisioning operation: `sp-connect command timed out.` **Resolution**: Add the following entry to the source XML using the REST API in the body of the PATCH request: `[{ "op": "add", "path": "/connectorAttributes/provisioningTimeout", "value": "600" }]` > [!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. ## Update account operation fails with status code 400 **Issue**: The following error appears during update account operation: `[ConnectorError] update account operation failed for: xxxxxxx Request failed with status code 400 (requestId: xxxxxxxxx)` **Resolution**: Ensure to deselect **User Level Caching** to avoid creating cache during update, and then retry performing update account operation. For more information, refer to [Aggregation Settings](). ## Account aggregation is failing with the error codes 502 and 504 **Resolution**: Add the following entry to the source XML using the REST API in the body of the PATCH request (the value can be increased up to 3600): `[{ "op": "add", "path": "/connectorAttributes/aggregateTimeout", "value": "600" }]` ## Read User (Get Object) is not bringing updated details after create or update provisioning operation If the read user (get object) operation is not bringing updated details without any errors after a create or update provisioning operation, follow the resolution steps below. **Resolution**: Add the following entry to the source XML using the REST API in the body of the PATCH request: `[{ "op": "add", "path": "/connectorAttributes/getObjectDelay", "value": 25 }]` The default value of `getObjectDelay` is 20 seconds. This entry sets the `getObjectDelay` attribute to 25 seconds, allowing sufficient time for the changes to propagate before the read user (get object) operation is performed. ## Enable/Disable status not showing properly for accounts **Resolution**: Ensure that the `identityState` and `identityStatus` attributes are added to the **Account Schema** of the SailPoint Identity Security Cloud Governance connector configuration page. For more information, refer to [Enable/Disable Statuses of Accounts](). > [!NOTE] > > To create, deploy, and link the customizer to the source using the SailPoint CLI, refer to [Customizers]() documentation in the SailPoint developer community. ## Request failed with status code 400 during Identity Refresh This error can occur during an Identity Refresh on the SailPoint Identity Security Cloud Governance connector when the system attempts to add an invalid user level to an identity. **Resolution**: To resolve this issue, assign a valid User level other than Access Intelligence Center - Admin (`sp:aic-dashboard-admin`). For more information, refer to [User Levels in Entitlement Aggregation](). ## User Level is not brought during account aggregation **Issue**: The SailPoint Identity Security Cloud Governance connector does not bring User Level during account aggregation. **Resolution**: Select **Enable User Level Caching** on the source configuration page. For more information, refer to [Aggregation Settings](). # User Levels in Entitlement Aggregation Due to API limitations, the Identity Security Cloud Governance connector aggregates user levels in entitlement aggregation, and these levels are predefined within the connector. However, during account aggregation, the connector retrieves all the user levels assigned to the account. Following is the list of user levels included in entitlement aggregation: | ID | Name | Description | | --- | --- | --- | | HELPDESK | Helpdesk | Helpdesk access to the tenant | | ORG\_ADMIN | Admin | Full administrative access to the tenant | | CERT\_ADMIN | Cert Admin | Cert Administrator access to the tenant | | REPORT\_ADMIN | Report Admin | Report Administrator access to the tenant | | ROLE\_ADMIN | Role Admin | Role Administrator access to the tenant | | ROLE\_SUBADMIN | Role Sub-admin | Role SubAdministrator access to the tenant | | SOURCE\_ADMIN | Source Admin | Source Administrator access to the tenant | | SOURCE\_SUBADMIN | Source Sub-admin | Source Subadministrator access to the tenant | | CLOUD\_GOV\_ADMIN | Cloud Gov Admin | Cloud Gov Admin access to the tenant | | CLOUD\_GOV\_USER | Cloud Gov User | Cloud Gov User access to the tenant | | sp:aic-dashboard-read | Access Intelligence Center - Reader | Access Intelligence Center - Reader access to the tenant | | sp:aic-dashboard-write | Access Intelligence Center - Author | Access Intelligence Center - Author access to the tenant | | sp:aic-dashboard-admin | Access Intelligence Center - Admin | Access Intelligence Center - Admin access to the tenant | | sp:ui-config-hub-admin | Configuration Hub Admin | Admin access to Configuration Hub | | sp:ui-config-hub-backup-admin | Configuration Hub Backup Admin | Backup Admin access to Configuration Hub | | sp:ui-config-hub-read | Configuration Hub Reader | Reader access to Configuration Hub | | SAAS\_MANAGEMENT\_ADMIN | SaaS Management - Admin | Admin access to SaaS Management | | SAAS\_MANAGEMENT\_READER | SaaS Management - Reader | Reader access to SaaS Management | | das:ui-administrator | Data Access Security Administrator | Administrator access to Data Access Security | | das:ui-compliance\_manager | Data Access Security Compliance Manager | Compliance Manager access to Data Access Security | | das:ui-data\_owner | Data Access Data Owner | Data Owner access to Data Access Security | | das:ui-auditor | Data Access Security Auditor | Auditor access to Data Access Security | | idn:access-request-administrator | Access request administration | Access request administration access to the tenant | | idn:access-request-administrator-read | Access Request Administration Read Only | Access Request Administration Read Only access to the tenant |