Action Required: IIQ Salesforce Connector Migration to External Client App

Overview

To ensure continued seamless integration and prevent future service disruptions, SailPoint is updating the Salesforce connector for IdentityIQ (IIQ).

The connector will now support authentication through Salesforce External Client Apps (ECA) using OAuth 2.0 flows. Customers currently using basic authentication will need to migrate to OAuth 2.0. To avoid any potential interruptions, we strongly recommend completing this transition at your earliest convenience.

As an IIQ customer, you manage your Salesforce environment directly. You will need to create and deploy your own local ECA in Salesforce and then configure the OAuth flow within IIQ. This approach gives you full control over security policies, scoping, and token management.

For questions or assistance with migration planning, please contact your SailPoint Product Manager or Customer Success representative.

What Is Changing?

The External Client App is Salesforce’s next-generation framework for managing API access. It provides granular OAuth policy controls and represents Salesforce's strategic direction for external integrations.

Who Is Impacted?

IIQ Customers Using Basic Authentication — Action Required

Customers currently authenticating the Salesforce connector with username and password must migrate to one of the supported OAuth 2.0 flows via an External Client App

IIQ Customers Already Using OAuth 2.0 (JWT, Client Credentials, or Refresh Token)

You will need to transition your existing Connected App configuration to an External Client App. The OAuth flow configuration in IIQ remains similar, but the Salesforce-side app must be recreated as an ECA.

Why Is This Change Being Made?

• Salesforce is evolving its integration platform, and ECA is the modern successor to Connected Apps for external integrations.
• The OAuth 2.0 Authorization Code Grant flow provides a more secure, standards-based mechanism for user-consented API access.
• This ensures the SailPoint Salesforce connector aligns with Salesforce’s present and future platform direction.

What Should I Do Now?

1. Identify your current authentication method. Check your IIQ Salesforce application configuration — if you are using Basic (username + password), you must migrate.
2. Choose your target OAuth 2.0 flow. Review the three supported flows above and select the one that best fits your operational requirements:
   • JWT
   • Client Credentials
   • Refresh Token
3. Deploy a local ECA in your Salesforce org. Work with your Salesforce admin to create an External Client App with the appropriate OAuth settings, scopes, and policies. Refer to the detailed setup guides below.
4. Reconfigure your IIQ Salesforce application. Update the authentication settings to use the new ECA credentials and chosen OAuth flow.
5. Test connectivity. Run a test connection and account aggregation to verify everything works before your production cutover.
6. Contact your SailPoint PM or Customer Success Manager for migration support.

Salesforce Local ECA — deployment & authentication

Three procedures: JWT, Client Credentials, and Refresh Token flows. Expand a section below.

1. Deploy Local ECA on Salesforce and validate JWT authentication

The following steps describe the process for supporting the JWT-based authentication flow for Local ECA.

Step 1: Create a private key and self-signed digital certificate

This process produces two files:

• server.key — the private key.
• server.crt — the digital certificate. You upload this when you create the external client app (connected app).

Create a directory for the generated files and change to it:

mkdir ~/JWT
cd ~/JWT

Generate a private key and store it in server.pass.key (PKCS#1 traditional RSA is supported in IIQ):

openssl genpkey -aes-256-cbc -algorithm RSA -pass pass:SomePassword -out server.pass.key -pkeyopt rsa_keygen_bits:2048
openssl rsa -in server.pass.key -passin pass:SomePassword -traditional -out server.key

Generate a certificate signing request; store it in server.csr. Enter your company details when prompted:

openssl req -new -key server.key -out server.csr

Generate a self-signed certificate from server.key and server.csr; store it in server.crt:

openssl x509 -req -sha256 -days 365 -in server.csr -signkey server.key -out server.crt

Replace SomePassword with a strong password you will keep.

Step 2: Create an external client app and upload the digital certificate

1. Create a New External Client App.
2. Update name, contact email, and other fields as needed.
3. Under API (Enable OAuth Settings), enable OAuth.
4. Under App Settings, set Callback URL — e.g. https://test.salesforce.com/services/oauth2/success.
5. In OAuth Scopes, select:
   • Manage user data via APIs (api)
   • Manage user data via Web browsers (web)
   • Perform requests at any time (refresh_token, offline_access)

• (Required for JWT) Under Flow Enablement, select Enable JWT Bearer Flow.
• (Required for JWT) Upload your certificate file (e.g. server.crt).

Click Edit (JWT sub-steps): open the Policies tab → OAuth Policies.

• Under Plugin Policies, set Permitted Users to Admin approved users are pre-authorized.
• Under App Policies, select profiles and permission sets that are pre-authorized. Create them if needed.

If needed, open the Policies tab → App Authorization → OAuth Policies: set refresh token policy (e.g. Refresh token is valid until revoked) per your requirement.

From OAuth settings, collect the Consumer Key and Consumer Secret for later use.

Step 3: Create an application in SailPoint

1. Create a new application in IIQ.
2. Authentication Type: OAuth2. Grant Type: JWT.
3. Subject — Salesforce username of the service account used by the connector.
4. Issuer — Consumer Key of the Salesforce connected / external client app.
5. Audience — Salesforce login URL for token requests:
   Production: https://login.salesforce.com
   Sandbox: https://test.salesforce.com
6. Private Key — full contents of server.key from Step 1.
7. Private Key Password — password used when generating the key.

2. Deploy Local ECA on Salesforce and validate client credentials authentication

Steps for the Client Credentials flow for Local ECA.

1. Create the external client app

1. Create an External Client App.
2. Under API (Enable OAuth Settings), enable OAuth.
3. Enter a Callback URL (e.g. https://test.salesforce.com/services/oauth2/success or your app URL).
4. Select required OAuth scopes (e.g. Manage user data via APIs — api).

Under Flow Enablement, enable Client Credentials Flow.

Click Save.

2. Configure the execution policy

Client Credentials requires a run-as (Integration User) because there is no interactive login.

1. In External Client App Manager, open your app → Policies (or Manage Policies from the dropdown).
2. Click Edit.
3. Under OAuth Flows, ensure Client Credentials Flow is enabled.
4. In Integration User, select the user whose permissions the integration runs under.

That user needs a profile or permission set granting the APIs and data access the app requires.

Configure refresh token expiration as required.

3. Retrieve credentials

1. Open the app Settings tab.
2. Under Consumer Details, use Manage Consumer Details to view Consumer Key (Client ID) and Consumer Secret. Store them securely.

4. Create an application in SailPoint

• Grant type: Client Credentials.
• Enter Client Id and Client Secret.
• Token URL: https://{your-domain}.my.salesforce.com/services/oauth2/token

3. Deploy Local ECA on Salesforce and validate refresh token authentication

Objective

To configure a Salesforce External Client Application generate a Refresh Token using OAuth 2.0 Authorization Code Flow, and validate authentication by creating and testing a Salesforce SaaS source in SailPoint.

Salesforce Configuration

Step 1: Create an External Client App

• Log in to Salesforce.
• Navigate to:
  • Setup → App Manager
• Click External Client App
• Enter the Required Fields Mentioned

Step 2: Enable OAuth Settings

Under API (Enable OAuth Settings):

• Check Enable OAuth Settings.
• Enter the Callback URL (as required by your environment).
  • Example: https://test.salesforce.com/services/oauth/success
• Select Distribution State as Local 
• Add the required OAuth Scopes.

Minimum Required OAuth Scopes for Refresh Token Generation

Select the following scopes:

• Manage user data via APIs (api)
• Perform requests at any time (refresh_token, offline_access) 

These scopes are required to ensure refresh token generation and API access.

Reference Salesforce OAuth documentation: Salesforce Help

Step 3: Security Settings

Under Security Settings of the Connected App:

• Uncheck Require Proof Key for Code Exchange (PKCE) (if not required for your flow).

• You can manage Refresh Token settings under the OAuth policies section of your Connected App:
  • Go to the Policies tab → OAuth Policies.
  • Locate the Refresh Token Policy.
  • Configure the policy according to your requirements:
  • recommended to keep it -Refresh token is valid until revoked
  • You can change it to a shorter or longer validity depending on your needs.
• Save the settings.

Step 4: Retrieve Client Credentials

Once the app is created:

1. Go to App Manager
2. Locate your External Client App
3. Click View
4. Navigate to Consumer Details
5. Copy:
   • Consumer Key (Client ID)
   • Consumer Secret (Client Secret)

Store these securely for later use in SailPoint.

Step 5: Create a User and Assign the Required Permissions

For Example :

How Refresh token is specific to User
To allow a user to perform specific actions, you need to create a new user and assign the appropriate permissions via permission set or profile.

Create a new user with a minimum access profile to ensure they only have basic permissions by default. This helps maintain security and follows the principle of least privilege.
It can be configured according to the Requirement.

Navigation Path:
Salesforce → Setup → Permission Sets → Select Permission Set → System Permissions → Users

Assign those Permission Sets to User

Ensure the user:

• Has API Enabled permission
• Has required Permission Sets assigned
• Has access to objects required by SailPoint

Recommended: Assign necessary permission sets to allow required object access and API operations.

3. Generate Authorization Code & Refresh Token

Step 1: Generate Authorization Code

This are the two manual steps which customer has to perform to get the token

Open the following URL in a browser:

https://{MyDomainName}.my.salesforce.com/services/oauth2/authorize?
client_id=<consumer_secret_eca>& redirect_uri=https://test.salesforce.com/services/oauth2/success& response_type=code

User Authenticates and Authorizes Access

Before Salesforce issues an authorization code to an external client application, the user must first log in to Salesforce. Make sure to log in with the specific user whose permissions you want to be applied, as the authorization and resulting access will reflect that user’s assigned permissions.

After a successful login, Salesforce redirects users to the approval page to grant access to the app.

If users previously approved access, it isn’t necessary to approve access again.

Salesforce Grants Authorization Code

After users approve access to an external client app, Salesforce redirects users to the callback URL, where they can view the callback with an authorization code.

https://test.salesforce.com/services/oauth2/success? code=<authorization_code>

• The first part of the callback is the external client app’s callback URL: https://test.salesforce.com/services/oauth2/success.
• The second part is the authorization code that the external client app uses to get an token:
  code=<authorization_code>
  The authorization code expires after 15 minutes.

Step 2: Exchange Authorization Code for Refresh Token

Use the following cURL command:

Request an Access Token

To request an refresh token, the external client app passes the authorization code to the Salesforce token endpoint as an HTTP POST.

POST /services/oauth2/token HTTP/1.1 Host: mycompany.my.salesforce.com Content-length: 307 Content-type: application/x-www-form-urlencoded grant_type=authorization_code& code=<authorization_code>& client_id=<consumer_key>& client_secret=<consumer_secret>& redirect_uri=https://test.salesforce.com/services/oauth2/success

Response will include:

{ "access_token": <access_token>,
"refresh_token" :<refresh_token> "signature": "d/SxeYBxH0GSVko0HMgcUxuZy0PA2cDDz1u7g7JtDHw=",
"scope": "web openid",
"id_token": "eyJraWQiOiIyMjAiLCJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdF9oYXNoIjoiSVBRNkJOTjlvUnUyazdaYnYwbkZrUSIsInN1YiI6Imh0dHBzOi8vbG9...",
"instance_url": "https://mycompany.my.salesforce.com",
"id": "https://login.salesforce.com/id/00DB0000000TfcRMAS/005B0000005Bk90IAC", "token_type": "Bearer",
"issued_at": "1558553873237" }

This refresh token will be used in SailPoint source configuration.

Reference: Salesforce Help

4. SailPoint Configuration

Step 1: Create Salesforce SaaS Source

• Navigate to Sources in SailPoint.
• Create a new Salesforce SaaS Source.
• Enter the following:
  • Client ID (Consumer Key)
  • Client Secret (Consumer Secret)
  • Refresh Token
• Test Connection.

If successful, authentication via Refresh Token is validated.

Step 2: Perform Aggregation

• Run Account Aggregation.
• Verify:
  • Accounts are fetched successfully
  • No authentication errors
  • API connectivity is stable