Configure ACC for an External React Application

Learning Objectives

After completing this unit, you’ll be able to:

• Configure the External Client App, trusted domain, and Salesforce cookie policy for an external React application.
  
• Generate the authentication values and retrieve the Employee Agent ID required for ACC initialization.
  

The External-Application Security Boundary

A React application hosted outside Salesforce operates outside the Salesforce trust boundary. ACC uses Lightning Out 2.0 to render Salesforce-managed UI in that application, so Salesforce must authenticate the user, trust the application’s origin, and allow the embedded session to persist.

An External Client App (ECA) enables the embedded ACC to securely access Salesforce APIs and user context from outside Salesforce. ECAs are next-generation connected apps that provide SSO and OAuth-based authorization. The ACC Web SDK requires an authenticated session negotiated through an ECA before the ACC UI is rendered outside Salesforce.

Each part of the configuration answers a different security or runtime question.

An External Client App is the OAuth authorization boundary for the external React application. It supplies the client identifier, callback URL, scopes, and permitted OAuth flows used to obtain the user-context access token.

Configure External Client Apps

An External Client App (ECA) authorizes the external React application to access Salesforce. ACC uses the resulting authenticated user session when it renders through Lightning Out 2.0.

1. From Salesforce Setup, in the Quick Find box, search for and select External Client App Manager.
   
2. Select New External Client App.
   
3. Enter the app name, API name, contact email, and distribution state. Select Local for an application developed for the current org.
   
4. Enable OAuth.
   
5. Enter the callback URL for the external application.
   
6. Select these OAuth scopes.
   
   • Manage user data via APIs
     
   • Manage user data via Web browsers
     
   • Access Lightning applications
     
7. Enable Authorization Code and Credentials Flow.
   
8. Configure the remaining OAuth and security settings for the application.
   
9. Select Create.
   

After Salesforce creates the ECA, open it from the External Client App Manager if its detail page isn’t already displayed. You use its Settings tab in the next section. Salesforce ECA guidance confirms the required scopes and the location of the consumer key and secret.

Retrieve Client Credentials

The backend uses the ECA consumer key and consumer secret to identify the application during the Authorization Code token exchange.

1. Open the ECA Settings tab.
   
2. Select Consumer Key and Secret.
   

3. Copy the consumer key value, and save it securely on the backend as client_id.
   
4. Copy the consumer secret value, and save it securely on the backend as client_secret.
   

Complete OAuth requests from a backend server. Don't hardcode OAuth tokens or frontdoor URLs in client-side code, and pass credentials to the browser only when strictly necessary.

Configure Trusted Domains

ACC renders Salesforce UI in a cross-domain iframe. Add the external application’s domain to the trusted-domain list so Salesforce can render the ACC interface for that origin.

1. From Salesforce Setup, in the Quick Find box, search for and select Session Settings.
   
2. Under Trusted Domains for Inline Frames, select Add Domain.
   
3. Enter the domain that hosts the external application. Accepted formats include:
   
   • example.com
     
   • https://example.com
     
   • *.example.com
     
4. Select Lightning Out as the iframe type.
   
5. Select Save.
   

Configure the Salesforce Cookie Policy

ACC requires the Salesforce session to persist when its interface is embedded in the external application. Because the interface runs in a cross-domain context rather than on a first-party Salesforce page, you need to remove the requirement to use first-party Salesforce cookies. This setting allows the browser to maintain the Salesforce session required by the embedded Lightning Out 2.0 experience.

1. From Salesforce Setup, in the Quick Find box, search for and select My Domain.
   
2. In the Routing and Policies section, locate Require first-party use of Salesforce cookies.
   
3. If the setting is enabled, select Edit.
   
4. Deselect Require first-party use of Salesforce cookies.
   
5. Select Save.
   

Generate Access Tokens with the OAuth 2.0 Web Server Flow

Use the OAuth 2.0 web server flow to generate an access token with user context. Your access token must include the web or full scope required to establish the Lightning Out 2.0 session.

Request Authorization Codes

Direct the user to your Salesforce org’s authorization endpoint. Replace the placeholders with your Salesforce domain, the client ID from your External Client App, and its registered callback URL.

https://<your-salesforce-domain>/services/oauth2/authorize?response_type=code&client_id=<client-id>&redirect_uri=<url-encoded-callback-url>

The callback URL must match a callback URL configured in the External Client App. URL-encode the callback URL when you include it in the authorization request.

After you sign in and authorize access, Salesforce redirects you to the callback URL. The redirected URL includes an authorization code in the code query parameter.

Exchange the Authorization Code for an Access Token

From your backend or another secure server-side environment, exchange the authorization code for an access token. Use the same callback URL that you included in the authorization request.

curl --request POST \
  'https://<your-salesforce-domain>/services/oauth2/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=authorization_code' \
  --data-urlencode 'code=<authorization-code>' \
  --data-urlencode 'client_id=<client-id>' \
  --data-urlencode 'client_secret=<client-secret>' \
  --data-urlencode 'redirect_uri=<callback-url>'

Replace these placeholders.

• <your-salesforce-domain>: Your Salesforce My Domain, without a trailing slash
  
• <authorization-code>: The code returned to your callback URL
  
• <client-id>: The consumer key from your External Client App
  
• <client-secret>: The consumer secret from your External Client App
  
• <callback-url>: The callback URL registered in your External Client App
  

The response includes an access_token. The backend exchanges this token for a frontdoor URL, which establishes the authenticated Salesforce UI session that Lightning Out 2.0 needs to render ACC in the external React application.

Keep the consumer secret and store the access token on the backend. Don’t hardcode OAuth credentials or tokens in the React application.

Generate a Frontdoor URL

Call the UI Bridge endpoint from the backend to exchange the access token for the frontdoor URL required by the embedded ACC interface.

Call the endpoint from the backend so that the access token remains protected.

export async function generateFrontdoorUrl({
  orgUrl,
  accessToken,
}) {
  const response = await fetch(
    `${orgUrl.replace(/\/$/, '')}/services/oauth2/singleaccess`,
    {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${accessToken}`,
        Accept: 'application/json',
      },
    }
  );
  if (!response.ok) {
    const responseBody = await response.text();
    throw new Error(
      `Frontdoor URL request failed: ${response.status} ${responseBody}`
    );
  }
  const { frontdoor_uri: frontdoorUrl } = await response.json();
  if (!frontdoorUrl) {
    throw new Error(
      'The frontdoor URL response doesn’t include frontdoor_uri.'
    );
  }
  return frontdoorUrl;
}

The response’s frontdoor_uri value is the frontdoorUrl that gets passed to the ACC Web SDK in Unit 3.

Get the Employee Agent ID

The Employee Agent ID identifies the specific Employee Agent that ACC loads when the external application initializes the Web SDK.

Before following the instructions, determine which method applies.

• The new Agentforce Builder provides the Agent ID in the Builder interface.
  
• The legacy Agentforce Builder provides the record ID through the agent record URL.
  
• Developers can also retrieve an agent ID programmatically with SOQL. This method is separate from the new Agentforce Builder interface.
  

Configure the integration user with the permissions required to access and use the selected Employee Agent.

New Agentforce Builder

Use these steps to find the Agent ID in the new Agentforce builder.

1. Open the Employee Agent in the new Agentforce Builder.
   
2. Expand Settings.
   
3. Select Agent Details.
   
4. Under Basic Information, locate Agent ID.
   
5. Copy the displayed value and store it as agentId.
   

Legacy Agentforce Builder

Use these steps to find the Agent ID in the legacy Agentforce builder.

1. From Salesforce Setup, in the Quick Find box, search for and select Agentforce Employee Agent.
   
2. Locate the Employee Agent that you want to embed in the external application.
   
3. Open the Agent record and copy the 18-character Salesforce record ID from the URL.
   
4. Use the value as agentId during ACC Web SDK initialization.
   

Programmatic Alternative

The SOQL query is a developer-oriented, programmatic method for retrieving the agent ID. It’s not included in the new Agentforce Builder interface.

SELECT Id, DeveloperName
FROM BotDefinition
WHERE DeveloperName = 'DEVELOPER_NAME'

Replace DEVELOPER_NAME with the agent’s developer name. Use the returned Id value as agentId during ACC Web SDK initialization.

You now have the runtime values required by the React integration.

• frontdoorUrl: Establishes the authenticated Salesforce UI session
  
• agentId: Identifies the Employee Agent that ACC loads
  

Now that you’ve configured the external-application security requirements and obtained the initialization values, move on to installing the ACC package and rendering the Employee Agent conversation in React.

Summary

You reviewed how to configure the ECA and trusted domain, generate an access token and frontdoor URL, and retrieve the Employee Agent ID required by the external integration. In the next unit, the React application passes frontdoorUrl as a top-level embedAgentforceClient() option and passes agentId inside agentforceClientConfig.

Resources

• Salesforce Developers: Set Up External Client Apps
• Salesforce Developers: Set Up Trusted Domains
• Salesforce Developers: Generate the Access Token for Agentforce Conversation Client Web SDK
• Salesforce Developers: Get Your Employee Agent ID