ConnectedAppSettings Metadata Type in SFDX

Architectural Overview#

One of the most critical Zero-Trust security controls in Salesforce is API Access Control. By default in older orgs, any user with the “API Enabled” permission could click through an OAuth consent screen for an unverified third-party application (such as a browser plugin or external data loader), granting that app an OAuth refresh token scoped to the user’s data access.

The ConnectedAppSettings metadata type (ConnectedApp.settings-meta.xml) allows security architects to enforce API Access Control declaratively across all environments. By locking down connected app access at the org level (enableAdminApprovedAppsOnly), all connected apps are blocked by default unless they are explicitly installed and configured as “Admin approved users are pre-authorized” with assigned PermissionSet or Profile grants.

SFDX Directory and File Suffix#

Key Metadata Fields#

ConnectedAppSettings exposes boolean flags that control org-wide API Access Control enforcement.

Declarative XML Example#

The following ConnectedApp.settings-meta.xml enforces strict API Access Control across the org while allowing a controlled escape hatch (enableGiveAccessToToggle) via the “Use Any API Client” permission for system administrators.

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

package.xml Manifest#

Deploy ConnectedAppSettings using the Settings metadata type with the ConnectedApp member:

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

Auditing OAuth App Usage via SOQL and SFDX CLI#

Before deploying enableAdminApprovedAppsOnly = true to Production, always audit which connected apps currently have active OAuth tokens so you do not inadvertently break critical middleware, ETL pipelines, or Salesforce CLI integrations.

1. Audit Active OAuth Tokens by Connected App (OauthToken)#

SELECT AppName, UserId, User.Username, UseCount, LastUsedDate, CreatedDate
FROM OauthToken
ORDER BY LastUsedDate DESC
LIMIT 100

2. Inspect Installed Connected Apps (ConnectedApplication)#

SELECT Id, Name, OptionsAllowAdminApprovedUsersOnly, OptionsRefreshTokenValidityMetric,
       RefreshTokenValidityPeriod, CreatedDate
FROM ConnectedApplication
ORDER BY Name ASC

3. SFDX CLI Retrieve and Deploy Commands#

# Retrieve current ConnectedAppSettings from the target org
sf project retrieve start --metadata Settings:ConnectedApp

# Deploy hardened ConnectedAppSettings to enforce API Access Control
sf project deploy start --metadata Settings:ConnectedApp

Architect Best Practices and Gotchas#

• Pre-Install First-Party Tools: Before flipping enableAdminApprovedAppsOnly to true, navigate to Setup -> Connected Apps OAuth Usage, click Install next to Salesforce CLI, Salesforce for Outlook, or your CI/CD ConnectedApp, and assign a dedicated PermissionSet to your DevOps service accounts.
• Avoid Broadly Granting “Use Any API Client”: When enableGiveAccessToToggle is true, treat the “Use Any API Client” system permission as a privileged administrative capability equivalent to “Modify All Data” for OAuth client consent. Never assign it to standard Sales or Service users.

Frequently asked questions

What is the primary security function of ConnectedAppSettings?

ConnectedAppSettings controls API Access Control at the org level, restricting users from authorizing unapproved or uninstalled OAuth connected apps unless an admin explicitly approves them and assigns profiles or permission sets.

Where is ConnectedAppSettings stored in an SFDX repository?

It resides in force-app/main/default/settings/ConnectedApp.settings-meta.xml and is retrieved using the Settings metadata type with member ConnectedApp.

What is the difference between ConnectedApp and ConnectedAppSettings?

ConnectedApp defines an individual OAuth client or canvas integration, whereas ConnectedAppSettings defines the org-wide governance policy that controls how all connected apps are authorized across the org.

How does API Access Control prevent OAuth phishing attacks?

When enableAdminApprovedAppsOnly is enabled in ConnectedAppSettings, end users cannot self-authorize third-party OAuth apps via browser consent prompts unless the app is installed and pre-authorized.