SecuritySettings Metadata Type in SFDX

Architectural Overview#

SecuritySettings is the architectural bedrock of compliance, authentication posture, and access security in Salesforce. It encapsulates the core security settings governing session lifetimes, password complexity, identity verification, trusted network IP ranges (networkAccess), and Single Sign-On (SSO) enforcement.

In enterprise deployments, managing SecuritySettings via declarative metadata version control is mandatory for SOC 2, HIPAA, and ISO 27001 audits. Relying on manual setup adjustments introduces security drift between environments. By codifying security controls in Security.settings-meta.xml, security architects ensure that developer sandboxes, UAT environments, and production instances enforce uniform information security standards.

Directory and File Conventions#

In SFDX source format, SecuritySettings is stored in the settings directory under the filename Security.settings-meta.xml.

Key Metadata Fields#

The SecuritySettings schema contains multiple complex subtypes:

NetworkAccess and IpRanges#

<networkAccess>
    <ipRanges>
        <description>Corporate VPN Gateway</description>
        <end>198.51.100.254</end>
        <start>198.51.100.1</start>
    </ipRanges>
</networkAccess>

Declarative XML and Package Manifest Examples#

Below is a production-hardened Security.settings-meta.xml complying with modern corporate security standards:

<?xml version="1.0" encoding="UTF-8"?>
<SecuritySettings xmlns="http://soap.sforce.com/2006/04/metadata">
    <canUsersGrantLoginAccess>true</canUsersGrantLoginAccess>
    <networkAccess>
        <ipRanges>
            <description>Corporate HQ Primary Gateway</description>
            <end>203.0.113.254</end>
            <start>203.0.113.1</start>
        </ipRanges>
        <ipRanges>
            <description>CI/CD Build Pipeline Dedicated Runner</description>
            <end>198.51.100.50</end>
            <start>198.51.100.50</start>
        </ipRanges>
    </networkAccess>
    <passwordPolicies>
        <complexity>SpecialCharacters</complexity>
        <expiration>NinetyDays</expiration>
        <historyRestriction>24</historyRestriction>
        <lockoutInterval>FifteenMinutes</lockoutInterval>
        <maxLoginAttempts>FiveAttempts</maxLoginAttempts>
        <minimumPasswordLength>12</minimumPasswordLength>
        <minimumPasswordLifetime>true</minimumPasswordLifetime>
        <obscureSecretAnswer>true</obscureSecretAnswer>
        <questionRestriction>DoesNotContainPassword</questionRestriction>
    </passwordPolicies>
    <sessionSettings>
        <disableTimeoutWarning>false</disableTimeoutWarning>
        <enableCSRFOnGet>true</enableCSRFOnGet>
        <enableCSRFOnPost>true</enableCSRFOnPost>
        <enableCacheAndAutocomplete>false</enableCacheAndAutocomplete>
        <enableClickjackNonsetupSFDC>true</enableClickjackNonsetupSFDC>
        <enableClickjackNonsetupUser>true</enableClickjackNonsetupUser>
        <enableClickjackSetup>true</enableClickjackSetup>
        <enablePostForSessions>true</enablePostForSessions>
        <enableSMSIdentity>true</enableSMSIdentity>
        <forceLogoutOnSessionTimeout>true</forceLogoutOnSessionTimeout>
        <forceRelogin>true</forceRelogin>
        <lockSessionsToDomain>true</lockSessionsToDomain>
        <lockSessionsToIp>false</lockSessionsToIp>
        <sessionTimeout>TwoHours</sessionTimeout>
    </sessionSettings>
</SecuritySettings>

Manifest Definition (package.xml)#

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

Retrieval and Deployment#

Retrieve and deploy SecuritySettings using the CLI:

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

# Deploy Security settings
sf project deploy start --metadata "Settings:Security"

Senior Architect Deployment Best Practices and Gotchas#

1. Lock Sessions to IP Address: Setting lockSessionsToIp to true can cause severe session drops in organizations where mobile users or remote workers roam between cellular towers and VPN tunnels with dynamic IP addresses. Use with caution.
2. Environment Variable Separation: Maintain environment-specific branches or deployment parameter replacements for networkAccess. Sandbox IP ranges often include office staging networks that should never be trusted in production.
3. Session Timeout vs. Integration Users: Enforcing short timeouts in sessionSettings applies to interactive UI sessions. Ensure integration users utilize Connected Apps and OAuth token flows rather than web sessions to prevent authentication interruptions.
4. Destructive Changes on IP Ranges: Always perform pre-deployment diffs on Security.settings-meta.xml. A careless git merge can drop critical API gateway IP ranges and interrupt mission-critical third-party integrations.

Frequently asked questions

What critical security controls are managed in SecuritySettings?

SecuritySettings controls network IP whitelisting, session timeouts, password complexity rules, lockout thresholds, and SSO redirection policies.

Where is SecuritySettings stored in an SFDX repository?

In force-app/main/default/settings/Security.settings-meta.xml and retrieved using the Settings:Security metadata identifier.

What happens if a deployment overwrites networkAccess IP ranges?

Deploying an incomplete networkAccess block can lock out integrations, CI/CD runners, and remote users whose IP ranges were omitted.

How does session timeout configuration prevent session hijacking?

Locking session timeouts and enforcing high assurance session requirements ensures dormant sessions terminate and prompt for re-authentication.