/integration-connectivity-connected-app-configure

name: integration-connectivity-connected-app-configure
description: "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)."
allowed-tools: Bash Read Write Edit Glob Grep WebFetch AskUserQuestion TodoWrite
metadata:
  version: "1.1"
  domains: ["Integration"]
  minApiVersion: "57.0"
  relatedSkills:
    - "integration-connectivity-generate"
    - "platform-apex-generate"
    - "platform-metadata-deploy"
  cliTools:
    - tool: ["curl"]
      semver: ">=7.0.0"
    - tool: ["jq"]
      semver: ">=1.7.0"
    - tool: ["openssl"]
      semver: ">=1.1.0"
    - tool: ["python3"]
      semver: ">=3.10.0"
    - tool: ["sf"]
      semver: ">=2.0.0"

integration-connectivity-connected-app-configure: 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.xml` or `.eca-meta.xml` files
• 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 → [integration-connectivity-generate](../integration-connectivity-generate/SKILL.md)
• Deploying metadata to orgs → the `platform-metadata-deploy` skill
• Writing Apex token-handling code → the `platform-apex-generate` skill

---

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 instead
• `INVALID_CROSS_REFERENCE_KEY` — the `externalClientApplication` name in an ECA settings file doesn't match the `.eca-meta.xml` filename exactly
• `INSUFFICIENT_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