How to Connect to Salesforce Using an External Client App

Summary

This guide provides a comprehensive overview of how to securely connect your workspace to your Salesforce instance by creating and configuring an External Client App. This is the first major step in setting up a secure integration. Following these steps will allow for a secure OAuth handshake, enabling your application to access necessary Salesforce data. These settings are critical for enabling API access and ensuring the connection is secure.

When to Use This

Use this process when you need to integrate an external application with your Salesforce environment. This is necessary for applications that need to perform actions or access data within Salesforce on behalf of your users, ensuring a secure and authenticated connection. You must have administrative privileges in your Salesforce environment to perform these actions.

How to Connect to Salesforce Using an External Client App 3024x1964

Step-by-Step Instructions

Step 1: Create an External Client App in Salesforce

• Log in to Salesforce with your administrator credentials.
• Navigate to 'Setup' by clicking the gear icon in the top-right corner.
• In the 'Quick Find' search box on the left, type "External" and click on 'External Client App Manager' under the 'Apps' section.
• Click the “New External Client App” button.
• Fill in the following fields in the Basic Information section:
  • External Client App Name / Name: Give your app a recognizable name (e.g., “Brainfish Integration”).
  • API Name: This is auto-filled; leave the default.
  • Contact Email: Enter a valid administrative email address.
  • Distribution State: Leave set to “Local”.
  • (Optional) Logo/Image URL: Add a representative logo if desired.
  • Description: Provide an optional description, for example, “OAuth integration for Brainfish”.
• Salesforce Create External Client app guide

Step 2: Configure OAuth Settings

• In the 'API (Enable OAuth Settings)' section, check the “Enable OAuth” box.
• Enter the following callback URL: https://app.brainfi.sh/auth/salesforce.callback
• You can enter additional callback URLs if integrating with multiple environments. Each must be on a separate line. Callback URL limits apply (2,000 characters total).
• Select these OAuth Scopes (permissions) and add them to the 'Selected OAuth Scopes' box:
  • Access the identity URL service (id, profile, email, address, phone)
  • Manage user data via APIs (api)
  • Perform requests at any time (refresh_token, offline_access)

Step 3: Generate and Note Your Credentials

• After saving, Salesforce will display a Client ID (also known as Consumer Key) and give you an option to reveal a Client Secret (also known as Consumer Secret).
• Copy both the Client ID and Client Secret—these will be entered in the Brainfish integration panel.

Step 4: Security Settings

• Navigate to the security section and ensure the following settings are enabled for maximum security:
  • Require secret for Web Server Flow
  • Require secret for Refresh Token Flow
  • Require Proof Key for Code Exchange (PKCE) extension for Supported Authorization Flows.

Step 5: Enable the Correct OAuth Flow

• Confirm that “Web Server Flow” (Authorization Code Flow) is enabled—this is required for most secure OAuth integrations and aligns with PKCE support.
• Save your changes.

Step 6: Connect Your Application

• Use the generated Client ID and Client Secret to configure the integration from your application's settings page, completing the connection to Salesforce.

Common Questions (FAQs)

What is an External Client App? An External Client App in Salesforce is a configuration that allows external applications to securely connect to your Salesforce data and services using protocols like OAuth.

What is a Callback URL? The Callback URL is the endpoint in your application where Salesforce will redirect the user after they have successfully authenticated and authorized the app. It's a crucial part of the OAuth flow. An incorrect Callback URL will cause the authentication process to fail, as Salesforce will not be able to redirect the user back to your application correctly.

Why is PKCE important? Proof Key for Code Exchange (PKCE) is a security extension that prevents authorization code interception attacks. It adds an extra layer of security to ensure the client exchanging the code is the same one that requested it.

Do I need to be a Salesforce admin to create an app? Yes, creating and managing External Client Apps requires administrator permissions in Salesforce.

What should I put for the app name? Use a clear and descriptive name that will help you and other admins easily identify the purpose of the integration.

Can I edit these details after the app is created? Yes, you can always navigate back to the 'External Client App Manager', select your app, and click 'Edit' to modify its information and settings.

Where do I find my Consumer Key and Secret? After you enable OAuth and save your app, the 'Consumer Key' (Client ID) and 'Consumer Secret' (Client Secret) will be displayed. Click to reveal the secret and copy both credentials.

What are OAuth Scopes? OAuth scopes are permissions that define what actions your app can perform and what data it can access in Salesforce. It's important to only grant the scopes that are necessary for the integration to function.

Troubleshooting Tips

• Authentication Errors: If you encounter authentication failures, double-check that the Client ID and Client Secret are copied correctly.
• Invalid Callback URL: Ensure the Callback URL entered in the Salesforce app settings exactly matches the URL expected by your application. Any mismatch will result in an error.
• Permission Issues / 'Forbidden' Error: If the app cannot access certain data or you receive a 'Forbidden' error, review the selected 'OAuth Scopes' in the External Client App settings to ensure the necessary permissions have been granted.
• Cannot Find 'External Client App Manager': If you cannot find this option, verify that you are logged in with a user profile that has the necessary administrative permissions.
• Error When Saving: If you receive an error upon clicking 'Create', ensure all mandatory fields (marked with a red asterisk) have been filled out correctly.
• PKCE Errors: If you encounter errors related to PKCE, confirm that both your external application and your Salesforce app settings have PKCE enabled. Mismatched configurations can cause the flow to fail.

Additional Tips

• Only share the client secret securely, and rotate it if it may have been exposed.
• Use HTTPS callback URLs in production for security.

This process creates an External Client App in Salesforce and provides the credentials and settings you need for a secure OAuth integration with Brainfish.