Skip to main content

Migrating to External Client App (ECA)

Overview​

Starting with Salesforce Spring '26, new Connected Apps can no longer be created, and Salesforce requires External Client Apps (ECA) as the replacement. Starting with managed package version 3.0.0 and resource version 2.0.0, SCC-AC supports using an External Client App for the AWS-to-Salesforce integration.

This page is for existing installations that are set up with the Connected App awsscc GLOBAL_CONNECTED_APP. New installations use an External Client App from the start: see Installing SCC-AC (step 4, Option A) and Setting Up SCC-AC Using Guided Setup.

The External Client App replaces the Connected App awsscc GLOBAL_CONNECTED_APP only. Agents, contact flows, routing, and the contact center setup are not affected.

Note: Existing installations that use a Connected App continue to work for now. Salesforce controls how long Connected Apps remain supported, so we recommend migrating to the External Client App.

Migration moves SCC-AC from the Connected App to an External Client App in place:

  • Salesforce provides a one-click Migrate to External Client App button on the Connected App (see step 3). It keeps the same consumer key, consumer secret, and certificate, so you do not re-enter credentials.
  • SCC-AC updates the existing SCC-GLOBAL-STACK-{SalesforceOrgId} stack. Existing AWS resources are not recreated, and the existing values in SCCAC-Secret-{SalesforceOrgId} are kept. The update adds two new Lambda functions and three Secret keys (see FAQs).
  • The migration does not require downtime. Contacts continue to be handled while the stack updates.
  • The migration is one-way. After Salesforce migrates the Connected App, SCC-AC cannot be switched back to the Connected App.

NOTE: We recommend testing the migration in a sandbox first.

Before you begin​

  1. You can log in as the SCCAC Administrator user.
  2. You have AWS access to CloudFormation and Secrets Manager in us-east-1 for the AWS account used by SCC-AC.

Migration steps​

1) Upgrade the managed package to 3.0.0​

  1. Follow Managed Package Upgrade.
  2. IMPORTANT: Right after upgrading, before agents handle contacts, add field-level security (FLS) for the new SCC Global Configuration fields to your SCC Administrator and SCC Agent permission sets. The upgrade only updates the packaged Placeholder permission sets, not the ones you cloned from them. Without this step, contacts are not delivered to agents (see Troubleshooting).
    1. SCC Administrator: In Setup > Permission Sets, open SCC Administrator, choose Object Settings > SCC Global Configuration > Edit, and select Read Access and Edit Access for ECA Consumer Key, Is ECA, and Is New Customer. Choose Save.
    2. SCC Agent: Open SCC Agent, choose Object Settings > SCC Global Configuration > Edit, and select Read Access for ECA Consumer Key, Is ECA, and Is New Customer. Choose Save.
    3. Repeat for any other permission set or profile you use for SCC-AC administrators or agents. Users assigned only the Placeholder permission sets, or the System Administrator profile, already have access.
  3. Open guided setup. It now shows 7 steps, and step 5 is Migrate to External Client App. You do not redo the other steps: steps 1-4 and the certificate steps stay complete from your existing setup. The only new action is step 5, in step 4 of this guide.

IMPORTANT: Do not choose Migrate to ECA until the resources are on 2.0.0 or later (step 2) and the Connected App is migrated in Salesforce (step 3). Earlier resource versions cannot run the migration. Guided setup keeps Migrate to ECA disabled until it detects the Salesforce migration.

2) Update AWS resources to the latest version​

  1. In guided setup, scroll to Update Resources and choose Update. See AWS Resources Upgrade Process.
  2. In CloudFormation (us-east-1), wait for SCC-GLOBAL-STACK-{SalesforceOrgId} to reach UPDATE_COMPLETE, and confirm its Version parameter is 2.0.0 or later.
  3. Refresh guided setup and confirm Update Resources shows a green check mark.

3) Migrate the Connected App in Salesforce​

  1. Go to Setup > App Manager.
  2. Find awsscc GLOBAL_CONNECTED_APP and choose Migrate to External Client App. Follow the Salesforce wizard.
  3. In Setup > External Client Apps, confirm an External Client App with the API name awsscc_GLOBAL_CONNECTED_APP now exists, with type Local (Migrated).

IMPORTANT: Do not delete the Connected App awsscc GLOBAL_CONNECTED_APP.

Note: Salesforce keeps the original API name, so the migrated app is named awsscc_GLOBAL_CONNECTED_APP, not awsscc_GLOBAL_EXTERNAL_CLIENT_APP. This is expected.

4) Migrate SCC-AC to the External Client App​

  1. In guided setup, step 5 Migrate to External Client App, choose Migrate to ECA.
  2. In CloudFormation (us-east-1), wait for SCC-GLOBAL-STACK-{SalesforceOrgId} to reach UPDATE_COMPLETE.
  3. Refresh guided setup. Step 5 shows a green check mark.

5) (Optional) Rotate the certificate​

You do not need to re-apply the certificate after migrating. Salesforce's migration in step 3 carries your existing certificate over to the External Client App, and SCC-AC keeps working with it. Run the certificate steps only when you want a new certificate, for example before the current one expires. Follow your usual Certificate Upgrade Process, which includes a brief interruption while resources are updated. For a migrated org, the certificate steps are guided setup steps 6 and 7.

6) Verify​

  1. In Secrets Manager, SCCAC-Secret-{SalesforceOrgId}:
    • IS_ECA = true
    • ECA_CONSUMER_KEY and ECA_CONSUMER_SECRET match your existing Connected App consumer key and secret.
    • CONNECTED_APP_CONSUMER_KEY, CONNECTED_APP_CONSUMER_SECRET, and CERTIFICATE_KEY_PASSWORD are unchanged.
  2. If you rotated the certificate in step 5, SCC-GLOBAL-CERTIFICATE-APPLIED-RESOURCE-STACK-{SalesforceOrgId}-{Timestamp} is in CREATE_COMPLETE.
  3. Place a test chat and confirm it reaches an agent.

Troubleshooting​

After upgrading, agents don't receive chats or tasks, or guided setup shows a field-level security error

Inbound chats and tasks end with an error such as You do not have READ permission for Field "awsac__ECA_Consumer_Key__c" in object "awsac__SCCGlobalConfiguration__c", and guided setup can fail with the same error. The SCC Administrator or SCC Agent permission set you cloned before upgrading does not have access to the new SCC Global Configuration fields. Add the field-level security described in step 1.

Migrate to ECA stays disabled

Guided setup enables Migrate to ECA only after it detects the Salesforce migration in step 3, and only while SCC-GLOBAL-STACK-{SalesforceOrgId} is not being updated. Complete step 3, wait for any stack update to finish, then refresh guided setup.

The certificate stack fails with "No External Client App found among candidates"

The External Client App does not exist in the org, or the Salesforce migration in step 3 was not completed. Confirm the app exists in Setup > External Client Apps, then run the certificate steps again.

The certificate stack fails with "invalid_grant: no client credentials user enabled"

Client Credentials Flow is not enabled on the External Client App, or Run As is not set. In Setup > External Client Apps, open the app, choose Edit Policies, select Enable Client Credentials Flow, set Run As to your system admin user, and retry.

For CloudFormation failures, review the CloudWatch logs for the SCCAC-EcaManagerFunction-{SalesforceOrgId} and SCCAC-EcaSecretPopulatorFunction-{SalesforceOrgId} Lambda functions.

FAQs​

Do I have to migrate? Not right now. Existing Connected App installations continue to work for now, but Salesforce controls how long Connected Apps remain supported. We recommend migrating, because Salesforce no longer allows new Connected Apps to be created.

Does my consumer key change? No. Salesforce's migration keeps the consumer key and secret, and SCC-AC reuses them.

Are any AWS resources recreated? No existing resources are recreated. The migration updates SCC-GLOBAL-STACK-{SalesforceOrgId} in place. It adds two Lambda functions, SCCAC-EcaManagerFunction-{SalesforceOrgId} and SCCAC-EcaSecretPopulatorFunction-{SalesforceOrgId}, and three keys to the Secret: IS_ECA, ECA_CONSUMER_KEY, and ECA_CONSUMER_SECRET. See Appendix B: AWS Lambda Functions and Appendix B: AWS Secrets.

Can I roll back to the Connected App? No. The migration is one-way. Salesforce's migration in step 3 cannot be undone, so SCC-AC does not offer a rollback.