Register Salesforce Org using OAuth via External Client App (ECA)
Overview
To use Salesforce Org functionality within ARM, you must register your Salesforce organization. Registration enables ARM to securely connect to your Salesforce org with the required permissions.
ARM supports the following authentication methods:
Standard Authentication
OAuth via Connected App
OAuth via External Client App (ECA)
This article explains:
How to register a new Salesforce org using OAuth via External Client App (ECA)
How to migrate an existing org to this authentication type
Important considerations and limitations
Part 1: Salesforce Prerequisites
Before registering your org in ARM, complete the following configuration in Salesforce.
Step 1: Create an External Client App
Navigate to Salesforce Setup.
Search for External Client Apps.
Click New External Client App.
Enter the required details.
Basic Information
External Client App Name
API Name (auto-populated)
Contact Email
Enable OAuth Settings
Select Enable OAuth Settings.
Provide the Callback URL exactly as displayed in the ARM UI.
Add the following OAuth scopes:
Access the identity URL service (id, profile, email, address, phone)
Manage user data via APIs (api)
Full access (full)
Access Connect REST API resources (chatter_api)
Perform requests at any time (refresh_token, offline_access)
Access custom permissions (custom_permissions)
Flow Enablement
Enable the following:
Authorization Code and Credentials Flow &#xNAN;(Sub-options are not required.)
Save and Activate
Save the application and activate it.
Step 2: Collect Client Credentials
After activation, copy the following credentials:
Consumer ID (Consumer Key)
Consumer Secret
Note: Newly generated credentials may take up to 10 minutes to become active. If verification fails, wait and retry.
Part 2: Register a New Salesforce Org Using OAuth via ECA
Step 1: Open Org Registration
Navigate to:
Salesforce Org Management → Register Org
Step 2: Select Authentication Type
Choose:
OAuth via External Client App
Step 3: Enter Required Details
Provide the following information:
Name
Type
Login URL (Production / Sandbox / Custom Domain)
Consumer ID
Consumer Secret
Click Verify / Connect.
Step 4: Authorize in Salesforce
You will be redirected to the Salesforce login page.
Log in and approve ARM access.
Salesforce will redirect you back to ARM.
Step 5: Successful Registration
After successful authorization:
The org is registered.
Tokens are securely encrypted and stored.
The org becomes available across applicable ARM modules.
The connection status displays as Connected.
Part 3: Reauthentication
To reauthenticate an existing org:
Navigate to Org Details.
Click Reauthenticate.
Update the Consumer ID and/or Consumer Secret (if required).
Click Authenticate.
Complete the Salesforce authorization process.
After successful completion:
The connection status updates automatically.
The last authenticated timestamp is refreshed.
Part 4: Migrating an Existing Org to OAuth via ECA
Scenario
You have an org registered using:
Standard Authentication, or
OAuth via Connected App
You want to migrate to OAuth via External Client App (ECA) without re-registering the org.
Step 1: Open Org Details
Navigate to:
Salesforce Org Management → Select Org → Details
Step 2: Change Authentication Type
Select:
Move to OAuth via ECA
A guided migration panel will open.
Step 3: Create External Client App in Salesforce
Follow the guided instructions and create the External Client App as described in Part 1.
Step 4: Enter Client Credentials
Enter:
Consumer ID
Consumer Secret
Click Connect.
Step 5: Authorize in Salesforce
You will be redirected to Salesforce.
Log in and approve access.
Salesforce will redirect back to ARM.
Step 6: Migration Completion
Upon successful authorization:
The authentication type updates to OAuth via ECA.
The same org record is retained.
Pipelines, jobs, and mappings remain unchanged.
No new org entry is created.
The connection status displays as Connected.
The last authenticated timestamp is updated.
Failure Handling
If authentication fails:
A clear error message is displayed.
The existing connection remains unaffected.
You can retry without impacting current configurations.
Important: Dev Hub Registration
Please note the following limitations:
Dev Hub registration is supported only through OAuth (Connected App).
Dev Hub registration is not supported using:
Standard Authentication
OAuth via External Client App (ECA)
Additional notes:
Dev Hub registration is available only under: Settings → Salesforce Org
Dev Hub registration is no longer available in the SFDX module.
Existing Dev Hubs cannot be reauthenticated.
New Dev Hubs can be created using OAuth (Connected App) without issues.
Important: Updating Consumer ID and Consumer Secret
When updating credentials for an existing OAuth via ECA connection, the following behavior applies.
Test Connection Behavior
If you:
Update the Consumer ID or Consumer Secret
Click Test Connection
Do not complete OAuth authorization
Then:
The test may still display Success.
The system continues using previously authorized credentials stored in the backend.
The updated values are not applied yet.
When Are New Credentials Applied?
New credentials take effect only after completing the OAuth authorization flow successfully.
Until authorization is completed:
Existing tokens remain active.
Previous credentials remain in effect.
Backend values are not replaced.
Recommendation
After updating credentials:
Click Authenticate / Connect.
Complete Salesforce authorization.
Confirm that the connection status updates successfully.
Without completing authorization, the new credentials will not be validated or activated.
Last updated
Was this helpful?

