sf-connected-apps: Salesforce Connected Apps & External Client Apps

Expert in creating and managing Salesforce Connected Apps and External Client Apps (ECAs) with OAuth configuration, security best practices, and metadata compliance.

Core Responsibilities

1. Connected App Generation: Create Connected Apps with OAuth 2.0 configuration, scopes, and callbacks
2. External Client App Generation: Create ECAs with modern security model and separation of concerns
3. Security Review: Analyze OAuth configurations for security best practices
4. Validation & Scoring: Score apps against 6 categories (0-120 points)
5. Migration Guidance: Help migrate from Connected Apps to External Client Apps

Workflow (5-Phase Pattern)

Phase 1: Requirements Gathering

Ask the user to gather:

Then:

1. Check existing: Glob: **/*.connectedApp-meta.xml, Glob: **/*.eca-meta.xml
2. Create a task list

Phase 2: App Type Selection

Quick Decision:

• Multi-org or ISV → External Client App
• Regulated industry → External Client App (audit requirements)
• Simple single-org → Connected App sufficient
• Automated DevOps → External Client App (key rotation)

Phase 3: Template Selection & Generation

Template Locations (try in order):

1. ~/.claude/plugins/marketplaces/sf-skills/sf-connected-apps/assets/[template]
2. [project-root]/sf-connected-apps/assets/[template]

Template Selection:

Output Locations:

• Connected Apps: force-app/main/default/connectedApps/
• External Client Apps: force-app/main/default/externalClientApps/

Phase 4: Security Validation & Scoring

Scoring Categories:

Score: XX/120 ⭐⭐⭐⭐
├─ Security: XX/30 (PKCE, token rotation, IP restrictions, certificates)
├─ OAuth Config: XX/25 (callbacks, flows, token expiration, OIDC)
├─ Metadata: XX/20 (required fields, API version, naming)
├─ Best Practices: XX/20 (minimal scopes, named principal, pre-auth)
├─ Scopes: XX/15 (least privilege, no deprecated)
└─ Documentation: XX/10 (description, contact email)

Thresholds:

📋 Detailed scoring: See Phase 4 in previous version for point breakdown per criteria.

Phase 5: Deployment & Documentation

Deploy:

Use the **sf-deploy** skill: "Deploy connected apps to [target-org] with --dry-run"

Completion Output:

✓ App Created: [AppName]
  Type: [Connected App | External Client App]
  Location: force-app/main/default/[connectedApps|externalClientApps]/
  OAuth Flow: [flow]
  Scopes: [list]
  Score: XX/120

Next Steps:
- Retrieve Consumer Key from Setup > App Manager
- Test OAuth flow (Postman/curl)
- For ECA: Configure policies in subscriber org

Quick Reference: OAuth Flow Selection

📘 Detailed flows: See references/oauth-flows-reference.md for implementation patterns, security checklists, and code examples.

Metadata Structure Essentials

Connected App XML

<?xml version="1.0" encoding="UTF-8"?>
<ConnectedApp xmlns="http://soap.sforce.com/2006/04/metadata">
    <label>My Integration App</label>
    <contactEmail>[email protected]</contactEmail>
    <description>Integration description</description>

    <!-- OAuth Configuration -->
    <oauthConfig>
        <callbackUrl>https://app.example.com/oauth/callback</callbackUrl>
        <certificate>MyCertificate</certificate> <!-- JWT Bearer only -->
        <scopes>Api</scopes>
        <scopes>RefreshToken</scopes>
        <isAdminApproved>true</isAdminApproved>
        <isConsumerSecretOptional>false</isConsumerSecretOptional>
        <isPkceRequired>true</isPkceRequired> <!-- Public clients -->
    </oauthConfig>

    <!-- OAuth Policy -->
    <oauthPolicy>
        <ipRelaxation>ENFORCE</ipRelaxation>
        <refreshTokenPolicy>infinite</refreshTokenPolicy>
        <isRefreshTokenRotationEnabled>true</isRefreshTokenRotationEnabled>
    </oauthPolicy>
</ConnectedApp>

External Client App Files

1. Header File ([AppName].eca-meta.xml):

<ExternalClientApplication xmlns="http://soap.sforce.com/2006/04/metadata">
    <label>My External Client App</label>
    <contactEmail>[email protected]</contactEmail>
    <description>Modern integration</description>
    <distributionState>Local</distributionState> <!-- or Packageable -->
</ExternalClientApplication>

2. Global OAuth ([AppName].ecaGlblOauth-meta.xml):

<ExtlClntAppGlobalOauthSettings xmlns="http://soap.sforce.com/2006/04/metadata">
    <callbackUrl>https://app.example.com/oauth/callback</callbackUrl>
    <externalClientApplication>My_App_Name</externalClientApplication>
    <label>Global OAuth Settings</label>
    <isPkceRequired>true</isPkceRequired>
    <isConsumerSecretOptional>true</isConsumerSecretOptional>
</ExtlClntAppGlobalOauthSettings>

⚠️ Important: File suffix is .ecaGlblOauth (abbreviated), NOT .ecaGlobalOauth

3. Instance OAuth ([AppName].ecaOauth-meta.xml):

<ExtlClntAppOauthSettings xmlns="http://soap.sforce.com/2006/04/metadata">
    <externalClientApplication>My_App_Name</externalClientApplication>
    <commaSeparatedOauthScopes>api,refresh_token</commaSeparatedOauthScopes>
    <label>Instance OAuth Settings</label>
    <isClientCredentialsEnabled>false</isClientCredentialsEnabled>
</ExtlClntAppOauthSettings>

OAuth Scopes Reference

Security Best Practices

🔒 Security details: See references/security-checklist.md for comprehensive security review.

Scratch Org Setup (External Client Apps)

{
  "orgName": "ECA Development Org",
  "edition": "Developer",
  "features": [
    "ExternalClientApps",
    "ExtlClntAppSecretExposeCtl"
  ]
}

Common CLI Commands

# List Connected Apps in org
sf org list metadata --metadata-type ConnectedApp --target-org [alias]

# Retrieve Connected App
sf project retrieve start --metadata ConnectedApp:[AppName] --target-org [alias]

# Deploy
sf project deploy start --source-dir force-app/main/default/connectedApps --target-org [alias]

# Retrieve Consumer Key (after deployment)
# Go to Setup > App Manager > [App] > View

Migration: Connected App → External Client App

Quick Steps:

1. Assess: Glob: **/*.connectedApp-meta.xml
2. Create: Map OAuth settings to ECA structure
3. Parallel: Deploy ECA alongside old app
4. Test: Verify flows with new Consumer Key
5. Cutover: Update integrations, disable old app
6. Archive: Remove after 30-day grace period

Scoring Benefit: ECAs typically score 15-20 points higher.

📘 Detailed migration: See references/migration-guide.md for step-by-step process.

Cross-Skill Integration

Key Insights

Notes

• API Version: 62.0+ recommended, 61.0+ required for External Client Apps
• Scoring: Block deployment if score < 54 (54% threshold)
• Consumer Secret: Never commit to version control - use environment variables
• External Client Apps: Preferred for new development (modern security model)
• Testing: Use Postman for OAuth flow testing before production

Additional Resources

Detailed References

• OAuth Flow Patterns: references/oauth-flows-reference.md
  • Implementation examples (Node.js, Python, JavaScript)
  • Security checklists per flow
  • Error handling patterns
  • Named Credentials integration

Documentation

• OAuth Flow Diagrams: references/oauth-flows.md
• Security Review: references/security-checklist.md
• Migration Guide: references/migration-guide.md
• Testing & Validation: references/testing-validation-guide.md

Examples

• Usage Examples: references/example-usage.md

License

MIT License. See LICENSE file. Copyright (c) 2024-2025 Jag Valaiyapathy