integration-connectivity-connected-app-configure
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 integration-connectivity-generate), reviewing permission policies (use platform-metadata-deploy), or writing Apex token-handling code (use platform-apex-generate).
Full skill instructions
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.
In scope:
.connectedApp-meta.xml or .eca-meta.xml filesOut of scope — delegate elsewhere:
platform-metadata-deploy skillplatform-apex-generate skill| 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:
Ask for or infer:
Decide whether a Connected App or ECA is the better long-term fit using the decision table above.
| 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) |
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>
Read references/security-checklist.md for the full 120-point security checklist. Favor:
Read references/testing-validation-guide.md before handoff. Confirm:
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 — the externalClientApplication name in an ECA settings file doesn't match the .eca-meta.xml filename exactlyINSUFFICIENT_ACCESS_OR_READONLY — user lacks the "Manage Connected Apps" permission| 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 |
Default source location (verify via sfdx-project.json → packageDirectories):
<packageDir>/connectedApps/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 |
| 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 |
When finishing, confirm and report in this order:
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
| Need | Delegate to | Reason |
|---|---|---|
| Named Credential / callout runtime config | integration-connectivity-generate | runtime integration setup |
| Deploy app metadata | platform-metadata-deploy skill | org validation and deployment |
| Apex token or refresh handling | platform-apex-generate skill | implementation logic |
| Score | Meaning |
|---|---|
| 80+ | production-ready OAuth app config |
| 54–79 | workable but needs hardening review |
| < 54 | block deployment until fixed |
| 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 |
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).
SOQL query generation, optimization, and analysis with 100-point scoring. Use this skill when the user needs SOQL/SOSL authoring or optimization: natural-language-to-query generation, relationship queries, aggregates, query-plan analysis, and performance or safety improvements for Salesforce queries. TRIGGER when: user writes, optimizes, or debugs SOQL/SOSL queries, touches .soql files, or asks about relationship queries, aggregates, or query performance. DO NOT TRIGGER when: bulk data operations (use platform-data-manage), Apex DML logic (use platform-apex-generate), or report/dashboard queries.
Salesforce DevOps automation using sf CLI v2. TRIGGER when: user deploys metadata, 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 (use platform-apex-generate), building LWC components (use experience-lwc-generate), creating metadata definitions (use platform-custom-object-generate or platform-custom-field-generate), or querying org data (use platform-data-manage).
ALWAYS USE THIS SKILL to retrieve metadata from an org to your local project using the sf project retrieve start command. Supports multiple retrieval modes: retrieve all remote changes, retrieve by source directory, retrieve by metadata type with wildcards, retrieve by manifest (package.xml), or retrieve by package name. Use when the user asks to retrieve, pull, sync, or download metadata, Apex classes, custom objects, or org changes. Supports source format (default) or metadata format (ZIP). DO NOT TRIGGER for deploying metadata (use platform-metadata-deploy skill), listing metadata, or generating package.xml. NEVER use MCP tools - always use this skill and the Bash tool with sf project retrieve start.
Use this skill when users need to create, generate, or validate Salesforce Custom Field metadata. Trigger when users mention custom fields, field types, Roll-up Summary fields, Master-Detail relationships, Lookup relationships, formula fields, picklists, dependent (controlling) picklists, referencing a value set from a field, or scoping/limiting picklist values for a specific record type. Also use when users encounter field deployment errors, especially around Roll-up Summary format, Master-Detail constraints, formula issues, or a record type that won't deploy without a business process. Use this skill for custom field metadata work, field generation, and field troubleshooting. DO NOT TRIGGER for creating or customizing the value set itself — defining a new GlobalValueSet, or modifying a StandardValueSet catalog like Industry or Lead Source — use platform-value-set-generate instead; this skill covers the field that references a value set, not the value set definition.
Generates correct, deployable Salesforce permission set metadata (PermissionSet XML) with object, field, user, and app permissions. Use this skill when creating or editing permission set metadata, object permissions, field-level security (FLS), tab visibility, or deploying permission sets.
Run Salesforce Code Analyzer to scan code for security, performance, best practice, and code style violations. Supports all engines (PMD, ESLint, CPD, RetireJS, Flow, SFGE, ApexGuru), targets (files, folders, git diff), categories, and severities. Also handles post-scan exploration: filtering results by engine/severity/category/file, and explaining what rules mean. TRIGGER when: user says 'scan my code', 'check security issues', 'run PMD/ESLint', 'find duplicates', 'analyze Flows', 'check vulnerable libraries', 'AppExchange review', 'lint my LWC', 'static analysis', 'code quality', 'show security violations', 'what is this rule', 'explain ApexCRUDViolation', 'filter results', or mentions engines/file types (.cls, .trigger, .js, .flow-meta.xml). Use this skill for scanning, exploring results, and listing rules. DO NOT TRIGGER when: user asks only about installation/configuration (use dx-code-analyzer-configure), or wants to create a custom rule (use dx-code-analyzer-custom-rule-create).
Generate Salesforce Flows using the MCP tool execute_metadata_action. Use when the user asks to create, build, or generate a flow — including Screen, Autolaunched, Record-Triggered (before/after-save), Scheduled. Also trigger for flow-like requests such as "when a record is created", "trigger daily at", "send an email when", "update the field when", "automate", "workflow", or "flow XML/metadata". This is the only skill for Salesforce Flow generation.
Use this skill when users need to create, generate, or validate Salesforce Custom Object metadata. Trigger when users mention custom objects, creating objects, object metadata, .object files, sharing models, name fields, or validation rules on objects. Also use when users say things like "create a custom object", "generate object metadata", "set up an object for...", or when they're troubleshooting object deployment errors especially around sharing models and Master-Detail relationships. Always use this skill for any custom object metadata work, including enriching and keeping the object's description current whenever its fields or validation rules change. Do NOT use this skill for non-Custom-Object metadata (Apex, Flows, LWC, Permission Sets, Custom Metadata Types) or for standard Salesforce objects.
Salesforce data operations with 130-point scoring. Use this skill to create, update, delete, bulk import/export, generate test data, and clean up org records using sf CLI and anonymous Apex. TRIGGER when: user creates test data, performs bulk import/export, uses sf data CLI commands, needs data factory patterns for Apex tests, or needs to seed/clean records in a Salesforce org. DO NOT TRIGGER when: SOQL query writing only (use platform-soql-query), Apex test execution (use platform-apex-test-run), or metadata deployment (use platform-metadata-deploy).
Lightning Web Components with PICKLES methodology and 165-point scoring. Use this skill when the user creates or edits LWC components, builds wire service patterns, or writes Jest tests for LWC. TRIGGER when: user creates/edits LWC components, touches lwc/**/*.js, .html, .css, .js-meta.xml files, or asks about wire service, SLDS, or Jest LWC tests. DO NOT TRIGGER when: Apex classes (use platform-apex-generate), Aura components, or Visualforce.
Apply SLDS-compliant UI using the correct blueprints, styling hooks, utility classes, and icons. Use when building any UI that needs SLDS, choosing between Lightning Base Components and SLDS Blueprints, applying styling hooks for theming, using utility classes for layout and spacing, or selecting icons. Triggers include "build a modal", "create a form", "data table", "SLDS styling", "style with hooks", "add an icon".
Generate, edit, and beat-sync AI video with leading models in one workspace.
The world's fastest calendar for remote work
Transform Your Design with AI Designer by ImgCreator.ai
Revolutionizing Video Production with AI-Powered Creativity
Extend an image past the frame and let AI fill the new aspect ratio.
Discover your celebrity doppelgänger with StarByFace!
ChainClarity explains 700+ crypto whitepapers in plain English, with layered summaries, comparisons, research tools, alerts, and a $4.99 Pro plan.
Opus.ai: Revolutionize Your Web Experience