ConnectedApp Metadata Type and OAuth Security Guide

Overview#

The ConnectedApp metadata type (connectedApps/<AppName>.connectedApp-meta.xml) configures an OAuth 2.0, OpenID Connect, SAML 2.0 Single Sign-On, or Canvas integration boundary for external applications, middleware, mobile apps, and headless CI/CD pipelines (sf org login jwt).

An important architectural milestone for Salesforce developers: starting in Spring ’26 (API v66.0), Salesforce restricted the creation of new ConnectedApp components in favor of the modern, second-generation packaging-friendly ExternalClientApplication metadata architecture. Existing ConnectedApp definitions continue to run and can be updated via Metadata API across sandboxes and production orgs.

As shown in the diagram above, a secure enterprise ConnectedApp locks down oauthConfig with least-privilege scopes, sets isAdminApproved to true, and delegates access strictly through <permissionSetName> assignments rather than allowing arbitrary users to self-authorize.

Prerequisites#

• Permissions: “Manage Connected Apps” and “Customize Application” permissions.
• Certificate for JWT / Client Credentials: A PEM-encoded X.509 public certificate string (without -----BEGIN CERTIFICATE----- headers) when configuring headless JWT Bearer authentication.
• API Version: Introduced in API version 29.0. Verified against API version 68.0 (Winter ’27).

Key ConnectedApp XML Security Elements#

Querying Connected Apps and Active OAuth Tokens via SOQL#

You can audit installed and local Connected Apps along with active user tokens using standard SOQL on ConnectedApplication and OauthToken.

1. Audit All Connected Apps and Their Security Policies (Standard SOQL)#

SELECT Id, Name, OptionsAllowAdminApprovedUsersOnly,
       OptionsRefreshTokenValidityMetric, RefreshTokenValidityPeriod,
       SessionTimeout, PinLength, CreatedBy.Name, LastModifiedDate
FROM ConnectedApplication
ORDER BY Name ASC

2. Inspect Active OAuth Tokens and Usage Counts by App (Standard SOQL)#

Identify which Connected Apps have active tokens and when they were last used:

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

Example#

The following GitHub_Actions_CI.connectedApp-meta.xml configures a hardened, pre-authorized Connected App for headless CI/CD pipelines (sf org login jwt), restricted to the CI_CD_Deployment_Bot permission set with least-privilege Api and RefreshToken scopes.

<?xml version="1.0" encoding="UTF-8"?>
<ConnectedApp xmlns="http://soap.sforce.com/2006/04/metadata">
    <contactEmail>devops-security@example.com</contactEmail>
    <description>Headless OAuth 2.0 JWT Bearer Connected App for GitHub Actions CI/CD deployments.</description>
    <label>GitHub Actions CI</label>
    <oauthConfig>
        <callbackUrl>http://localhost:1717/OauthRedirect</callbackUrl>
        <certificate>MIIDjTCCAnWgAwIBAgIJAK8...base64EncodedX509Cert...</certificate>
        <isAdminApproved>true</isAdminApproved>
        <isClientCredentialEnabled>false</isClientCredentialEnabled>
        <isCodeCredentialEnabled>false</isCodeCredentialEnabled>
        <isConsumerSecretOptional>false</isConsumerSecretOptional>
        <isIntrospectAllTokens>false</isIntrospectAllTokens>
        <isNamedUserJwtEnabled>false</isNamedUserJwtEnabled>
        <isPkceRequired>true</isPkceRequired>
        <isRefreshTokenRotationEnabled>false</isRefreshTokenRotationEnabled>
        <isSecretRequiredForRefreshToken>true</isSecretRequiredForRefreshToken>
        <isSecretRequiredForTokenExchange>false</isSecretRequiredForTokenExchange>
        <isTokenExchangeEnabled>false</isTokenExchangeEnabled>
        <scopes>Api</scopes>
        <scopes>RefreshToken</scopes>
    </oauthConfig>
    <oauthPolicy>
        <ipRelaxation>ENFORCE</ipRelaxation>
        <isTokenExchangeFlowEnabled>false</isTokenExchangeFlowEnabled>
        <refreshTokenPolicy>zero</refreshTokenPolicy>
    </oauthPolicy>
    <permissionSetName>CI_CD_Deployment_Bot</permissionSetName>
    <sessionPolicy>
        <sessionLevel>HIGH_ASSURANCE</sessionLevel>
        <sessionTimeout>120</sessionTimeout>
    </sessionPolicy>
</ConnectedApp>

Limits and Gotchas#

• PermissionSet and Profile Names Use Labels in ConnectedApp XML: Uniquely in Metadata API, <permissionSetName> and <profileName> inside ConnectedApp reference the Label of the Permission Set or Profile in many API versions—ensure your Permission Set label and fullName match or verify in a scratch org before deploying to Production.
• 2–10 Minute Propagation Delay: After creating or updating a ConnectedApp’s consumerKey or certificate, Salesforce’s global OAuth edge gateways take 2 to 10 minutes to propagate the change. Immediate JWT login attempts may return invalid_client_id during the first few minutes.
• Removing All PermissionSets on Deploy: To clear all assigned permission sets from a ConnectedApp via Metadata API, deploy an empty <permissionSetName></permissionSetName> element.

Related Official Documentation#

• ConnectedApp Metadata API Reference: Complete XML specification for ConnectedApp, ConnectedAppOauthConfig, and ConnectedAppOauthPolicy.
• ExternalClientApplication Metadata API Reference: Next-generation replacement for Connected Apps in Spring ’26 and Winter ’27.

Frequently asked questions

Can I still create new ConnectedApp components in Spring '26 and Winter '27?

As of Spring '26 (API v66.0), Salesforce restricts the creation of new ConnectedApps by default and recommends using ExternalClientApplication instead. Existing ConnectedApps continue to work and can be updated and deployed across environments.

Why should consumerKey and consumerSecret be omitted when deploying a ConnectedApp to a new org?

Each Salesforce org requires a globally unique Consumer Key. Including an existing org's consumerKey in .connectedApp-meta.xml when deploying to a new org causes a duplicate key error. Omit consumerKey on initial creation so Salesforce generates a new one.

How do I pre-authorize a ConnectedApp for headless JWT Bearer CI/CD pipelines?

In oauthConfig, set isAdminApproved to true, embed the X.509 base64 public certificate in the certificate tag, and assign access using permissionSetName or profileName elements on the ConnectedApp.

How do I enforce PKCE and refresh token rotation on a ConnectedApp?

Inside oauthConfig, set isPkceRequired to true to require Proof Key for Code Exchange on Authorization Code flows, and set isRefreshTokenRotationEnabled to true.

How do I query active ConnectedApp configurations and OAuth token usage via SOQL?

Query the ConnectedApplication standard object in SOQL to inspect installed and local Connected Apps, and query OauthToken to audit active user refresh and access tokens.