forcedotcom/sf-skills / plugins/builder/integration/skills/integration-connectivity-connected-app-configure
integration-connectivity-connected-app-configure
VerifiedSalesforce 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).
| File | Kind | Size |
|---|---|---|
| README.md | markdown | 2.9 KB |
| SKILL.md | skill md | 10.7 KB |
| assets/connected-app-basic.xml | config | 1.0 KB |
| assets/connected-app-canvas.xml | config | 2.1 KB |
| assets/connected-app-jwt.xml | config | 1.9 KB |
| assets/connected-app-oauth.xml | config | 2.3 KB |
| assets/eca-global-oauth.xml | config | 1.9 KB |
| assets/eca-oauth-settings.xml | config | 1.4 KB |
| assets/eca-policies.xml | config | 1.3 KB |
| assets/external-client-app.xml | config | 1.6 KB |
| references/example-usage.md | markdown | 8.5 KB |
| references/migration-guide.md | markdown | 8.5 KB |
| references/oauth-flows-reference.md | markdown | 18.0 KB |
| references/security-checklist.md | markdown | 5.8 KB |
| references/testing-validation-guide.md | markdown | 9.9 KB |
references/testing-validation-guide.md
View on GitHub<!-- Parent: integration-connectivity-connected-app-configure/SKILL.md -->
# Testing & Validation Guide
This guide documents tested External Client App (ECA) and Connected App patterns based on systematic validation testing (December 2025).
## Test Matrix
| Component Type | Template / Source | Test Status |
|----------------|-------------------|-------------|
| Connected App (Basic) | `connected-app-basic.xml` | ✅ Verified |
| Connected App (Full OAuth) | `connected-app-oauth.xml` | ✅ Verified |
| Connected App (JWT Bearer) | `connected-app-jwt.xml` | ✅ Verified |
| Connected App (Canvas) | `connected-app-canvas.xml` | ⚠️ Location-dependent |
| External Client App | `external-client-app.xml` | ✅ Verified |
| ECA Global OAuth | `eca-global-oauth.xml` | ✅ Verified |
| ECA OAuth Settings | `eca-oauth-settings.xml` | ✅ Verified |
| ECA OAuth Security Settings | retrieve-first (`ExtlClntAppOauthSecuritySettings`) | ✅ CLI/registry-supported |
| ECA Configurable Policies | `eca-policies.xml` | ✅ Naming updated |
---
## Critical File Naming Conventions
### External Client App Files
| Metadata Type | Source Directory | File Suffix | Example |
|--------------|------------------|-------------|---------|
| ExternalClientApplication | `externalClientApps/` | `.eca-meta.xml` | `externalClientApps/MyApp.eca-meta.xml` |
| ExtlClntAppOauthSettings | `extlClntAppOauthSettings/` | `.ecaOauth-meta.xml` | `extlClntAppOauthSettings/MyApp.ecaOauth-meta.xml` |
| ExtlClntAppGlobalOauthSettings | `extlClntAppGlobalOauthSets/` | `.ecaGlblOauth-meta.xml` | `extlClntAppGlobalOauthSets/MyApp.ecaGlblOauth-meta.xml` |
| ExtlClntAppOauthSecuritySettings | `extlClntAppOauthSecuritySettings/` | `.ecaOauthSecurity-meta.xml` | `extlClntAppOauthSecuritySettings/MyApp.ecaOauthSecurity-meta.xml` |
| ExtlClntAppOauthConfigurablePolicies | `extlClntAppOauthPolicies/` | `.ecaOauthPlcy-meta.xml` | `extlClntAppOauthPolicies/MyApp.ecaOauthPlcy-meta.xml` |
| ExtlClntAppConfigurablePolicies | `extlClntAppPolicies/` | `.ecaPlcy-meta.xml` | `extlClntAppPolicies/MyApp.ecaPlcy-meta.xml` |
⚠️ **CRITICAL**:
- Use `.ecaGlblOauth` (abbreviated), NOT `.ecaGlobalOauth`
- Use `.ecaPlcy`, NOT `.ecaPolicy`
- `ExtlClntAppOauthSecuritySettings` is now source-supported; prefer retrieve-first until you have an org-validated sample file
### Connected App Files
| Metadata Type | File Suffix | Example |
|--------------|-------------|---------|
| ConnectedApp | `.connectedApp-meta.xml` | `MyApp.connectedApp-meta.xml` |
---
## Common Deployment Errors & Solutions
### Error: "Invalid or missing field" in ECA OAuth Settings
**Cause**: Using wrong schema with non-existent fields
**Wrong Schema (FAILS):**
```xml
<ExtlClntAppOauthSettings>
<isAdminApproved>true</isAdminApproved> <!-- DOES NOT EXIST -->
<isCodeCredentialsEnabled>true</isCodeCredentialsEnabled> <!-- DOES NOT EXIST -->
<scopes>Api</scopes> <!-- WRONG FORMAT -->
</ExtlClntAppOauthSettings>
```
**Correct Schema:**
```xml
<ExtlClntAppOauthSettings xmlns="http://soap.sforce.com/2006/04/metadata">
<commaSeparatedOauthScopes>Api, RefreshToken</commaSeparatedOauthScopes>
<externalClientApplication>MyApp</externalClientApplication>
<label>MyApp OAuth Settings</label>
</ExtlClntAppOauthSettings>
```
### Error: "Missing required field" in ECA Global OAuth
**Cause**: Missing `externalClientApplication` or `label`
**Wrong (FAILS):**
```xml
<ExtlClntAppGlobalOauthSettings>
<callbackUrl>https://example.com/callback</callbackUrl>
<isPkceRequired>true</isPkceRequired>
</ExtlClntAppGlobalOauthSettings>
```
**Correct:**
```xml
<ExtlClntAppGlobalOauthSettings xmlns="http://soap.sforce.com/2006/04/metadata">
<callbackUrl>https://example.com/callback</callbackUrl>
<externalClientApplication>MyApp</externalClientApplication>
<isConsumerSecretOptional>true</isConsumerSecretOptional>
<isIntrospectAllTokens>false</isIntrospectAllTokens>
<isPkceRequired>true</isPkceRequired>
<isSecretRequiredForRefreshToken>false</isSecretRequiredForRefreshToken>
<label>MyApp Global OAuth</label>
<shouldRotateConsumerKey>false</shouldRotateConsumerKey>
<shouldRotateConsumerSecret>false</shouldRotateConsumerSecret>
</ExtlClntAppGlobalOauthSettings>
```
### Error: "Organization is not configured to support location"
**Cause**: Canvas app using location that requires org feature enablement
**Problematic Locations:**
- `AppLauncher` - Requires feature enablement
- Some other locations may have similar requirements
**Solution**: Use universally available locations:
```xml
<canvasApp>
<locations>Visualforce</locations>
</canvasApp>
```
### Error: Certificate not found (JWT Bearer)
**Cause**: Referenced certificate doesn't exist in org
**Wrong:**
```xml
<certificate>NonExistent_Cert</certificate>
```
**Solution**: Create certificate first, then reference it:
```bash
# 1. Create certificate in org (Setup > Certificate and Key Management)
# 2. Reference in Connected App
<certificate>My_JWT_Cert</certificate>
```
---
## Field Reference
### ExtlClntAppOauthSettings (ECA OAuth)
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `commaSeparatedOauthScopes` | String | Yes | Comma-separated scopes (e.g., "Api, RefreshToken") |
| `externalClientApplication` | String | Yes | Reference to parent ECA API name |
| `label` | String | Yes | Display label |
**Available Scopes:**
- `Api` - REST/SOAP API access
- `RefreshToken` - Offline access
- `OpenID` - OpenID Connect
- `Profile` - User profile info
- `Email` - User email
- `Web` - Web browser access
- `ChatterApi` - Chatter REST API
### ExtlClntAppGlobalOauthSettings (ECA Global OAuth)
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `callbackUrl` | URL | Yes | OAuth redirect URI |
| `externalClientApplication` | String | Yes | Reference to parent ECA |
| `isConsumerSecretOptional` | Boolean | No | True for public clients with PKCE |
| `isIntrospectAllTokens` | Boolean | No | Enable token introspection |
| `isPkceRequired` | Boolean | No | Require PKCE (recommended for public clients) |
| `isSecretRequiredForRefreshToken` | Boolean | No | Require secret for refresh |
| `label` | String | Yes | Display label |
| `shouldRotateConsumerKey` | Boolean | No | Enable key rotation |
| `shouldRotateConsumerSecret` | Boolean | No | Enable secret rotation |
---
## Deployment Order
For External Client Apps, deploy in this order:
```bash
# 1. Deploy base ECA first
sf project deploy start --metadata ExternalClientApplication:MyApp --target-org [alias]
# 2. Deploy OAuth settings
sf project deploy start --metadata ExtlClntAppOauthSettings:MyApp --target-org [alias]
# 3. Deploy Global OAuth (if needed)
sf project deploy start --metadata ExtlClntAppGlobalOauthSettings:MyApp --target-org [alias]
# 4. Deploy companion security/policy metadata when you use it
sf project deploy start --metadata ExtlClntAppOauthSecuritySettings:MyApp --target-org [alias]
sf project deploy start --metadata ExtlClntAppOauthConfigurablePolicies:MyApp --target-org [alias]
sf project deploy start --metadata ExtlClntAppConfigurablePolicies:MyApp --target-org [alias]
# Or deploy the whole package directory when all ECA source directories live under it
sf project deploy start --source-dir force-app/main/default --target-org [alias]
```
---
## Post-Deployment Steps
### Client Credentials Flow (ECA)
Client Credentials flow still requires post-deployment admin validation. Even with broader metadata support, verify these items in Setup after deployment:
1. **Create Permission Set** with "Salesforce API Integration" permission
2. **Assign Permission Set** to the External Client App
3. **Confirm the run-as / execution-user behavior and any org-specific OAuth security settings**
### JWT Bearer Flow (Connected App)
1. **Upload Certificate** to org before deployment
2. **Pre-authorize Users** after deployment (Setup > Manage Connected Apps)
---
## Deployment Checklist
### External Client App
- [ ] `.eca-meta.xml` file exists under `externalClientApps/`
- [ ] `.ecaOauth-meta.xml` file exists under `extlClntAppOauthSettings/`
- [ ] `.ecaGlblOauth-meta.xml` uses abbreviated suffix under `extlClntAppGlobalOauthSets/`
- [ ] Optional companion files use the right suffixes: `.ecaOauthSecurity`, `.ecaOauthPlcy`, `.ecaPlcy`
- [ ] All companion files reference the same `externalClientApplication` name
- [ ] Required files include `label` where applicable
- [ ] `commaSeparatedOauthScopes` uses string format, not individual `<scopes>` tags
- [ ] Callback URL is HTTPS (or custom scheme for mobile)
- [ ] PKCE enabled for public clients
### Connected App
- [ ] `.connectedApp-meta.xml` file exists
- [ ] `contactEmail` is valid
- [ ] Callback URL matches OAuth flow requirements
- [ ] Certificate exists in org (for JWT Bearer)
- [ ] Canvas locations are supported by org (if using Canvas)
---
## Tested Configurations
### Minimal ECA (API Integration)
```text
Files:
├── externalClientApps/MyApp.eca-meta.xml
├── extlClntAppOauthSettings/MyApp.ecaOauth-meta.xml
└── extlClntAppGlobalOauthSets/MyApp.ecaGlblOauth-meta.xml
Scopes: Api, RefreshToken
PKCE: false (confidential client)
```
### Mobile App ECA (PKCE)
```text
Files:
├── externalClientApps/MobileApp.eca-meta.xml
├── extlClntAppOauthSettings/MobileApp.ecaOauth-meta.xml
└── extlClntAppGlobalOauthSets/MobileApp.ecaGlblOauth-meta.xml
Scopes: Api, RefreshToken, OpenID
PKCE: true (public client)
Callback: com.example.app://oauth/callback
```
### Server-to-Server ECA
```text
Files:
├── externalClientApps/ServiceApp.eca-meta.xml
├── extlClntAppOauthSettings/ServiceApp.ecaOauth-meta.xml
└── extlClntAppOauthSecuritySettings/ServiceApp.ecaOauthSecurity-meta.xml # retrieve-first when source controlling OAuth security settings
Scopes: Api
Note: Client Credentials still requires post-deployment Permission Set assignment and admin verification
```
---
*Last Updated: April 2026*
*Based on testing with SF CLI and API v66.0*
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |