MyDomainSettings Metadata Type Guide

Architectural Overview#

MyDomainSettings controls the identity, branding, and network routing perimeter of a Salesforce tenant. It defines your organization-specific subdomain, enforces login endpoint policies, dictates redirection behaviors, and enables critical platform networking features such as Enhanced Domains and Salesforce Edge Network.

From a Technical Architect perspective, MyDomainSettings sits at the nexus of Single Sign-On (SSO), Experience Cloud, API integrations, and browser security. Changes to this metadata type directly influence authentication flows for Connected Apps, cross-origin resource sharing (CORS), and trust boundaries between sandbox and production instances.

Directory and File Conventions#

In SFDX source format, MyDomainSettings is a singleton settings type placed in the settings/ directory and retrieved using the Settings:MyDomain moniker.

Key Metadata Fields#

The XML schema for MyDomainSettings exposes high-impact networking and security flags:

Declarative XML and Package Manifest Examples#

Below is a production-grade configuration enforcing zero-trust login boundaries and privacy headers:

<?xml version="1.0" encoding="UTF-8"?>
<MyDomainSettings xmlns="http://soap.sforce.com/2006/04/metadata">
    <canOnlyLoginWithMyDomainUrl>true</canOnlyLoginWithMyDomainUrl>
    <doesHideBrowserReferrer>true</doesHideBrowserReferrer>
    <doesWarnOnExternalRedirect>true</doesWarnOnExternalRedirect>
    <useEdge>true</useEdge>
    <useEnhancedDomains>true</useEnhancedDomains>
</MyDomainSettings>

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

{
  "orgName": "Enterprise Identity Scratch Org",
  "edition": "Enterprise",
  "settings": {
    "myDomainSettings": {
      "canOnlyLoginWithMyDomainUrl": false,
      "doesHideBrowserReferrer": true,
      "doesWarnOnExternalRedirect": true,
      "useEdge": true
    }
  }
}

Package Manifest (package.xml)#

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

CLI Retrieval and Deployment Commands#

Manage MyDomainSettings using standard Salesforce CLI commands:

# Retrieve MyDomain settings from the authorized org
sf project retrieve start --metadata Settings:MyDomain

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

Architect Best Practices and Gotchas#

• CI/CD Authentication Lockouts: Avoid deploying canOnlyLoginWithMyDomainUrl: true into scratch orgs or sandboxes if automated pipeline credentials use generic login URLs. Always ensure JWT bearer flows target the exact instanceUrl matching your configured My Domain.
• Enhanced Domain Cutover: Renaming a My Domain or toggling Enhanced Domains triggers URL shifts across Visualforce, Experience Cloud sites, and Content Builder URLs. Verify integrations and third-party firewalls prior to deployment.
• Redirection Rules: Plan redirection deprecation rules when migrating legacy domain prefixes. Use the Salesforce event log files (LoginHistory and UriEventStream) to detect traffic hitting obsolete hostnames before disabling redirects.

Frequently asked questions

What happens when canOnlyLoginWithMyDomainUrl is set to true?

Users are blocked from authenticating via login.salesforce.com or test.salesforce.com and must use the org-specific My Domain login URL.

Why are Enhanced Domains critical for enterprise third-party cookie restrictions?

Enhanced Domains align all org application URLs under a consistent domain suffix, eliminating cross-site cookie blocking in modern web browsers.

How is MyDomainSettings represented in SFDX source format?

It is stored as MyDomain.settings-meta.xml in the force-app/main/default/settings directory and retrieved using Settings:MyDomain.