IframeWhiteListUrlSettings in SFDX

Architectural Overview#

IframeWhiteListUrlSettings manages clickjack protection policies and defines external domains permitted to embed Salesforce pages within HTML iframes. Clickjacking is a malicious attack where an attacker embeds a legitimate application into a transparent iframe on a malicious website, tricking users into clicking invisible buttons or executing unauthorized transactions.

By default, Salesforce enforces strict clickjack protection on Visualforce pages, Lightning Out applications, and Experience Cloud sites. IframeWhiteListUrlSettings configures trusted domains allowed as frame ancestors, translating directly into HTTP response headers such as Content-Security-Policy: frame-ancestors and X-Frame-Options.

Directory and File Conventions#

IframeWhiteListUrlSettings belongs to the standard settings metadata type:

Key Metadata Fields#

The IframeWhiteListUrlSettings XML schema defines trusted iframe origins:

Declarative XML and Package Manifest Examples#

Below is a production IframeWhiteListUrl.settings-meta.xml configuration allowing an enterprise corporate portal to frame Salesforce:

<?xml version="1.0" encoding="UTF-8"?>
<IframeWhiteListUrlSettings xmlns="http://soap.sforce.com/2006/04/metadata">
    <enableIframeWhiteList>true</enableIframeWhiteList>
</IframeWhiteListUrlSettings>

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

{
  "orgName": "Clickjack Protection Scratch Org",
  "edition": "Enterprise",
  "settings": {
    "iframeWhiteListUrlSettings": {
      "enableIframeWhiteList": true
    }
  }
}

Package Manifest (package.xml)#

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

Retrieval and Deployment via SF CLI#

Retrieve and deploy iframe whitelist settings:

# Retrieve IframeWhiteListUrl settings
sf project retrieve start --metadata "Settings:IframeWhiteListUrl"

# Deploy settings to production
sf project deploy start --metadata "Settings:IframeWhiteListUrl" --target-org production-org

Senior Architect Best Practices and Gotchas#

• Protocol Matching: Ensure whitelisted URLs explicitly include the https:// protocol scheme. HTTP origins will be rejected by modern browser security policies.
• Port Matching: For local testing or development proxies, include the port number (e.g., https://localhost:8443) in trusted URL configurations.
• Subdomain Explicit Configuration: Avoid overly permissive top-level domains. Whitelist specific, fully qualified domain names (FQDNs) to minimize clickjack attack vectors.

Frequently asked questions

What is the primary security role of IframeWhiteListUrlSettings?

It manages clickjack protection rules and whitelists domains permitted to frame Salesforce pages.

Where is IframeWhiteListUrlSettings stored in source code?

It is stored in force-app/main/default/settings/IframeWhiteListUrl.settings-meta.xml.

What browser security header is influenced by these settings?

It controls the Content Security Policy frame-ancestors directive and legacy X-Frame-Options headers.

Can wildcard domains be configured in IframeWhiteListUrlSettings?

Wildcards are restricted based on security policies; explicitly qualified subdomains are recommended.