Configure the Salesforce Synapse Using OAuth 2.0 Authentication

The Salesforce synapse leverages the Salesforce API to synchronize data between Salesforce objects—including custom objects— and Syncari entities. After activating the synapse, Syncari replicates the Salesforce schema and makes it available within the Syncari Unified Data Model. Use Sync Studio to map Salesforce objects to Syncari entities and Salesforce fields to Syncari fields. To accelerate the setup and configuration of these pipelines, Syncari provides a default mapping for the standard objects and fields in Salesforce.

The steps to authenticate the Salesforce synapse differ depending on your selected authentication method. This topic covers setup using OAuth 2.0 authentication. If you want to authenticate using user credentials, see Configure the Salesforce Synapse Using User Credentials.

Requirements & Reference

• Prior to configuring Syncari with production data, we recommend that you first connect a sandbox or test environment.
• If your Salesforce security requires you to allowlist an IP address, see Allowlist an IP Address.
• Your Salesforce edition must have API Access so that Syncari can communicate with it. Salesforce Enterprise and Unlimited include API Access, and you can purchase API access for the Professional edition. Check out this Salesforce help article to be sure you have a supported edition.
• OAuth authentication requires a connected app. To set up a connected app, you must have Administrator privileges. Contact your system administrator if you do not have those privileges.
• Salesforce API documentation
• Salesforce Help: Authorization Through Connected Apps and OAuth 2.0
• Salesforce Help: Connected Apps

Supported Synapse Capabilities

• Schema discovery of standard objects
• Schema discovery of custom objects
• Bidirectional sync of standard objects
• Bidirectional sync of custom objects
• Schema Sync
• If you audit fields in Salesforce updates made Syncari are logged to the user who created the connected app.

Salesforce Setup for OAuth 2.0 Authentication

To configure the Salesforce synapse using OAuth 2.0 authentication, you’ll need the following information about your Salesforce instance and the OAuth-configured connected app:

• Salesforce Endpoint URL
• Client ID
• Client Secret

Keep this information handy. You'll need it to Configure the Salesforce Synapse in Syncari.

Locate the Salesforce Endpoint URL

In Salesforce, select your profile, and then copy the URL under your name.

Note: Use only this URL; when you enter it in Syncari, you’ll need to prepend https://.

Create a Connected App in Salesforce

To create a connected app in Salesforce:

1. Log in to your Salesforce account. If not already on the Setup page, navigate to it. 
2. In the menu on the left, click Apps, and then click App Manager. Alternatively, you can also search for App Manager using Quick Find.
   
3. Click New Connected App.
   
4. Complete the required Basic Information section.
   
5. In the API (Enable OAuth Settings) section, select Enable OAuth Settings.
6. Complete the required information in the Enable OAuth Settings section:
   
   • Callback URL—enter a placeholder callback URL, like https://temp.com.
     You will return to this later with a value from Syncari.
   • Selected OAuth Scopes—move the minimum required scopes from Available OAuth Scopes to Selected OAuth Scopes
     • Manage user data via APIs (api)
     • Manage user data via Web browsers (web)
     • Perform requests at any time (refresh_token, offline_access)
   • Disable the Require Proof Key for Code Exchange (PKCE) Extension for Supported Authorization Flows option
   • Keep these checkboxes enabled:
     • Enable Oauth Settings
     • Require Secret for Web Server Flow
     • Require Secret for Refresh Token Flow
7. Scroll to the bottom of the window, and then click Save.
8. Click Continue, and then click Manage Consumer Details.
   Note: You’ll likely need to verify your identity with a verification code to continue.
   
9. Copy your Consumer Key and Consumer Secret to use when authenticating the Salesforce synapse. Store these securely.
   
10. Click Cancel and keep the connected app’s window open so you can return to it later and edit the Callback URL.

Configure the Salesforce Synapse in Syncari

In the previous section, you:

• Created a connected app.
• Identified and safely stored your Consumer Key and Consumer Secret
• Located your Salesforce Endpoint URL

Now, you can configure the Salesforce synapse in Syncari:

1. In Syncari, open Synapse Studio.
2. Find Salesforce in the Synapse Library, and drag it to the canvas.
   
3. Complete the information in the Configure step:
   
   • Synapse Name—Enter your own custom name for the synapse.
     Note: Stick to letters and numbers. The name must begin with a letter. The only special characters we allow are spaces, hyphens (-), and underscores (_).
   • Endpoint URL—Enter https:// followed by the Salesforce Endpoint URL you identified in Locate the Salesforce Endpoint URL.
     Note: The URL must be a fully formed URL, so make sure to include https://.
     Example: https://d4600000019hkeai-dev-ed.my.salesforce.com.
   • Authentication Method—Select Oauth.
   • Optional: The Sync Rate Limit affects downstream syncs with the synapse. Turn on the Sync Rate Limit if needed to limit the sync rate for updates. You can edit this configuration later if you find you need to manage your downstream syncs.
     
4. Click Next.
5. Complete the Authenticate step using the information from Salesforce Setup for OAuth 2.0 Authentication.
   • Client ID—Enter the Consumer Key for your connected app.
   • Client Secret—Enter the Consumer Secret for your connected app.
   • Generate and register the below OAuth redirect URL—Click Generate to create the Callback URL you need to add to your connected app.
     
6. Click Copy, and then navigate to your connected app in Salesforce.
   Hopefully, you kept the Salesforce window open from the Salesforce Setup for OAuth 2.0 Authentication steps. If you need help getting back to the connected app, see this help page in Salesforce.

7. Click Edit in Salesforce.

   

8. Paste the Callback URL that you copied from Syncari in the Callback URL box in Salesforce, and then click Save.
   
9. Return to Syncari, and then click Authenticate.
10. When prompted, log in with your Salesforce credentials. 
11. Click Next.
    Note: If you receive any error messages after authenticating, click Previous and confirm each of the parameters is configured properly. If the error persists, contact one of our Onboarding and Support team members.
12. Select Make Synapse Active.
    Other options include:  
    • Map Entities in Sync Studio—Syncari takes you to Sync Studio to map the entities before activating the Synapse. You will have to go back to the Synapse configuration to Activate it when ready. 
    • Activate and Create Pipelines—We don't recommend using this option except in specific use cases (e.g., this is your first synapse, and you want your schema to match that of the synapse). For synapses with default mappings, Syncari updates the Sync Studio canvas and creates draft pipelines for the Syncari Unified Data Model. Contact one of our Onboarding and Support team members before using this option. 
      
13. Click Close.

Error Troubleshooting

If your Synapse is in "error" state, it's likely there is an authentication error. Please check a few things in your Salesforce settings.

Go to Apps → Connected Apps → Manage Connected Apps → {{YOUR APP}} → Edit Policies.

1. "Immediately expire refresh token" should NOT be selected
2. “Refresh token is valid until revoked” should be selected
3. Under Permitted Users, is it set to “All users may self-authorize”? (we recommend setting it this way)
4. “Require Proof Key for Code Exchange (PKCE) Extension for Supported Authorization Flows” should be UN-checked.
5. If you encounter an 'expired access/refresh token' error, this may be due to having more than five tokens issued for the connected app, as the default limit for each application is five access tokens. Consider creating another connected app to resolve this issue.