configuring-connected-apps
Salesforce Connected Apps and External Client Apps OAuth configuration with 120-point scoring. Use this skill to configure OAuth flows, JWT bearer auth, Connected Apps, and External Client Apps in Salesforce. TRIGGER when: user configures OAuth flows, JWT bearer auth, Connected Apps, ECAs, or touches .connectedApp-meta.xml / .eca-meta.xml files. DO NOT TRIGGER when: configuring Named Credentials for callouts (use building-sf-integrations), reviewing permission policies (use deploying-metadata), or writing Apex token-handling code (use generating-apex).
- Installs
- 2.8K
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/forcedotcom/sf-skills --skill configuring-connected-apps- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads configuring-connected-apps automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
configuring-connected-apps: Salesforce Connected Apps & External Client Apps
Use this skill when the user needs OAuth app configuration in Salesforce: Connected Apps, External Client Apps (ECAs), JWT bearer setup, PKCE decisions, scope design, or migration from older Connected App patterns to newer ECA patterns.
Scope
In scope:
.connectedApp-meta.xmlor.eca-meta.xmlfiles- OAuth flow selection and callback / scope setup
- JWT bearer auth, device flow, client credentials, or auth-code decisions
- Connected App vs External Client App architecture choices
- Consumer key / secret / certificate handling strategy
Out of scope — delegate elsewhere:
- Configuring Named Credentials or runtime callouts → building-sf-integrations
- Deploying metadata to orgs → deploying-metadata
- Writing Apex token-handling code → generating-apex
First Decision: Connected App or External Client App
| If the need is... | Prefer |
|---|---|
| simple single-org OAuth app | Connected App |
| new development with better secret handling | External Client App |
| multi-org / packaging / stronger operational controls | External Client App |
| straightforward legacy compatibility | Connected App |
Default guidance:
- Choose ECA for new regulated, packageable, or automation-heavy solutions.
- Choose Connected App when simplicity and legacy compatibility matter more.
- Spring '26 note: creation of new Connected Apps is disabled by default in orgs. For new integrations, prefer External Client Apps unless Connected App compatibility is explicitly required.
Required Inputs
Ask for or infer:
- App type: Connected App or ECA
- OAuth flow: auth code, PKCE, JWT bearer, device, client credentials
- Client type: confidential vs public
- Callback URLs / redirect surfaces
- Required scopes
- Distribution model: local org only vs packageable / multi-org
- Whether certificates or secret rotation are required
Workflow
1. Choose the app model
Decide whether a Connected App or ECA is the better long-term fit using the decision table above.
2. Choose the OAuth flow
| Use case | Default flow |
|---|---|
| backend web app | Authorization Code |
| SPA / mobile / public client | Authorization Code + PKCE |
| server-to-server / CI/CD | JWT Bearer |
| device / CLI auth | Device Flow |
| service account style app | Client Credentials (typically ECA) |
3. Start from the right template
Read the appropriate template before generating — do not build from scratch:
| Template | Use case |
|---|---|
assets/connected-app-basic.xml | Simple API integration, minimal OAuth |
assets/connected-app-oauth.xml | Web app with full OAuth 2.0 configuration |
assets/connected-app-jwt.xml | JWT bearer / server-to-server |
assets/connected-app-canvas.xml | Embedding external apps in Salesforce UI (Canvas) |
assets/external-client-app.xml | ECA header file — all new ECA builds start here |
assets/eca-global-oauth.xml | ECA global OAuth settings (scopes, PKCE, rotation) |
assets/eca-oauth-settings.xml | ECA per-app OAuth settings |
assets/eca-policies.xml | ECA configurable policies |
If you need source-controlled ECA OAuth security metadata, retrieve it from an org first and treat the retrieved file as the schema source of truth:
sf project retrieve start --metadata ExtlClntAppOauthSecuritySettings:<AppName> --target-org <alias>
4. Apply security hardening
Read references/security-checklist.md for the full 120-point security checklist. Favor:
- Least-privilege scopes
- Explicit callback URLs
- PKCE for public clients
- Certificate-based auth where appropriate
- Rotation-ready secret / key handling
- IP restrictions when realistic and maintainable
5. Validate deployment readiness
Read references/testing-validation-guide.md before handoff. Confirm:
- Metadata file naming is correct (see Gotchas below)
- Scopes are justified
- Callback and auth model match the real client type
- Secrets are not embedded in source
6. Handle errors
If deployment fails, check the error output for:
DUPLICATE_VALUE— a Connected App or ECA with this name already exists; rename or retrieve-then-update insteadINVALID_CROSS_REFERENCE_KEY— theexternalClientApplicationname in an ECA settings file doesn't match the.eca-meta.xmlfilename exactlyINSUFFICIENT_ACCESS_OR_READONLY— user lacks the "Manage Connected Apps" permission- If any step fails, do not proceed to the next step — surface the error to the user with the specific message above
Rules / Constraints
| Rule | Rationale |
|---|---|
| Never commit consumer secrets to source control | Credential exposure risk |
Never use Full scope by default | Unnecessary privilege; request only what the app needs |
| Always use PKCE for public clients (mobile, SPA) | Prevents auth code interception |
| Never use wildcard or overly broad callback URLs | Token interception risk |
| ECA OAuth security settings must be retrieved from org before editing | File schema is not fully documented; retrieve-first ensures accuracy |
Use <alias> placeholders in CLI commands, never hardcoded org URLs | Org URLs vary per environment |
Detect actual packageDirectory from sfdx-project.json before writing files | Projects may not use the default force-app/main/default/ layout |
Metadata Notes That Matter
Connected App
Default source location (verify via sfdx-project.json → packageDirectories):
<packageDir>/connectedApps/
External Client App
ECA metadata spans multiple top-level source directories. Default locations (verify via sfdx-project.json):
| Directory | Metadata type | File suffix |
|---|---|---|
<packageDir>/externalClientApps/ | ExternalClientApplication | .eca-meta.xml |
<packageDir>/extlClntAppGlobalOauthSets/ | ExtlClntAppGlobalOauthSettings | .ecaGlblOauth-meta.xml |
<packageDir>/extlClntAppOauthSettings/ | ExtlClntAppOauthSettings | .ecaOauth-meta.xml |
<packageDir>/extlClntAppOauthSecuritySettings/ | ExtlClntAppOauthSecuritySettings | .ecaOauthSecurity-meta.xml |
<packageDir>/extlClntAppOauthPolicies/ | ExtlClntAppOauthConfigurablePolicies | .ecaOauthPlcy-meta.xml |
<packageDir>/extlClntAppPolicies/ | ExtlClntAppConfigurablePolicies | .ecaPlcy-meta.xml |
Gotchas
| Gotcha | Detail |
|---|---|
.ecaGlblOauth not .ecaGlobalOauth | The global OAuth suffix is abbreviated — using the long form will break deployment |
.ecaPlcy not .ecaPolicy | Same abbreviation pattern — the general policy suffix is short form |
.ecaOauthSecurity for security settings | Use .ecaOauthSecurity, not .ecaSecurity |
| ECA OAuth security settings are retrieve-only | Cannot be created from scratch in source — always retrieve from org first |
| Spring '26: new Connected Apps disabled by default | New orgs block Connected App creation; use ECA unless explicitly required |
| Consumer key is generated post-deploy | You cannot set the consumer key in metadata — retrieve it after first deployment |
Output Expectations
When finishing, confirm and report in this order:
- App type chosen — Connected App or External Client App
- OAuth flow chosen
- Files created or updated — list each metadata file path
- Security decisions — scopes, PKCE, certs, secrets, IP policy
- Next deployment / testing step
Suggested output shape:
App: <name>
Type: Connected App | External Client App
Flow: <oauth flow>
Files: <paths>
Security: <scopes, PKCE, certs, secrets, IP policy>
Next step: <deploy, retrieve consumer key, or test auth flow>
Score: <x>/120
Cross-Skill Integration
| Need | Delegate to | Reason |
|---|---|---|
| Named Credential / callout runtime config | building-sf-integrations | runtime integration setup |
| Deploy app metadata | deploying-metadata | org validation and deployment |
| Apex token or refresh handling | generating-apex | implementation logic |
Score Guide
| Score | Meaning |
|---|---|
| 80+ | production-ready OAuth app config |
| 54–79 | workable but needs hardening review |
| < 54 | block deployment until fixed |
Reference File Index
| File | When to read |
|---|---|
assets/connected-app-basic.xml | Step 3 — template for simple Connected App with minimal OAuth |
assets/connected-app-oauth.xml | Step 3 — template for full OAuth 2.0 Connected App |
assets/connected-app-jwt.xml | Step 3 — template for JWT bearer / server-to-server Connected App |
assets/connected-app-canvas.xml | Step 3 — template for Canvas app embedding in Salesforce UI |
assets/external-client-app.xml | Step 3 — ECA header file template |
assets/eca-global-oauth.xml | Step 3 — ECA global OAuth settings template (PKCE, rotation, callbacks) |
assets/eca-oauth-settings.xml | Step 3 — ECA per-app OAuth settings template |
assets/eca-policies.xml | Step 3 — ECA configurable policies template |
references/oauth-flows-reference.md | Step 2 — detailed OAuth flow comparison and decision guide |
references/security-checklist.md | Step 4 — full 120-point security scoring checklist |
references/testing-validation-guide.md | Step 5 — pre-deployment validation and testing guide |
references/migration-guide.md | When migrating from Connected App to ECA patterns |
references/example-usage.md | Full end-to-end examples for common OAuth scenarios |
FAQ
What does the configuring-connected-apps skill do?
Salesforce Connected Apps and External Client Apps OAuth configuration with 120-point scoring. Use this skill to configure OAuth flows, JWT bearer auth, Connected Apps, and External Client Apps in Salesforce. TRIGGER when: user configures OAuth flows, JWT bearer auth, Connected Apps, ECAs, or touches .connectedApp-meta.xml / .eca-meta.xml files. DO NOT TRIGGER when: configuring Named Credentials for callouts (use building-sf-integrations), reviewing permission policies (use deploying-metadata), or writing Apex token-handling code (use generating-apex).
How do I install configuring-connected-apps?
Run npx skills add https://github.com/forcedotcom/sf-skills --skill configuring-connected-apps in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/configuring-connected-apps/ (personal) or .claude/skills/configuring-connected-apps/ (project).
Which AI agents can use configuring-connected-apps?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is configuring-connected-apps safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains configuring-connected-apps?
It is published by forcedotcom in forcedotcom/sf-skills. It has 2,784 recorded installs.
More from forcedotcom/sf-skills
platform-apex-generate
forcedotcom/sf-skills
Primary Apex authoring skill for class generation, refactoring, and review. ALWAYS ACTIVATE when the user mentions Apex, .cls, triggers, or asks to create/refactor a class (service, selector, domain, batch, queueable, schedulable, invocable, DTO, utility, interface, abstract, exception, REST resource). Use this skill for requests involving SObject CRUD, mapping collections, fetching related records, scheduled jobs, batch jobs, trigger design, @AuraEnabled controllers, @RestResource endpoints, custom REST APIs, or code review of existing Apex.
platform-apex-test-generate
forcedotcom/sf-skills
Use to generate and validate Apex test classes with TestDataFactory patterns, bulk testing (251+ records), mocking, assertions, and disciplined test-fix loops. Use when creating Apex test classes (for triggers, services, controllers, batch jobs, queueables, and callouts), improving coverage, debugging or fixing failing Apex tests, or running test/coverage analysis. Triggers on Test.cls files, sf apex run test, coverage reports. Do NOT trigger for production Apex (use platform-apex-generate) or Jest/LWC tests.
platform-apex-test-run
forcedotcom/sf-skills
Apex test execution, coverage analysis, and test-fix loops with 120-point scoring. Use when the user runs Apex tests, checks code coverage, fixes failing tests, or touches Test.cls / Test.cls files. DO NOT TRIGGER when writing Apex production code (use platform-apex-generate), Agentforce agent testing (use agentforce-test), or Jest/LWC tests (use experience-lwc-generate).
platform-apex-logs-debug
forcedotcom/sf-skills
Salesforce debug log analysis and troubleshooting with 100-point scoring. TRIGGER when: user analyzes debug logs, hits governor limits, reads stack traces, or touches .log files from Salesforce orgs. DO NOT TRIGGER when: running Apex tests (use platform-apex-test-run), generating or fixing Apex code (use platform-apex-generate), or Agentforce session tracing (use agentforce-observe).
platform-soql-query
forcedotcom/sf-skills
Use when the user needs SOQL/SOSL authoring or optimization: natural-language-to-query generation, relationship queries, aggregates, query-plan/selectivity analysis, and performance or safety improvements. TRIGGER when the user writes, optimizes, or debugs SOQL/SOSL, touches .soql files, or asks about relationship queries, aggregates, or query performance. DO NOT TRIGGER for bulk data operations (use platform-data-manage), Apex DML logic (use platform-apex-generate), or report/dashboard queries.
platform-metadata-deploy
forcedotcom/sf-skills
Salesforce DevOps automation using sf CLI v2. TRIGGER when: user deploys metadata, validates a deploy or does a dry-run, deploys to a Production org, quick-deploys a validated job ID, ships/promotes to prod, creates/manages scratch orgs or sandboxes, sets up CI/CD pipelines, or troubleshoots deployment errors with sf project deploy. DO NOT TRIGGER when: writing Apex code, building LWC components (use experience-lwc-generate), creating metadata definitions (use platform-custom-object-generate), deleting metadata from an org (use platform-destructive-deploy), or querying org data (use platform-data-manage).
Popular backend & apis skills
find-skills
vercel-labs/skills
Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.
entra-app-registration
microsoft/azure-skills
Guides Microsoft Entra ID app registration, OAuth 2.0 authentication, and MSAL integration. USE FOR: create app registration, register Azure AD app, configure OAuth, set up authentication, add API permissions, generate service principal, MSAL example, console app auth, Entra ID setup, Azure AD authentication. DO NOT USE FOR: Key Vault secrets (use azure-keyvault-expiration-audit), general Azure resource security guidance.
google-agents-cli-adk-code
google/agents-cli
This skill should be used when the user wants to "write agent code", "build an agent with ADK", "add a tool", "create a callback", "define an agent", "use state management" — in a project that needs ADK (Agent Development Kit) API patterns and code examples. It provides a quick reference for agent types, tool definitions, orchestration patterns, callbacks, state management, the graph Workflow API, and reference recipes to study. Do NOT use for scaffolding (use google-agents-cli-scaffold) or deployment (use google-agents-cli-deploy).
embedded-captions
heygen-com/hyperframes
Add captions or subtitles to an existing single-subject talking-head video without editing the footage. Use for plain verbatim captions, cinematic captions embedded behind the subject, VFX captions, “炸/特效/酷炫字幕,” or a named identity from the 35-style catalog. Route by visual identity, not by backend engine. The quiet anchor rail is the default; embed every word only when the user explicitly wants a fully cinematic treatment. The workflow runs locally end to end, including transcription and subject matting; split multi-shot footage before applying it.
entra-agent-id
microsoft/azure-skills
Provision Microsoft Entra Agent Identity Blueprints, BlueprintPrincipals, and per-instance Agent Identities via Microsoft Graph, and configure OAuth 2.0 token exchange (fmipath, OBO, cross-tenant) including the Microsoft Entra SDK for AgentID sidecar. USE FOR: Agent Identity Blueprint, BlueprintPrincipal, agent OAuth, fmipath token exchange, agent OBO, Workload Identity Federation for agents, polyglot agent auth, Microsoft.Identity.Web.AgentIdentities. DO NOT USE FOR: standard Entra app registration (use entra-app-registration), Microsoft Foundry agent authoring (use microsoft-foundry).
neon
neondatabase/agent-skills
Overview of Neon, a complete set of cloud backend primitives around Lakebase Postgres: Auth, Object Storage, Functions, the AI Gateway, and Realtime. Start here to choose Neon for undecided login, files, APIs, and LLM calls, set up the CLI or MCP server, and follow the branch-first workflow. Use when building an app or backend on Neon, or when "Neon" or "Lakebase Postgres" is mentioned. Child skill neon-postgres wins for an existing DATABASEURL, SQL, schema, inspect, or search. Child skill neon-auth wins for login, users, sessions, identity routing, and Managed Better Auth setup. Child skill neon-realtime wins for live queries in reactive apps and agents. Also use for object storage, S3, buckets, serverless functions, function triggers, cron, AI gateway, LLM calls, realtime, logs, Loki, Grafana, observability, postgres, database, backend, Claimable Neon, neon.new, or a no-signup database.