ExternalClientAppSettings in Salesforce Metadata API

Architectural Overview#

The ExternalClientAppSettings metadata type represents the foundational org-level configuration that governs Salesforce External Client Apps (ECA). Historically, connected apps bundled developer secrets, consumer keys, and subscriber administration policies into a single monolithic XML artifact. This legacy design created profound security risks and packaging bottlenecks in enterprise second-generation packaging (2GP) workflows.

External Client Apps decouple developer-controlled integration definitions from subscriber-controlled security policies. ExternalClientAppSettings serves as the master switchboard across your enterprise environment. It activates the ECA runtime engine, enables canvas integration hosting, and authorises packaging pipelines to package decoupled ECA metadata descriptors.

Enterprise architects must treat ExternalClientAppSettings as an essential deployment prerequisite. In continuous delivery pipelines and ephemeral scratch org pools, any downstream deployment containing External Client App descriptors will fail immediately if the ECA platform subsystem has not been activated at the org level.

Directory and File Conventions#

In Salesforce DX project structures (apiVersion 68.0), ExternalClientAppSettings resides in the standard settings directory under the singular member name ExternalClientApp.

Key Metadata Fields#

The ExternalClientAppSettings XML schema includes boolean toggles that control the lifecycle and scope of External Client Apps:

Declarative XML and Package Manifest Examples#

Below is a production-hardened ExternalClientApp.settings-meta.xml configuration suitable for packaging pipelines and enterprise production environments:

<?xml version="1.0" encoding="UTF-8"?>
<ExternalClientAppSettings xmlns="http://soap.sforce.com/2006/04/metadata">
    <enableCanvasInExternalClientApps>true</enableCanvasInExternalClientApps>
    <enableExternalClientAppPackaging>true</enableExternalClientAppPackaging>
    <enableExternalClientApps>true</enableExternalClientApps>
</ExternalClientAppSettings>

Scratch Org Configuration (project-scratch-def.json)#

To provision scratch orgs ready for External Client App development, enable the feature in your definition file:

{
  "orgName": "External Client App Dev Org",
  "edition": "Developer",
  "features": ["EnablePRM"],
  "settings": {
    "externalClientAppSettings": {
      "enableExternalClientApps": true,
      "enableExternalClientAppPackaging": true,
      "enableCanvasInExternalClientApps": true
    }
  }
}

Manifest Definition (package.xml)#

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>ExternalClientApp</members>
        <name>Settings</name>
    </types>
    <version>68.0</version>
</Package>

CLI Retrieval and Deployment Commands#

Manage org-level External Client App settings using the modern Salesforce CLI (sf):

# Retrieve ExternalClientApp settings from the current target org
sf project retrieve start --metadata Settings:ExternalClientApp

# Deploy ExternalClientApp settings to an integration environment
sf project deploy start --metadata Settings:ExternalClientApp

# Preview deployment changes before executing deployment
sf project deploy preview --metadata Settings:ExternalClientApp

Architect Best Practices and Gotchas#

• CI/CD Build Pipeline Sequencing: Always deploy ExternalClientApp.settings-meta.xml in an early foundational pipeline wave. Attempting to deploy individual External Client App components (ExtlClntAppOauthSettings, ExtlClntAppGlobalOauthSettings) before activating enableExternalClientApps will trigger unrecoverable deployment errors.
• Migration Strategy from Connected Apps: Do not attempt in-place conversion of mission-critical Connected Apps. Instead, deploy new External Client Apps in parallel, assign test permission sets, validate OAuth token exchanges, and systematically deprecate the legacy Connected App.
• Packaging Boundaries: Setting enableExternalClientAppPackaging to true is mandatory in packaging orgs building second-generation packages (2GP). Without this setting enabled, package version creation commands (sf package version create) will fail when validating ECA metadata.

Frequently asked questions

What is the primary function of ExternalClientAppSettings in Salesforce?

ExternalClientAppSettings enables the External Client Apps framework, allowing orgs to decouple developer integrations from subscriber security policies and enable packaging.

Why should architects migrate from Connected Apps to External Client Apps?

External Client Apps separate developer OAuth settings from subscriber admin policies, eliminating metadata collisions and secret exposure during second-generation packaging.

How is ExternalClientAppSettings retrieved using the Salesforce CLI?

Run sf project retrieve start with the metadata flag set to Settings:ExternalClientApp, which writes ExternalClientApp.settings-meta.xml.

Can External Client Apps be packaged without enabling this setting?

No. The enableExternalClientAppPackaging flag within ExternalClientAppSettings must be enabled to package and install External Client Apps across environments.