ExtlClntAppConfigurablePolicies Metadata Guide

Architectural Overview#

ExtlClntAppConfigurablePolicies represents the administrative policy domain within the Salesforce External Client App (ECA) architecture. In classical Connected App configurations, administrator access policies—such as user assignment restrictions, session timeouts, and IP relaxation rules—were co-located inside the same file as developer OAuth parameters and redirect URLs. Consequently, vendor package updates routinely overwrote subscriber security customizations.

The External Client App model introduces a clean separation of responsibilities. While ISVs and developers author integration endpoints and OAuth scopes, subscriber org administrators retain sovereign control via ExtlClntAppConfigurablePolicies. This metadata type allows security architects to mandate admin-approved user access, designate specific Permission Sets and Profiles, and enforce strict session timeouts.

By decoupling governance from development, enterprise security teams can check policy files into their tenant-specific repository and automate continuous policy validation without colliding with packaged vendor metadata.

Directory and File Conventions#

ExtlClntAppConfigurablePolicies metadata resides within the extlClntAppConfigurablePolicies folder:

Key Metadata Fields#

The ExtlClntAppConfigurablePolicies schema defines access control rules and session lifecycle parameters:

Declarative XML and Package Manifest Examples#

Below is a declarative XML file configuring zero-trust access policies for an External Client App:

<?xml version="1.0" encoding="UTF-8"?>
<ExtlClntAppConfigurablePolicies xmlns="http://soap.sforce.com/2006/04/metadata">
    <permittedUsers>AdminApprovedPreAuthorized</permittedUsers>
    <sessionTimeout>15</sessionTimeout>
    <permissionSetAccess>
        <permissionSet>Enterprise_Integration_Users</permissionSet>
    </permissionSetAccess>
    <isCanvasEnabled>true</isCanvasEnabled>
</ExtlClntAppConfigurablePolicies>

Package Manifest (package.xml)#

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

CLI Retrieval and Deployment Commands#

Manage configurable policy files using modern sf CLI commands:

# Retrieve configurable policies for a designated External Client App
sf project retrieve start --metadata ExtlClntAppConfigurablePolicies:Enterprise_Data_Sync

# Deploy security policies to production environment
sf project deploy start --metadata ExtlClntAppConfigurablePolicies:Enterprise_Data_Sync

# Retrieve all configurable policies across all registered client apps
sf project retrieve start --metadata ExtlClntAppConfigurablePolicies

Architect Best Practices and Gotchas#

• Zero-Trust Access Control: Always specify permittedUsers as AdminApprovedPreAuthorized. Permitting AllUsersMaySelfAuthorize allows any licensed user in your tenant to grant third-party OAuth access without IT oversight.
• Permission Sets Over Profiles: Architect user access by binding permissionSetAccess rather than hardcoding legacy profiles. Permission sets facilitate granular access auditing and modular permission assignment across personas.
• Deployment Dependencies: Ensure all referenced Permission Sets exist in the destination org prior to deploying ExtlClntAppConfigurablePolicies. Deploying policies referencing non-existent permission sets causes immediate validation failures.

Frequently asked questions

Who manages ExtlClntAppConfigurablePolicies in an enterprise org?

Subscriber system administrators manage configurable policies to dictate which users can run the app, session timeouts, and IP restrictions without touching developer code.

What is the security difference between Admin Approved and Self Authorize?

Admin Approved requires explicit Profile or Permission Set assignments before users can access the app, whereas Self Authorize allows any user to grant consent.

Why is ExtlClntAppConfigurablePolicies separated from OAuth settings?

This separation allows managed package vendors to update OAuth client definitions without overwriting local subscriber security policies in production.

How do you retrieve ExtlClntAppConfigurablePolicies with the sf CLI?

Use sf project retrieve start with metadata ExtlClntAppConfigurablePolicies to fetch local policy files into your repository.