# SailPoint Salesforce Connector Documentation > Salesforce VA-Based Connector Documentation # Documentation # Configuring Aggregation ## Aggregation Settings Define the scope of the records to fetch when aggregating user accounts and entitlements. > [!NOTE] > > **Screenshot** > > [![Aggregation Settings]()]() 1. (*Optional*) Select **Exclude Frozen Accounts** to exclude frozen user accounts. These accounts have the Salesforce attribute `IsFrozen` set to `true`. 2. (*Optional*) Select **Exclude Disabled Accounts** to aggregate only active accounts. This adds the following condition in the `where` clause of the search query for users: `AND user.IsActive = true` 3. (*Optional*) Select **Disable User Creation Email** to disable sending emails when a user is created. 4. (*Optional*) Select the **Create Contact on User Creation** option to enable the creation of new Salesforce contacts at the same time you create new users. The newly created contacts use the same attribute data provided for the new users as applicable. > **Note** > > SailPoint only supports simultaneous contact creation during user creation at this time. Simultaneous contact updates and deletions during user updates or deletions aren't supported. Afterward, if you want to add a new attribute for a contact that is also available as a user attribute, add the following entry key into the source XML: ```xml Custom_Attribute NewAttribute ``` Refer to [Best Practices: REST API Authentication]() and [REST API - Update Source (Partial)]() for more information. 5. Enter the **Page Size**, which is the number of records to aggregate in a single page when iterating over large datasets. *Default: 2000 records* 6. Enter the scope of the users that are retrieved during Account or Entitlement aggregation in **Search Query for Users**. For more information, refer to [Search Query for Users and Profiles](<#search-query-for-users-and-profiles>). 7. Enter the scope of the profiles that are retrieved during account or entitlement aggregation in **Search Query for Profiles**. For more information, refer to [Search Query for Users and Profiles](<#search-query-for-users-and-profiles>). 8. Enter the string for the public groups that are retrieved during account or entitlement aggregation in **Search String for Public Groups**. 9. Enter the string for the roles that are retrieved during account or entitlement aggregation in **Search String for Role**. 10. Enter the string for the permission sets that are retrieved during account or entitlement aggregation in **Search String for Permission Set**. 11. Select **Save**. ## Aggregating Only Active Users The Salesforce source has an option to aggregate only active users. To configure the Salesforce source to only aggregate active accounts: 1. In the Salesforce, go to the **Aggregation Filters** panel. 2. Check the **Exclude Disabled Accounts** box. ## Search Query for Users and Profiles Configure the search queries for users and profiles in the Salesforce source. On the Salesforce UI, in the **Aggregation Filter** panel, in the **Search Query for Users** field enter the scope of the users that are retrieved during Account or Entitlement aggregation. In the **Search Query for Profiles** field, enter the scope of the profiles that are retrieved during account or entitlement aggregation. For instance, specifying the following search query, retrieves only active users during account aggregation: `select Id from User where IsActive = true` The scope users or profiles retrieved during aggregation can be defined using custom attributes in the `where` clause, as follows: `select Id from Profile where Name = xyz` > [!NOTE] > > - The Salesforce source escapes special characters such as `<`, `>`, and `&` in a search query string and in entitlement provisioning. > - Only the `where` clause of the search query can be modified per the requirement. > - When **Exclude Disabled Account** is enabled, the connector adds the following condition in the `where` clause of Search Query for Users: > > `AND user.IsActive = true` > - If the where clause contains an apostrophe ('), use a backslash (\\) prefix to escape it. For example: > > `Find Id,username from user where lastname is buru'4` > > `Expected Query: Select Id,username from user WHERE lastname ='buru\'4'` > - If **Manage Active Accounts** is selected, the connector adds the same `AND user.IsActive = true` condition into the `where` clause of the user search query. # Configuring ECA Authentication ## External Client Application (ECA) Authentication To configure External Client Application (ECA) authentication, complete the following steps: > [!IMPORTANT] > > Before you begin, install External Client Application from Salesforce AppExchange. For information, refer to [Installing External Client Application](<#installing-external-client-application>). > [!NOTE] > > **Screenshot** > > [![External Client Application authentication]()]() 1. Turn on the **Enable External Client App (ECA)** toggle. 2. Under **Client configuration**, enter the required key-value pairs: 1. In the **Key** box, enter the key as `host_name`. 2. In the **Value** box, enter the **Token URL** to generate the token. For example: `test.salesforce.com` or `login.salesforce.com`. 3. Select **Save**. 4. Select **Authorise**. > [!NOTE] > > - The **Human** account you use to authorise the ECA must have adequate permissions to manage the required Salesforce objects. > - If you encounter issues with ECA authentication, you can turn off the feature and revert to your previous, working configuration. ### Important Considerations for Salesforce ECA Integration **Maximum concurrent tokens:** Salesforce limits active refresh tokens to five per user for each External Client App (ECA) or Connected App. If you request a sixth connection, Salesforce automatically and silently revokes the oldest active token to accommodate the new request. **Revoked token reuse:** If an authenticated source attempts to authenticate by using a previously revoked token (such as the silently dropped oldest token), Salesforce flags the attempt as a critical security threat. As a result, Salesforce immediately invalidates all active refresh tokens and sessions for that user across all clients. If this occurs, you must reauthorize the integration to continue. ### Installing External Client Application Perform the following steps to install External Client Application: 1. Go to [SailPoint Identity Security for Salesforce]() on AppExchange, and select **Get It Now**. 2. Enter your Salesforce credentials to authorize the installation. 3. Select the installation option that aligns with your organization's security requirements. For more information on configuring External Client Application (ECA) authentication, refer to [External Client Application Authentication](<#external-client-application-eca-authentication>). # Configuring Legacy Authentication The Basic and OAuth 2.0 authentication types are deprecated and will be removed in a future release. SailPoint recommends [External Client Application (ECA) authentication]() for new and existing connections. ## Basic Authentication (Deprecated) The following information is required if the Basic Authentication type is selected. > [!NOTE] > > **Screenshot** > > [![Basic authentication]()]() 1. Enter the fully qualified URL to the root of the Salesforce server in **Salesforce URL**. For example: `http://login.salesforce.com/services/Soap/u/` To find your site's URL, sign in to Salesforce.com, and perform the following: 1. Select **Develop** under the Application heading. 2. Select **API \> Generate Partner WSDL**. 3. Select **Generate**. The URL is located under the *SalesforceService* service name. 2. Enter the Salesforce **Service Account** that has the required permissions. 3. Enter the **Password** that is used to sign in to the managed system. > **Note** > > This is the API user's Salesforce.com password. If the client's IP address has not been added to your organization's allowed list, you must add a security token to your password for OAuth 2.0 authentication. 4. Select **Save**. ## OAuth 2.0 Grant Type: Password (Deprecated) The following information is required if the Password Grant Type is selected. **Prerequisites:** To support the Password grant type, you must create a connected application on the Salesforce system. For more information on creating the connected application, refer to [Create a Connected App]() in the Salesforce documentation. > [!NOTE] > > The linked document is not maintained by SailPoint and is subject to change without notice. After creating the connected application, you can get the Consumer Key and Consumer Secret from the connected application. > [!NOTE] > > **Screenshot** > > [![OAuth 2.0 Password grant type]()]() 1. Enter the Salesforce **Service Account** name with the required permissions. 2. Enter the **Password** used to sign in to the managed system. This is the API user's Salesforce.com password. > **Note** > > If the client's IP address has not been added to your organization's allowed list, you must add a security token to your password for OAuth 2.0 authentication. 3. Enter the Consumer Key and Secret from the Salesforce connected application in **Client ID** and **Client Secret**. Refer to [OAuth 2.0 Authentication Prerequisites](<#oauth-20-grant-type-password-deprecated>) for more information. 4. Select **Save**. ## OAuth 2.0 Grant Type: JWT (Deprecated) The following information is required if the JSON Web Token (JWT) Grant Type is selected. > [!NOTE] > > **Screenshot** > > [![OAuth 2.0 JWT grant type]()]() 1. Enter the Salesforce username in **Subject**. 2. Enter the OAuth Client ID for the connected application for which you registered the certificate in **Issuer**. 3. Enter the recipient for which the JWT is intended in **Audience**. 4. Enter the **Private Key** to be used to assert the JWT. For information on generating the JWT assertion, refer to [Generating a JWT Assertion](<#generating-a-jwt-assertion>). > **Note** > > The private key should be in standard PKCS \#1 format. Currently, SailPoint doesn't support private keys in PKCS \#8 format. 5. Enter the **Private Key Password** for the Private Key. > **Note** > > This is only needed if the Private Key is encrypted with a passphrase. 6. Select **Save**. > [!NOTE] > > Additional JWT Header and JWT Payload can be added with the `additionalJwtHeader` and `additionalJwtPayload` attributes, respectively, using the REST API if required per the managed system. > > For information on the REST APIs, refer to [Authentication]() and [Update Source (Partial)]() in the SailPoint Developer Community. ### Generating a JWT Assertion Perform the following steps in Salesforce to generate a JWT Assertion: 1. Construct a JWT header with the following format: `{"alg":"RS256"}` Encode the header with **Base64url**. 2. Construct a **JSON Claims Set** for JWT with the following parameters and encode with **Base64url**: - **iss** - The issuer must contain the OAuth client\_id for the connected app for which you registered the certificate. - **aud** - The audience identifies the authorization server as an intended audience. The authorization server must verify that it is an intended audience for the token. Use the authorization server's URL for the `aud` if you are using the following values: `https://login.salesforce.com` `https://test.salesforce.com` or use the following if you are implementing for a community. `https://community.force.com/customers` - **sub** - The subject must contain the username of the Salesforce user or the Salesforce community user if implementing for a community. For backward compatibility, you can use principal (`prn`) instead of subject (`sub`). If both are specified, `prn` is used. - **exp** - The validity must be the expiration time of the assertion within 3 minutes, expressed as the number of seconds from 1970-01-01T0:0:0Z measured in UTC. The following is an example for **JSON Claim Set** for JWT. ```text {"iss": "3MVG99OxTyEMCQ3gNp2PjkqeZKxnmAiG1xV4oHh9AKL_rSK.BoSVPGZHQ ukXnVjzRgSuQqGn75NL7yfkQcyy7", "sub": "my@email.com", "aud": "https://login.salesforce.com", "exp": "1333685628"} ``` 3. Create a string for the encoded JWT Header and the encoded JWT Claims Set in this format. `encoded_JWT_Header + "." + encoded_JWT_Claims_Set` 4. Download the **X509** Certificate from JKS. 5. Sign the resulting string using **RSA SHA256**. 6. Create an Assertion string in the following format. `existing_string(Created in step 3) + "." + base64_encoded_signature` - API request to generate Access Token from JWT assertion: ```text POST /services/oauth2/token HTTP/1.1 Host: login.example.com Content-Type: application/x-www-form-urlencoded grant_type= urn:ietf:params:oauth:grant-type:jwt-bearer& assertion=eyJpc3MiOiAiM01WRz...[omitted for brevity]...ZT ``` ## OAuth 2.0 Grant Type: Refresh Token (Deprecated) The following information is required if the Refresh Token Grant Type is selected. > [!NOTE] > > **Screenshot** > > [![OAuth 2.0 Refresh Token grant type]()]() 1. Enter the Consumer key and secret from the Salesforce connected application in **Client ID** and **Client Secret**. For more information, refer to [OAuth 2.0 Authentication Prerequisites](<#oauth-20-grant-type-password-deprecated>). 2. Enter a non-expiring Salesforce **Refresh Token**. 3. Select **Save**. ### Generating a Refresh Token Perform the following steps in Salesforce to generate the refresh token: 1. In Salesforce, create a **New Connected App**. Consider the following as you configure the new connected app: - Salesforce generates a **Consumer Key** and **Consumer Secret** that can be found in **Manage Consumer Details**. Retain these for this process as you'll use them for the `client_id` and `client_secret` entries respectively. - Enter `https://login.salesforce.com/` as the **Callback URL**. This will be used later in this process. 2. Generate an authorization code that will be used to generate a refresh token. 1. Copy the URL below and substitute your values for the `Consumer Key` and the `Callback URL`: ```text https://login.salesforce.com/services/oauth2/authorize?response_type=code&client_id=&redirect_uri= ``` 2. Paste the modified URL into your browser and navigate to the page, then authenticate as needed. Select **Allow** to authorize access. After authorizing, the browser redirects you to the Callback URL you configured in the New Connected App. Note the authorization code appended to it. For example: `https://login.salesforce.com/?code=` If you have any issues generating the authorization code, ensure that **Require Proof Key for Code Exchange (PKCE) Extension for Supported Authorization Flows** is disabled in the Connected App in the Salesforce source. > **Important** > > You may need to URL-decode the authorization code before using it in the next step. 3. Generate a refresh token using the authorization code in POSTMAN. - **method** - POST - **URL** - `https://login.salesforce.com/services/oauth2/token` - **Body** - Add the following: ```text grant_type=authorization_code client_id= client_secret= code= redirect_uri= ``` You will receive the refresh token in the response this request returns. 4. (*Optional*) To test the refresh token, you can generate an access token. Create an API request to generate an access token using the refresh token as follows: ```text POST /services/oauth2/token HTTP/1.1 Host: login.salesforce.com client_id= client_secret= grant_type=refresh_token refresh_token= ``` ## OAuth 2.0 Grant Type: Client Credentials (Deprecated) The Salesforce connector supports the Client Credentials grant type for authentication. > [!NOTE] > > **Screenshot** > > [![OAuth 2.0 Client Credentials grant type]()]() To configure the client credentials grant type: 1. In the **Client ID** field, enter the Consumer Key from the Salesforce source. 2. In the **Client Secret** field, enter the Consumer Secret from the Salesforce source. 3. Select **Save**. # Connecting SailPoint and Salesforce To connect SailPoint with Salesforce, 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 In this section you will configure the direct connection between the source and SailPoint by specifying the authentication type and credentials to establish a secure connection. > [!IMPORTANT] > > Effective July 1, 2026, the External Client Application (ECA) is the recommended authentication method for the Salesforce connector. The Basic and legacy OAuth 2.0 authentication types are deprecated and will be removed in a future release. SailPoint strongly recommends configuring new connections by using ECA and migrating your existing connections. 1. Go to **Connection Settings**. 2. In the **Connection Timeout** field, specify a timeout value in minutes. The default value is `1`. 3. Under **Authentication Type**, select **Basic** or **OAuth 2.0** authentication. The fields change based on the option you choose: - [Basic Authentication (Deprecated)]() - OAuth 2.0 Authentication (Deprecated): Enter the OAuth 2.0 Token URL. If the Salesforce source is configured to use OAuth 2.0 authentication, the following URL is used to generate the access token by default: `https://login.salesforce.com/services/oauth2/token` - [OAuth 2.0 Grant Type: Password (Deprecated)]() - [OAuth 2.0 Grant Type: JWT (Deprecated)]() - [OAuth 2.0 Grant Type: Refresh Token (Deprecated)]() - [OAuth 2.0 Grant Type: Client Credentials (Deprecated)]() 4. Select **Save**. As an alternative to the Basic and OAuth 2.0 authentication types above, you can enable [External Client Application (ECA) authentication](). ## Aggregation Settings Define the scope of the records to fetch when aggregating user accounts and entitlements. Refer to [Configuring Aggregation](). ## Configuration Parameters This section contains the information that this connector uses to connect and interact with the source. Each source type requires different information to create and maintain a connection. The Salesforce connector uses the following connection parameters: > [!NOTE] > > All attributes marked with an asterisk (\*) are mandatory attributes. | Parameter | Description | | --- | --- | | Connection Timeout | Timeout value in minutes. Default - One minute. | | Disable User Creation Email Notification | Enable this to prevent emails from being sent when a user is created. | | Exclude Disabled Accounts | Enable this to exclude disabled users. This works by adding the following condition to the `where` clause of the search query for users: `AND user.IsActive = true` | | Exclude Frozen Accounts | Enable this to exclude users that have the flag value for `IsFrozen` set to true in Salesforce. | | Password\* | This parameter defines the password used for logging in to the managed system. This is the API user's Salesforce.com password. If the client's IP address has not been whitelisted in your organization, add a security token to your password for OAuth 2.0 authentication. Password must be `Account Password + Security Token`. For example, if you have account password such as SAilpoint123 and the security token is @34567, the combined password entry will be SAilpoin123@34567. | | Search Query for User/Profile | Determines the scope of the users or profiles that are retrieved during account or entitlement aggregation. Refer to [Search Query for Users and Profiles]() for details and examples. | | Service Account | Salesforce account with required permissions. | | Source Description\* | Details necessary to distinguish the source from other similar connection sources. | | Salesforce URL\* | Enter the fully qualified URL to the root of the Salesforce server. Not applicable if **Enable OAuth2 API** is selected. For example: `http://login.salesforce.com/services/Soap/u/26.0/` | To find the Salesforce URL for your site, log in to salesforce.com: 1. Select **Develop** under the **Application** heading. 2. Go to **API \> Generate Partner WSDL**. 3. Select **Generate**. The URL is located under the *SalesforceService* service name. ## Configuring Additional Features - To create portal or partner users, refer to [Creating Portal and Partner Users](). - To configure password management, refer to Password Management. ## Direct Permissions The Salesforce source supports the ability to read direct permissions for Group Profiles. In new sources, the `includePermissions` attribute is set to `true` by default in a given Group Profile schema. This attribute enables the connector to fetch the direct permissions associated to the Group Profile. For the pre-existing sources, perform the following steps to update the `includePermissions` attribute value for the group profile schema. - Use [listSources API]() to get the source ID for your source. - Use [listSchemas API]() to get the schema ID for the group profile schema for which you want to include direct permissions. - Use [updateSchema API]() and enter the following content in the body. ```json { "op": "replace", "path": "/includePermissions", "value": true } ``` After these steps, run entitlement aggregation to fetch the direct permissions associated to the Group Profile. ## 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 Salesforce SailPoint's Salesforce connector offers access management of Salesforce users. This integration with Salesforce gives you policy-based access controls so you can be sure only the right users can see and interact with critical information. This integration enables a deep level of access governance which not only allows you to manage internal users but also your public groups. You can search for specific information about the requirements and field definitions needed to get a working instance of the Salesforce source in SailPoint. To manage the account data, either create an identity profile based on the source or verify that the accounts you load are correlated to an existing identity. > [!NOTE] > > To view the latest features, enhancements, and fixes for all SaaS connectors, refer to the [SaaS Release Notes]() page. ## Supported Managed Systems The Salesforce connector supports: - Salesforce CRM (sales-cloud) - Salesforce API version 61 - Salesforce Hyperforce-enabled tenants For information on the permissions required to support Hyperforce tenants, refer to [Salesforce Hyperforce Tenant User Access](). - Salesforce API version 60 > **Note** > > The version in the URL is disregarded for existing Salesforce sources. Instead, the connector uses Salesforce API version 60.0 automatically. There is no change in the existing behavior. ## Prerequisites - Configure at least one virtual appliance cluster and successfully test the connection. For more information, refer to the [Virtual Appliance Reference Guide](). - Most of your users need a standard Salesforce user license. - For External Client Application (ECA) authentication, install External Client Application from Salesforce AppExchange. For information, refer to [Installing External Client Application](). For administrator rights and custom profile access on the Salesforce account, refer to [required permissions](). ## Supported Features The Salesforce connector supports the following features. > [!NOTE] > > Before you can use any item marked with an asterisk (\*), SailPoint must first activate the feature for you. ### Account Management - \*Load and provision accounts - \*Access certifications (Certification of entitlements connected to accounts) - Enable and disable accounts - Password Management - Add and remove associations of the following group objects with User objects: - `PermissionSet` - `PermissionSetGroup` - `CollaborationGroups` - `PublicGroups` - `Role` - `PermissionSetLicense` - `ManagedPackage` - `DelegateGroup` - Create new Portal Users and Partner Users, and assign licenses > **Note** > > Enabling and disabling portal and partner users is not supported. ### Account - Group Management - Aggregate collaboration groups as entitlements during account aggregation - Aggregate collaboration groups as group objects > **Note** > > If you enable or disable a user that has a collaboration group object assigned to it, Salesforce automatically removes it, but it won't update in the SailPoint user interface for that user. To correct this, run the **Iterate the User** process after the Enable/Disable operation is performed. - Add or remove collaboration groups as entitlements - Manages Salesforce profiles as account-groups - Group aggregation - Refresh groups - Aggregate the following objects as group objects: - `PermissionSet` - `PermissionSetGroup` - `PublicGroup` - `PermissionSetLicense` > **Note** > > Through certification, permission set licenses cannot be removed until associated permission sets are removed. - `ManagedPackage` - `Role` > **Note** > > Includes the role's hierarchy. - `DelegateGroup` > **Note** > > DelegateGroup objects can be assigned to active (enabled) users. > > If you disable a user that has a DelegateGroup object assigned to them, Salesforce automatically removes it from the user. However, it doesn't update in SailPoint for that user. To update SailPoint, run the **Iterate the User** process after performing the Enable/Disable operation. - Aggregate `QueueNames` as an entitlement ### Enhanced Domains The Salesforce connector supports use with the Enhanced Domains feature. ### Role Hierarchy Management The Salesforce connector can manage a Role hierarchy in addition to the Role itself. Within the Salesforce system, Role hierarchies are used to extend record access automatically. ### Pass-through Authentication Pass-through authentication enables you to sign in to SailPoint using your Salesforce username and password. To use Pass-through authentication, you must use your Salesforce password and the security token appended to it. ### Password Management 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](). # Machine Account Attributes Machine account attributes are used in provisioning configurations for machine accounts. After you have [created the required machine account subtypes](), you can use the machine account attributes to provision machine accounts in your SailPoint tenant. Refer to [Machine Identity Security Overview]() for more information. ## Machine Account Provisioning Attributes | Create Machine Account Attributes | Description | Required | Initial Value Type | Initial or Default Value | | --- | --- | --- | --- | --- | | Alias | Alias for the Salesforce user. Review not required. | Yes | `identityAttribute` | Identity attribute `firstname` | | IsActive | Flag that indicates whether the user is active in Salesforce. | No | `static` | `true` | | Username | Username for the Salesforce user. Review not required. | Yes | `identityAttribute` | Identity attribute `email` | | Email | Email address for the Salesforce user. Review not required. | Yes | `identityAttribute` | Identity attribute `email` | | FirstName | First name of the Salesforce user. Review not required. | Yes | `identityAttribute` | Identity attribute `firstname` | | LastName | Last name of the Salesforce user. Review not required. | Yes | `identityAttribute` | Identity attribute `lastname` | | CommunityNickname | Community nickname for the Salesforce user. Review not required. | Yes | `identityAttribute` | Identity attribute `displayName` | | TimeZoneSidKey | Time zone for the Salesforce user. Allowed values include America/Chicago, America/Bogota, America/Lima, America/Los\_Angeles, and Atlantic/Bermuda. | Yes | \- | `America/Los_Angeles` | | LocaleSidKey | Locale for the Salesforce user. | Yes | \- | `en_US` | | LanguageLocaleKey | Language locale for the Salesforce user. | Yes | \- | `en_US` | | EmailEncodingKey | Email encoding for the Salesforce user. | Yes | \- | `UTF-8` | | ProfileName | Salesforce profile name assigned to the user. Review not required. | Yes | `static` | `Standard User` | | UserType | Salesforce user type (for example, Standard). Review not required. | No | \- | `STANDARD` | Refer to [Machine Identity Security Overview]() for more information. # Provisioning The Salesforce connector supports provisioning, allowing you to create and manage accounts and entitlements in Salesforce 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. > [!NOTE] > > The Generator default is Disabled. ## Default Create Account Attributes | Attribute | Description | | --- | --- | | Alias | (Required) The eight-character alias. By default, it generates a value based on the `lastname` and `firstname` in the field's inline script. It takes the first seven characters from the last name and prefixes it with the first character of the first name. | | IsActive | Indicates the active status of the account. Defaults to `true`, meaning the account is active. | | Username | Defaults to the account's username. | | Email | Defaults to the account's email address. | | FirstName | Defaults to the account's first name. | | Lastname | Defaults to the account's last name. | | CommunityNickname | Nickname defaults to account's full name. | | TimeZoneSidKey | The user's timezone, it uses a display name defined by Salesforce. Only a few timezones are defined in the policy drop down and this will need to be customized for each deployment. Defaults to `America/Los_Angeles`. | | LocaleSidKey | The user's locale. Defaults to `UTF-8`. | | Email EncodingKey | The email encoding key. There are several selections to choose from in from the web interface. The encoding keys are customizable. Defaults to `UTF-8`. | | LanguageLocaleKey | The language locale key. There are several selections to choose from in from the web interface. The locale keys are customizable. Defaults to `en_US`. | | Federation Identifier | A Federation ID is an identifier that is unique within a Salesforce organization. | | UserType | Used for defining Portal or Partner Users. Portal and Partner Users must be assigned to a Salesforce account using the **Account Name** provisioning policy attribute. If not configured, then the default `STANDARD` user will be created. Example values: `PORTAL`, `PARTNER`. | | AccountName | A Salesforce account name to assign to a new portal or partner user. If left blank, the system creates a new Salesforce account and assigns it to the new portal or partner user. | | PermissionSetLicense | For the Salesforce source, the `PermissionSetLicense` is added as an entitlement while provisioning an account. For existing sources, you must add the `PermissionSetLicense` object (String type) to the account schema. The Attribute Request priority is: Add PermissionSetLicense Object, Add/Remove PermissionSet, Remove PermissionSetLicense. Through the certification process, the `PermissionSetLicense` object cannot be removed until the associated Permission sets are removed. | | ManagedPackage | The Salesforce source supports `ManagedPackage` entitlement. The source aggregates the `ManagedPackage` object (schema type: String; description: Managed Package assigned to a user). New Salesforce sources, by default, have `ManagedPackage` as an entitlement attribute while provisioning an account. For existing sources, you must manually add the `ManagedPackage` attribute to the schema. | ## Creating Portal and Partner Users Configure your provisioning policy to create a new portal or partner user then associate them with an existing or new Salesforce account. To create Portal Users and Partner Users: 1. Add the **UserType** attribute into your Create Profile provisioning policy. Supported values are `STANDARD`, `PARTNER` and `PORTAL`. The default value is `STANDARD`. 2. Add the **AccountName** attribute to the provisioning policy if you want to assign it to an existing Salesforce account. If the **AccountName** is not provided or not configured, a new account will be created and assigned to the new Portal or Partner User. > **Note** > > Enabling and disabling Portal and Partner users is not supported. # Salesforce Required Permissions The administrator must have the appropriate rights on the Salesforce account to support user provisioning. The System Administrator Profile can configure and customize the application. It contains the following permissions: - Has access to all functionality that does not require an additional license - Can create, edit, and delete custom profiles - Can reset the password of multiple user accounts - Can add multiple user accounts - Has access to all user accounts and profile permissions - Enable and disable user accounts ## Profile Access to User Accounts A user profile determines what a user can do in the system. By default, the System Administrator Profile can do the most; the Read Only Profile can do the least. For most users, the Standard User Profile is a good choice. It lets people create and edit most records, as well as access and run reports. System Administrators can configure Users, Roles, and Profiles from the **Setup** area. To access these settings when signed in to Salesforce, select your name, and then select **Setup** from the drop-down menu. The Users, Roles, and Profiles settings are all available under **Manage Users** in the **Administration Setup** menu. For more information on configuring a custom user profile to enable the connector to connect to the Salesforce managed system and manage the data within, refer to [Required Access for Custom User Profiles](<#required-access-for-custom-user-profiles>). ## User Licenses Create Access Most of your users will need a standard Salesforce user license. This license gives the user full access to Salesforce's CRM features and applications, including Chatter. Other user license options limit user access. ## Required Access for Custom User Profiles SailPoint recommends that you use a System Administrator user profile to grant the Salesforce connector the minimum necessary access within the Salesforce managed system. However, if your organizational policies prohibit the use of a System Administrator user profile in this way, you can create a custom user profile for the connector to use instead. For identity and access management operations, the custom user profile must have full access to the following Salesforce objects at a minimum: > [!NOTE] > > The list of objects which require full access can vary for custom attributes, depending on how the attribute is defined. You may need to grant full access to additional Salesforce objects for custom attributes. - Accounts - Contact - CollaborationGroup - Group - Profile - PackageLicense - PermissionSet - PermissionSetAssignments - PermissionSetGroup - PermissionSetLicense - PermissionSetLicenseAssign - PublicGroups - Queues - Roles - User - UserLicense - UserPackageLicense - UserRole ## Required Permissions for DelegateGroup Configure the following permissions before you begin configuring DelegateGroup: - To manage delegated administration - Customize Application - To be a delegated administrator - View Setup and Configuration > **Note** > > Delegated administrators can only manage user roles. Delegated administrators cannot create new user roles, copy existing roles, or delete existing roles. ## Salesforce Hyperforce Tenant User Access To support a Hyperforce tenant, the Salesforce connector requires a custom user profile with full access to the standard objects listed below. - Accounts - Contact - Collaboration Group - Group - Profile - Package License - Permission Set - Permission Set Assignments - Permission Set Group - Permission Set License - Permission Set License Assign - Public Groups - Queues - Roles - User - User License - User Package License - User Role # 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 Salesforce 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. ### Updating the Schema For pre-existing sources, perform the following steps to start using new attributes with your source. Refer to the appropriate attribute section for detailed information about updating the schema. 1. Use the [createSchema]() API to create a new group schema for your source. 2. Update the account schema with the following steps: 1. Get the account schema using the [getSchema]() API. 2. Copy the schema to a file and search for the attribute corresponding to the group schema you created earlier. 3. Add and update the properties for the attribute you found. 4. Add the modified schema to the payload to update the account schema in the source using the [replaceSchema]() API. ### 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 | | Name | PermissionSet | | Id | PermissionSetGroup | | Id | Role | | Id | PublicGroup | | Id | PermissionSetLicense | | Id | ManagedPackage | ### Default Account Attributes The Salesforce connector supports the following default account schema attributes and customer configurable attributes. The attributes must be defined as strings if not specified. > [!NOTE] > > Only account attributes in the source schema are processed by the connector. | Attribute Name | Description | | --- | --- | | UserName | The account user's display name, typically in an email type format. For example, [denise.hunt@demoexample.com]() | | Id | The internal Salesforce ID number for the account. The format is as follows: `005A00000014ySyIXX` | | Name | The user's full name | | FirstName | The user's first name | | LastName | The user's last name | | Alias | The user's assigned alias | | City | The user's city | | CommunityNickname | Display Names for the user's online communities | | CallCenterId | The user's call center | | CompanyName | The user's company name | | Country | The user's country | | Department | The user's department | | Email | The user's Email address | | Division | The user's division | | EmployeeNumber | The user's employee number | | Extension | The user's telephone extension | | Street | Name of the street | | Fax | The user's fax number | | IsActive | Indicates if the user account is active in Salesforce. When set to `false`, the user account is disabled | | EmailEncodingKey | Encoding that should be used during email communications | | ProfileId | ID of the profile assigned to a user. Profiles contain settings and permissions, which control what users can do. The available profiles depend on which user license is selected | | ProfileName | Name of the profile assigned to a user. Profiles contain settings and permissions, which control what users can do. The available profiles depend on which user license is selected | | Role | The role assigned to a user | | PublicGroups | Public groups are the entitlements for a user | | QueueNames | The queues assigned to the user | | UserPermissionsMarketingUser | Maps to the Marketing user flag | | UserPermissionsOfflineUser | Maps to the Offline user flag | | Phone | The user's phone number | | ReceivesAdminInfoEmails | Enable to receive the salesforce.com administrator newsletter | | UserType | Type of the user. This field is read-only. | | IsFrozen | The user's frozen status. | | UserPermissionsSFContentUser | Maps to Sales Anywhere User | | ReceivesInfoEmails | Enable to receive the salesforce.com newsletter | | State | The user's state | | Title | The user's title | | ManagerId | The user's manager' ID | | PermissionSet | The PermissionSet assigned to a user | | ManagedPackage | The managed package assigned to a user | | CollaborationGroup | The collaboration group ID assigned to a user | | PermissionSetGroup | The PermissionSetGroup assigned to a user | | PermissionSetLicense | The PermissionSetLicense assigned to a user | | FederationIdentifier | A Federation ID is an identifier that is unique within a Salesforce Organization | | UserPermissionsMobileUser | Maps to the Mobile user flag. This attribute isn't supported with Salesforce API version 59.0. | | IsPortalEnabled | Enabled if the user is a Portal User. This field is read-only. | | IsPartner | Enabled if the user is a Partner User. This field is read-only. | | UserLicense | The user's license | | TimeZoneSidKey | The user's timezone, it uses a display name defined by Salesforce. Only a few timezones are defined in the policy drop down and this will need to be customized for each deployment. Defaults to `America/Los_Angeles`. | | LocaleSidKey | The user's locale. Defaults to `UTF-8`. | | LanguageLocaleKey | The language locale key. There are several selections to choose from in from the web interface. The locale keys are customizable. Defaults to `en_US`. | > [!NOTE] > > The `ProfileId` and `UserRoleId` fields are required in the schema to aggregate the `ProfileName` and `userRoleName` respectively. If the `ProfileId` or `UserRoleId` is removed then profile name and user role name will not be fetched. #### Additional Account Attributes for the Salesforce Connector > [!NOTE] > > The Salesforce connector supports provisioning custom attributes present on the user object. - (For attributes present on user object only) The Salesforce connector enables you to aggregate and update custom attributes present on user objects. The custom attributes added in the Salesforce user schema must have `__c` appended to the attribute names created in Salesforce. For example, if you added `EMP_DEPARTMENT` in the user entity on the Salesforce system, you should also add `EMP_DEPARTMENT__c` in the Salesforce user schema. > **Note** > > Custom attributes can also be updated. - Support for custom attributes not present in Salesforce system but are required internally in SailPoint, such as for a configured correlation rule can be acknowledged if the attribute is prepended with `_#`. For example: `_#Emp_company_history` ## 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. ### User and Group Object Modification The Salesforce connector supports user object modification while enabling and disabling accounts. For enable or disable account operations, you can modify other attributes of the account that are part of the user object. The connector supports multiple group objects and entitlements by having the group object schemas defined and aggregated. The following are the group object schemas: - `PublicGroups` - `QueueNames` - `Role` (includes the role hierarchy) - `PermissionSet` - `PermissionSetGroup` - `PermissionSetLicense` - `ManagedPackage` - `DelegateGroup` User and group object modification is supported by default in new Salesforce sources. You must add the objects manually for pre-existing sources. > [!IMPORTANT] > > - You must manually add multi-group object schemas. > - You must remove the `UserRoleName` and `UserRoleId` attributes and add an attribute named `Role` into the account schema. > - Adding the `Role` entitlement attribute into the account schema adds duplicate Role entitlements. This can be helpful if you can't remove the `UserRoleName` attribute from the account schema. Note the following when adding or modifying a group object: - Use the API to create a new group schema. - Use the POST method. - Use the `beta/sources//schemas` URI. The following JSON payload example adds the schema for the PublicGroups group object: ```json { "name": "PublicGroups", "nativeObjectType": "PublicGroups", "identityAttribute": "Id", "displayAttribute": "Name", "hierarchyAttribute": null, "includePermissions": false, "features": [], "configuration": {}, "attributes": [ { "name": "Id", "type": "STRING", "schema": null, "description": "PublicGroups Id.", "isMulti": false, "isEntitlement": false, "isGroup": false }, { "name": "Name", "type": "STRING", "schema": null, "description": "PublicGroups name.", "isMulti": false, "isEntitlement": false, "isGroup": false } ] } ``` The example adds the following schema for the PublicGroups group object: ```xml PublicGroups Id. PublicGroups name. ``` ### Default Group Attributes The Salesforce connector also supports groups. The following attributes must be configured on the managed system and in the SailPoint source schema to manage groups. Profiles are aggregated during account-group aggregation. The following are the attributes returned by the group aggregation process. | Attribute Name | Description | | --- | --- | | Id | The internal Salesforce ID for the group. For example: `00eA0000000OoP6IAK` | | Name | The friendly name assigned to the profile. For example, Force.com - Free User | | UserType | This is the profile's type. | | Description | The description for the profile. | ### Default Role Attributes When aggregating group attributes as role objects, the following attributes are returned by the role aggregation process: | Attribute Name | Description | | --- | --- | | Id | The role's unique identifier. | | Name | The role name. | | CaseAccessForAccountOwner | The case access level for the account owner. | | ContactAccessForAccountOwner | The contact access level for the account owner. | | OpportunityAccessForAccountOwner | The opportunity access level for the account owner. | | ParentRoleId | Unique identifier for the role's parent role. | Aggregating group attributes as role objects enables the connector to delete a role associated with a user provisioning and assign a new role to a user during provisioning. New sources support the Role object with bidirectional role hierarchy at one level by default. For an existing source, update the Role schema with the `hierarchyAttribute` set to `ParentRoleId` and the attributes listed in the table above to get support for the role hierarchy: ```json { "hierarchyAttribute": "ParentRoleId", "attributes": [ { "name": "CaseAccessForAccountOwner", "type": "STRING", "schema": null, "description": "The case access level for the account owner", "isMulti": false, "isEntitlement": false, "isGroup": false }, { "name": "ContactAccessForAccountOwner", "type": "STRING", "schema": null, "description": "The contact access level for the account owner", "isMulti": false, "isEntitlement": false, "isGroup": false }, { "name": "OpportunityAccessForAccountOwner", "type": "STRING", "schema": null, "description": "The opportunity access level for the account owner", "isMulti": false, "isEntitlement": false, "isGroup": false }, { "name": "ParentRoleId", "type": "STRING", "schema": null, "description": "Unique identifier for role's parent role", "isMulti": true, "isEntitlement": false, "isGroup": false } ] } ``` Then use the [REST API for Entitlement Aggregation]() and add `disableOptimization=true` in the payload to trigger a full entitlement aggregation. For example: `https://{tenant}.api.identitynow.com/beta/entitlements/aggregate/sources/:id?disableOptimization=true` ### Default PublicGroup Attributes When aggregating PublicGroup attributes as group objects, the following attributes are returned by the group aggregation process: | Attribute Name | Description | | --- | --- | | Id | The Public Group's identifier. | | Name | The Public Group's name. | Aggregating PublicGroup as a group object enables the connector to verify aggregated Public Groups not currently associated with a user, and assign any new Public Group to users during provisioning. ### Default PermissionSet Attributes When aggregating PermissionSet attributes as group objects, the following attributes are returned by the group aggregation process: | Attribute Name | Description | | --- | --- | | Id | The permission set's ID. This is an Account ID which must not be changed. | | Name | The internal ID for this profile. | | Label | The friendly name assigned to the profile. | | Description | The description for the profiles. | Aggregating PermissionSet as a group object enables the connector to verify aggregated PermissionSets not currently associated with a user, and assign any new PermissionSet to users during provisioning. ### Default PermissionSetGroup Attributes When aggregating PermissionSetGroup attributes as group objects, the following attributes are returned by the group aggregation process: | Attribute Name | Description | | --- | --- | | Id | The permission set group's ID. This is an Account ID which must not be changed. | | MasterLabel | The permission set group's name. | | Description | A description of the permission set group. | Aggregating PermissionSetGroup as a group object enables the connector to verify aggregated PermissionSetGroups not currently associated with a user, and assign any new PermissionSetGroup to users during provisioning. ### Default PermissionSetLicense Attributes When aggregating PermissionSetLicense attributes as group objects, the following attributes are returned by the group aggregation process: | Attribute Name | Description | | --- | --- | | Id | The permission set license's ID. This is an Account ID which must not be changed. | | MasterLabel | The permission set license's master label. | Aggregating PermissionSetLicense as a group object enables the connector to verify aggregated PermissionSetLicenses not currently associated with a user, and assign any new PermissionSetLicense to users during provisioning. ### Default ManagedPackage Attributes While aggregating ManagedPackage attributes as group objects, the following attributes are returned by the group aggregation process: | Attribute Name | Description | | --- | --- | | Id | The managed package's ID. | | NamespacePrefix | The managed package's namespace prefix. | Aggregating ManagedPackage as a group object enables the connector to verify aggregated managed packages not currently associated with a user, and assign any new managed package to users during provisioning. ### Default CollaborationGroup Attributes While aggregating CollaborationGroup attributes as group objects, the following attributes are returned by the group aggregation process: | Attribute Name | Description | | --- | --- | | Id | Collaboration Group Id. | | Name | Collaboration Group name. | | CollaborationType | Collaboration Group Type. | Aggregating CollaborationGroup as a group object enables the connector to verify aggregated collaboration groups not currently associated with a user, and assign any new collaboration group to users during provisioning. For pre-existing sources, update the Account schema with a `CollaborationGroup` schema attribute to start managing Collaboration Groups in account aggregation, then add the schema above using the [Create a new Schema on the Specified Source]() process. Refer to [Updating the Schema](<#updating-the-schema>) for more information. Add the following schema attribute to the account schema: ```json { "name": "CollaborationGroup", "type": "STRING", "schema": { "type": "CONNECTOR_SCHEMA", "id": , "name": "CollaborationGroup" }, "description": null, "isMulti": true, "isEntitlement": true, "isGroup": true } ``` Add the following JSON to create the group schema: ```json { "name": "CollaborationGroup", "nativeObjectType": "CollaborationGroup", "identityAttribute": "Id", "displayAttribute": "Name", "hierarchyAttribute": null, "includePermissions": false, "features": [], "configuration": {}, "attributes": [ { "name": "Id", "type": "STRING", "schema": null, "description": "Collaboration Group Id.", "isMulti": false, "isEntitlement": false, "isGroup": false }, { "name": "Name", "type": "STRING", "schema": null, "description": "Collaboration Group name.", "isMulti": false, "isEntitlement": false, "isGroup": false }, { "name": "CollaborationType", "type": "STRING", "schema": null, "description": "Collaboration Group Type.", "isMulti": false, "isEntitlement": false, "isGroup": false } ] } ``` ### Default DelegateGroup Attributes The Salesforce connector supports the Salesforce DelegateGroup object. | Attribute Name | Description | | --- | --- | | Id | The Delegate Group's unique identifier. | | Name | The developer group's unique label. | | DeveloperName | The unique developer name for the delegate group. | | IsLoginAccessEnabled | Indicates if login access is enabled for the developer group. | Aggregating DelegateGroup as a group object enables the connector to verify aggregated Delegate Groups not currently associated with a user, and assign any new Delegate Group to users during provisioning. New sources have the `DelegateGroup` account schema attribute by default. For existing sources, add the following attribute to your account schema to manage DelegateGroup objects in account aggregation: ```json { "name": "DelegateGroup", "type": "STRING", "schema": { "type": "CONNECTOR_SCHEMA", "id": , "name": "DelegateGroup" }, "description": "The ID of the Delegate Group assigned to the user", "isMulti": true, "isEntitlement": true, "isGroup": true } ``` To aggregate DelegateGroup as a group object, add the following JSON to the group schema via the IDN REST API to add the new schema to an existing source: ```json { "name": "DelegateGroup", "nativeObjectType": "DelegateGroup", "identityAttribute": "Id", "displayAttribute": "Name", "hierarchyAttribute": null, "includePermissions": false, "features": [], "configuration": {}, "attributes": [ { "name": "Id", "type": "STRING", "schema": null, "description": "The Delegate Group's unique identifier", "isMulti": false, "isEntitlement": false, "isGroup": false }, { "name": "Name", "type": "STRING", "schema": null, "description": "The developer group's unique label", "isMulti": false, "isEntitlement": false, "isGroup": false }, { "name": "DeveloperName", "type": "STRING", "schema": null, "description": "The unique developer name for the delegate group", "isMulti": false, "isEntitlement": false, "isGroup": false }, { "name": "IsLoginAccessEnabled", "type": "BOOLEAN", "schema": null, "description": "Indicates if login access is enabled for the developer group", "isMulti": false, "isEntitlement": false, "isGroup": false } ] } ``` # 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]() > [!TIP] > > Community nickname must be unique. ## Issue While Running Salesforce Account Aggregation **Issue**: `javax.net.ssl.SSLHandshakeException: Remote host terminated the handshake` The test connection might be working, but when you run an aggregation or any other flow, you may still get the error. **Resolution**: Check the following: - The certificate may need to be communicated to the managed system. - Try running the Salesforce request and print in the logs via Postman. - If dynamic IP is configured in environment, try opening the firewall for `*.salesforce.com`. ## Duplicate User Error Is Displayed **Issue**: The email ID of that user may be utilized in the Salesforce system already. **Resolution**: Create a new account with a different email ID. The Email ID is the mandatory username for the user. ## Connector Fails to Create a New Account When the Total Active Account Limit in Salesforce Is Exceeded **Resolution**: Increase the account limit in Salesforce or disable existing active accounts in Salesforce before initiating a Create request. ## INVALID\_SESSION\_ID Session Error During Any Salesforce Connector Operation **Issue**: `INVALID_SESSION_ID` **Resolution**: 1. Remove the `serverUrl` and `sessionID` attributes from the application configuration using the source update API. 2. Perform a test connection. 3. If the test is successful retry the failed operation. ## Errors During JWT Authentication Configuration Before connecting to Salesforce using OAuth 2.0 JWT Flow, you need to create your own connected app required by JWT Flow on the Salesforce platform. 1. In Salesforce, go to **Security Controls \> Certificate and Key Management**. Select **Create Self-Signed Certificate** to create a self-signed certificate. Then download the certificate to your local machine. In this example, the certificate, `jwtapril.crt`, was created and downloaded to `C:\jwtapril.crt` for demonstration purposes. 2. Select **Export to Keystore** to export your certificate to a keystore file in JKS (Java Keystore) format. In this example, the certificate is exported to `D:\jwtapril.jks`. Use this same location to export the certificate in JKS format. 3. Go to **Create \> Apps**, and select **New** in the connected apps area. Create a connected app that enables OAuth settings and which uses the digital certificate `C:\jwtapril.crt` you downloaded earlier and save it. > **Screenshots** > > [![Create connected app]()]() [![Create connected app]()]() Now, go to **Create \> Apps** and open the newly created connected app. You can find the following attributes in the connect app view: - `subject` - The username with which certificate is registered - `audience` - The callback URL (provide: `https://login.salesforce.com`) - `issuer` - The connected app's consumer key 4. Execute a keytool command to extract the private key from the Certificate: A. List the contents of the keystore file from earlier. Check the certificate details with the alias name: Raw query: `keytool -list -v -keystore keystoreName.jks` Query for this case: `keytool -list -v -keystore .jks` > **Note** > > In this case, `` is the alias name of the certificate from earlier. B. Convert the .jks file to a .p12 file by providing the certificate alias name from the keystore. In this example, it's `jwtapril`. Raw query: `keytool -importkeystore -srckeystore .jks -srcstorepass -srckeypass -srcalias -destalias -destkeystore .p12 -deststoretype PKCS12 -deststorepass -destkeypass ` Query for this case: `keytool -importkeystore -srckeystore jwtapril.jks -srcstorepass jwtapril -srckeypass jwtapril -srcalias jwtapril -destalias jwtapril -destkeystore destination_keystore.p12 -deststoretype PKCS12 -deststorepass jwtapril -destkeypass jwtapril` `-srckeystore: location of source keystore file(.jks file)` `-srcstorepass: password of the keystore file` `-srckeypass : password of the keystore file` `-srcalias: alias of the keystore file` `-destalias: alias of the destination(.p12) file` `-destkeystore: location where you want to generate the .p12 file` `-deststorepass: password of the destination file` `destkeypass:password of the destination keypass` > **Tip** > > Be sure to keep track of the passwords used in this query. Incorrect passwords may cause errors during private key generation. Another example: `-> keytool -importkeystore -srckeystore C:\Certificates\Salesforce\00D3k000000usr9.jks -srcstorepass changeit -srckeypass changeit -srcalias jwt8mar -destalias jwt8mar -destkeystore C:\Certificates\Salesforce\pem8Mar.p12 -deststoretype PKCS12 -deststorepass changeit -destkeypass changeit` C. Change the .p12 file into .pem format: `openssl pkcs12 -in destination_keystore.p12 -nodes -nocerts -out examplePem.pem` > **Note** > > You may get an error message such as: > > `0C2F0000:error:0308010C:digital envelope routines:inner_evp_generic_fetch:unsupported:crypto\evp\evp_fetch.c:373:Global default library context, Algorithm (RC2-40-CBC : 0), Properties ()` > > To work around this, do one of the following: > > - Download the `openssl` version for your system from [https://indy.fulgan.com/SSL/]() > - Try to change the node version. D. Change the extension of the .pem file from ".pem" to ".key". `openssl rsa -in examplePem.key -outform PEM -out privatekey.key` For example: `openssl rsa -in C:\Certificates\Salesforce1\examplePem.key -outform PEM -out C:\Certificates\Salesforce1\privatekey.key` The generated private key (`privatekey.key` in the example) should be in **RSA** format. If the key is not in RSA format, run the following command to change it to RSA key format: `openssl rsa -in C:\Certificates\Salesforce1\examplePem.key -outform PEM -out C:\Certificates\Salesforce1\privatekey.key -traditional` E. Open to validate the privatekey: `https://8gwifi.org/certsverify.jsp` Input x509, CSR, or PrivateKey: `put jwtapril.crt content` Validate against x509, CSR, or PrivateKey: `put privatekey.key content` `privatekey.key` contains the privatekey. > **Note** > > `PrivateKeyPassword` can be empty as it is not mandatory. > [!NOTE] > > During the test connection, you may get the following error message: > > `Unable to Authorize User: user is not admin approved to access this app` > > To work around this error, do the following: > > 1. Go to **Create \> App** and open your newly created connected app. > 2. Select **Manage**. > 3. Select **Edit Policies**. > 4. In the OAuth Policies section: > > A. Select **Admin approved users are pre-authorized for Permitted Users**, and select **OK**. > > B. Select **Save**. > > C. Select **Manage Profiles** and then **Manage Permission Sets**. Do one of the following: > > - Select the profiles and permission sets that are pre-authorized to use this connected app. You can create permission sets if necessary. > > Now, the connected app provides access to users assigned with the selected profiles and permission sets. Assign the selected profiles or permission sets to the subject (username is used as the subject). > > OR > - Select **All users may self-authorize**. This authorizes all users. > [!NOTE] > > You may need to authorize a Salesforce user. Use the following Postman query to do so: > > 1. Import the following cURL request in Postman: > > ```text > curl --location --request POST 'https://login.salesforce.com/services/oauth2/authorize' \ > --header 'Content-Type: application/x-www-form-urlencoded' \ > --header 'Cookie: BrowserId=ytV1qb2fEe2h2SmHOqTcbQ; CookieConsentPolicy=0:0; LSKey-c$CookieConsentPolicy=0:0' \ > --data-urlencode 'client_id=3MVG9_XwsqeYoueJcfSbGhDFD45vg89rWLCiZ_yhv8WAQ3KFojhtBDz7qSDH37Kp7tbzEv8lRhg6LYk3ZtPu2b' \ > --data-urlencode 'client_secret=FF2148B26AC19A1EC8800AA9EC63C8100XDF74C75F86AACF4173D6C355EA2A3A' \ > --data-urlencode 'redirect_uri=https://login.salesforce.com/' \ > --data-urlencode 'response_type=code > ``` > 2. Save the response of this query with a ".html" extension. > 3. Open the file and select it in order to validate. The file asks for you to provide a username and password. Provide the same username and password you used to create the certificate. ## Aggregation Timeout Error The connector terminates an aggregation task with a timeout error. **Error message**: `QUERY_TIMEOUT: Your query request was running for too long` **Resolution**: Increase the **Connection Timeout** setting, then reattempt the aggregation task. For more information, refer to [Connection Settings](). ## OAuth Authentication Error Occurs While Connecting to Salesforce Test Environment **Resolution**: To use the Salesforce test environment, add the `OAuth2TokenURL` parameter in the Application Debug page with the following custom URL: `` ## Unable to Find Valid Certification Path to Requested Target **Error Message**: `PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target` **Resolution**: 1. Check if the Profile associated with the Service account User have the `SystemAdmin` permission. For more information, refer to Required Permissions. 2. Add the below entry key in the source xml file: `` # 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" } ] ```