Want to build more secure external integrations while maintaining clean metadata? External client apps (ECAs) are your answer. Unlike traditional connected apps, ECAs offer a closed security model, full metadata compliance, and modern developer tooling. In this blog post, we’ll discuss how to create, configure, and manage ECAs to build integrations that your admins and developers will love.

Why ECAs matter

Traditional connected apps leave your org open by default. This means that once a connected app is created in an org locally, it can be used by any other org without installation. ECAs flip this model with a “closed by default” approach. This means that the app can’t be used until you explicitly allow them to do so by installing the ECA in your org.

ECAs also separate developer settings from subscriber policies, making your packages cleaner and more maintainable. Think of ECAs as connected apps with guardrails. They support the same OAuth flows but add built-in security features while allowing you to package developer settings, keeping subscriber policies separate. This separation means cleaner deployments and better control over your integration security.

Unlike connected apps, ECAs are fully metadata-compliant and support modern development workflows. You can control the version of your configurations, deploy across orgs, and manage settings through clear API interfaces.

Building secure integrations with ECAs

Let’s walk through the process of creating an ECA using Metadata API. We’ll start with the basic structure and then add OAuth capabilities. First, we’ll create our ECA header definition in XML, and then we’ll deploy it using Metadata API.

Here’s an example of an ECA header file:

The Distribution State field can be set to “Local” or “Packageable” depending on whether the ECA needs to be used locally in the org or if it also needs to be used in other orgs.

Next, lets look at how we can configure OAuth plugins settings and policies for an ECA.

Configuring OAuth plugin settings

In external client apps (ECAs), developer-controlled settings include features that developers define and package, such as OAuth flows, callback URLs, and scopes. These settings are part of the app’s core functionality and remain consistent across orgs.

On the other hand, admin-controlled subscriber policies are configurations set by the admin of the subscriber org. These include security-related policies like refresh token validity, allowed users, and session timeouts. These policies are not packageable, giving admins the flexibility to customize the app’s behavior to meet their org’s specific security and compliance needs.

After you’ve created the ECA, you’ll configure the OAuth plugin. This involves setting up both developer-controlled settings and subscriber policies that are controlled by admins. ECAs separate developer settings from subscriber policies. Developer settings like OAuth scopes and plugins are packageable, and subscriber policies for session management and IP restrictions are not. This separation gives admins and developers flexibility while maintaining their integration’s core functionality.

Developer settings define the core OAuth configuration. These settings are packageable and need to be managed in your source control. OAuth plugin settings, which are one type of developer-controlled setting, have two parts.

  • Global OAuth settings: These affect the local org, as well as every org where the ECA is deployed
  • OAuth settings: These affect the local instance

The example below shows Global OAuth plugin settings.

This example shows OAuth plugin settings.

Managing ECA policies

As mentioned above, admin-controlled subscriber policies in ECAs allow org admins to customize security settings, such as token validity and user access, ensuring tailored compliance and control.

To update an OAuth policies file, you first deploy an external client app on your Salesforce org. The OAuth policies file is auto-generated with default values that you can then change. Here how to do it:

  • Open the ExtlClntAppOauthConfigurablePolicies file on your org. The OAuth policies file is generated when the external client app is deployed, and its name follows this format: [ECAPP_OAUTH_POLICY].ecaOauthPlcy-meta.xml.
  • To set the configuration, edit the field values in the OAuth policies file. See Verify OAuth Policy and Settings Generation for information about the available OAuth policies fields.
  • Deploy the OAuth policies changes.
  • Retrieve the updated ECA information.

After the ECA OAuth policies plugin is deployed, you can enable plugins and configure settings and policies through the Setup UI or API. You can also track OAuth usage using Connect REST API.

Conclusion

ECAs modernize how you build Salesforce integrations. Their closed security model protects your org by default, their metadata compliance makes packaging and deployment easier, and their policy management gives admins and developers the control they need. Ready to get started? Check out the external client apps documentation or explore the External Client Apps Trailhead module to learn how to create an ECA. You can also watch a video of the Dreamforce 2024 session on mastering external client apps.

About the author

Daivat Dholakia is a Product Manager for Identity at Salesforce, where he focuses on connected apps, external client apps, and Salesforce Authenticator. Follow him on X and LinkedIn to stay updated on his work.

Get the latest Salesforce Developer blog posts and podcast episodes via Slack or RSS.

Add to Slack Subscribe to RSS