OauthOidcSettings Metadata Type Guide

Architectural Overview#

OauthOidcSettings is an org-level settings metadata type that enforces global authentication and token security policies for OAuth 2.0 and OpenID Connect (OIDC) protocols. As enterprise identity architectures evolve toward zero trust, this metadata type establishes tenant-wide rules for cryptographic token signing, Token Exchange flows (RFC 8693), and refresh token IP address validation.

For Enterprise Architects, configuring OauthOidcSettings ensures that Connected Apps and External Client Apps adhere to strict cryptographic baselines, mitigate token replay attacks, and integrate cleanly with modern Identity Providers such as Okta, Microsoft Entra ID, and PingFederate.

Directory and File Conventions#

OauthOidcSettings is configured as a singleton settings file under settings/.

Key Metadata Fields#

The XML schema defines organization-wide token and identity controls:

Declarative XML and Package Manifest Examples#

A hardened enterprise configuration for OAuth and OIDC security:

<?xml version="1.0" encoding="UTF-8"?>
<OauthOidcSettings xmlns="http://soap.sforce.com/2006/04/metadata">
    <enableOauthOidcApi>true</enableOauthOidcApi>
    <enableOauthRefreshTokenIpCheck>false</enableOauthRefreshTokenIpCheck>
    <enableOidcIdTokenSigning>true</enableOidcIdTokenSigning>
    <enableTokenExchangeFlow>true</enableTokenExchangeFlow>
</OauthOidcSettings>

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

To enable token exchange testing in ephemeral development scratch orgs:

{
  "orgName": "Identity Federation Scratch Org",
  "edition": "Enterprise",
  "settings": {
    "oauthOidcSettings": {
      "enableOauthOidcApi": true,
      "enableTokenExchangeFlow": true,
      "enableOidcIdTokenSigning": true
    }
  }
}

Package Manifest (package.xml)#

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

CLI Retrieval and Deployment Commands#

Use the Salesforce CLI to retrieve and deploy OauthOidcSettings:

# Retrieve OAuth OIDC settings
sf project retrieve start --metadata Settings:OauthOidc

# Deploy settings to target environment
sf project deploy start --metadata Settings:OauthOidc

Architect Best Practices and Gotchas#

• Token Exchange Prerequisites: If your architecture leverages OauthTokenExchangeHandler, you must deploy OauthOidcSettings with enableTokenExchangeFlow: true first, or the token exchange endpoint will reject incoming exchange requests with HTTP 400 errors.
• IdP Certificate Rotations: When utilizing OIDC ID token verification, ensure downstream services integrate with Salesforce’s discovery document (.well-known/openid-configuration) to automatically ingest rotated public verification keys.
• Mobile Client Re-authentication: Enabling refresh token IP checks will cause mobile users to encounter session expirations whenever their cellular carrier shifts gateway IPs. Evaluate device management strategies (MDM/VPN) before enabling.

Frequently asked questions

What is the role of OauthOidcSettings in Salesforce security?

OauthOidcSettings governs org-wide OAuth 2.0 security rules, OpenID Connect token signing algorithms, and token exchange flow permissions.

How does OauthOidcSettings harden refresh token security?

It enables IP binding policies for refresh tokens, preventing token theft and replay attacks across untrusted external networks.

Where is OauthOidcSettings stored in an SFDX project?

It is stored in force-app/main/default/settings/OauthOidc.settings-meta.xml and retrieved using Settings:OauthOidc.