ExtlClntAppOauthConfigurablePolicies in SFDX

Architectural Overview#

ExtlClntAppOauthConfigurablePolicies represents the subscriber-administered OAuth governance layer within the Salesforce External Client App architecture. In legacy Connected Apps, operational security policies—such as IP range enforcement, refresh token expiration intervals, and single logout handlers—were intermingled with technical OAuth client parameters.

This metadata type establishes a clear security boundary for OAuth execution. While integration developers specify required OAuth scopes and callback endpoints, the subscriber security team retains exclusive authority over operational risk parameters via ExtlClntAppOauthConfigurablePolicies. This guarantees that enterprise tenant policies—such as zero-trust IP restrictions and token revocation rules—are strictly enforced regardless of updates shipped by software vendors.

Enterprise security teams can version-control this metadata within tenant-specific repositories, enabling continuous compliance auditing and automated promotion across sandbox environments.

Directory and File Conventions#

ExtlClntAppOauthConfigurablePolicies metadata files reside within the extlClntAppOauthConfigurablePolicies folder:

Key Metadata Fields#

The ExtlClntAppOauthConfigurablePolicies XML schema defines runtime OAuth security parameters:

Declarative XML and Package Manifest Examples#

Below is a declarative XML definition of ExtlClntAppOauthConfigurablePolicies configured for high-security enterprise environments:

<?xml version="1.0" encoding="UTF-8"?>
<ExtlClntAppOauthConfigurablePolicies xmlns="http://soap.sforce.com/2006/04/metadata">
    <ipRelaxation>Enforce</ipRelaxation>
    <isTokenExchangeEnabled>false</isTokenExchangeEnabled>
    <refreshTokenPolicy>SpecifiedDays</refreshTokenPolicy>
    <refreshTokenValidity>30</refreshTokenValidity>
    <singleLogoutUrl>https://erp.enterprise.com/auth/single-logout</singleLogoutUrl>
</ExtlClntAppOauthConfigurablePolicies>

Package Manifest (package.xml)#

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

CLI Retrieval and Deployment Commands#

Retrieve and deploy OAuth configurable policy metadata using the Salesforce CLI:

# Retrieve OAuth configurable policies for the designated app
sf project retrieve start --metadata ExtlClntAppOauthConfigurablePolicies:Enterprise_ERP_Integration

# Deploy OAuth policies to target environment
sf project deploy start --metadata ExtlClntAppOauthConfigurablePolicies:Enterprise_ERP_Integration

# Deploy all policy files across the repository
sf project deploy start --metadata "ExtlClntAppOauthConfigurablePolicies,ExtlClntAppConfigurablePolicies"

Architect Best Practices and Gotchas#

• IP Relaxation Security Risks: Setting ipRelaxation to RelaxForApp bypasses profile-level login IP ranges. While necessary for integrations originating from dynamic cloud IP pools (e.g., AWS Lambda or Azure Functions), never relax IP restrictions without pairing with mutual TLS (mTLS) or strong OAuth client authentication.
• Refresh Token Invalidation: When refreshTokenPolicy is configured as SpecifiedDays, ensure automated integration services execute daily synthetic health checks. If a service remains dormant beyond the specified lifespan, the refresh token expires and requires human intervention to re-authenticate.
• Single Logout URL Validation: Ensure the singleLogoutUrl points to an HTTPS endpoint that can parse standard OpenID Connect logout tokens asynchronously without timing out.

Frequently asked questions

What does ExtlClntAppOauthConfigurablePolicies govern in an org?

It governs subscriber OAuth runtime policies such as IP address relaxation, refresh token expiration schedules, and single logout URL redirects.

What is the impact of setting IP relaxation to Relax IP Restrictions?

Setting IP relaxation to relax restrictions allows API clients to connect from any public IP, bypassing user profile login IP ranges for OAuth integrations.

How does the refresh token policy prevent stale API sessions?

Administrators can configure refresh tokens to expire immediately upon session termination or after a specific number of days of inactivity.

Can ExtlClntAppOauthConfigurablePolicies be customized per subscriber org?

Yes. As a configurable policy metadata type, each subscriber org tailors these settings to their enterprise security baselines without breaking the app.