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/migration-guide.md
View on GitHub<!-- Parent: integration-connectivity-connected-app-configure/SKILL.md -->
# Migration Guide: Connected App → External Client App
Step-by-step guide for migrating from Connected Apps to External Client Apps (ECAs).
## Why Migrate?
| Feature | Connected App | External Client App |
|---------|--------------|---------------------|
| Metadata Compliance | Partial | Full |
| Secret in Sandboxes | Visible | Hidden |
| Key Rotation | Manual | Automated via API |
| Multi-Org Distribution | Manual recreation | Native 2GP packaging |
| Audit Logging | Limited | MFA + full audit |
| Security Model | Open by default | Closed by default |
**Migrate when**:
- Distributing to multiple orgs (ISV, enterprise)
- Compliance requires audit trails
- DevOps needs automated credential rotation
- Moving to 2GP packaging
---
## Migration Process
### Phase 1: Assessment
#### 1.1 Inventory Current Apps
```bash
# List all Connected Apps
sf org list metadata --metadata-type ConnectedApp --target-org <org>
# Retrieve for analysis
sf project retrieve start --metadata ConnectedApp --output-dir ./migration-review
```
#### 1.2 Document Configuration
For each Connected App, record:
| Setting | Value |
|---------|-------|
| App Name | |
| Consumer Key | |
| OAuth Scopes | |
| Callback URLs | |
| IP Restrictions | |
| Token Policy | |
| Certificate (if JWT) | |
#### 1.3 Identify Integrations
List all systems using each Connected App:
- External applications
- CI/CD pipelines
- Third-party tools
- Mobile applications
---
### Phase 2: Planning
#### 2.1 Choose Distribution Model
| Scenario | Distribution State |
|----------|-------------------|
| Single org only | `Local` |
| Multiple orgs, same company | `Local` per org or `Packageable` |
| ISV/AppExchange | `Packageable` |
#### 2.2 Plan Credential Rollover
```text
Timeline Example:
Week 1: Create ECA, deploy to DevHub
Week 2: Update integration systems with new credentials
Week 3: Test in sandbox environments
Week 4: Production cutover
Week 5-8: Monitor, keep old app active as fallback
Week 9: Deactivate Connected App
Week 12: Delete Connected App
```
---
### Phase 3: Create External Client App
#### 3.1 Prepare Scratch Org (if needed)
```json
// config/project-scratch-def.json
{
"orgName": "ECA Migration Dev",
"edition": "Developer",
"features": [
"ExternalClientApps",
"ExtlClntAppSecretExposeCtl"
]
}
```
#### 3.2 Create ECA Metadata Files
**File 1: Header** (`MyApp.eca-meta.xml`)
```xml
<?xml version="1.0" encoding="UTF-8"?>
<ExternalClientApplication xmlns="http://soap.sforce.com/2006/04/metadata">
<contactEmail>team@company.com</contactEmail>
<description>Migrated from Connected App: MyConnectedApp</description>
<distributionState>Local</distributionState>
<isProtected>false</isProtected>
<label>MyApp</label>
</ExternalClientApplication>
```
**File 2: Global OAuth** (`MyApp.ecaGlblOauth-meta.xml`)
```xml
<?xml version="1.0" encoding="UTF-8"?>
<ExtlClntAppGlobalOauthSettings xmlns="http://soap.sforce.com/2006/04/metadata">
<callbackUrl>https://app.example.com/oauth/callback</callbackUrl>
<externalClientApplication>MyApp</externalClientApplication>
<isConsumerSecretOptional>false</isConsumerSecretOptional>
<isPkceRequired>true</isPkceRequired>
<label>MyApp Global OAuth</label>
<shouldRotateConsumerKey>true</shouldRotateConsumerKey>
<shouldRotateConsumerSecret>true</shouldRotateConsumerSecret>
</ExtlClntAppGlobalOauthSettings>
```
**File 3: OAuth Settings** (`MyApp.ecaOauth-meta.xml`)
```xml
<?xml version="1.0" encoding="UTF-8"?>
<ExtlClntAppOauthSettings xmlns="http://soap.sforce.com/2006/04/metadata">
<commaSeparatedOauthScopes>Api, RefreshToken</commaSeparatedOauthScopes>
<externalClientApplication>MyApp</externalClientApplication>
<label>MyApp OAuth Settings</label>
</ExtlClntAppOauthSettings>
```
**Optional companion metadata (retrieve-first):** `MyApp.ecaOauthSecurity-meta.xml`
- Use this when you need to source-control ECA OAuth security settings now supported by the CLI/SDR registry.
- Recommended workflow: retrieve from an org first, then commit the retrieved file under `extlClntAppOauthSecuritySettings/`.
#### 3.3 Deploy to DevHub/Org
```bash
sf project deploy start \
--metadata ExternalClientApplication:MyApp \
--metadata ExtlClntAppGlobalOauthSettings:MyApp \
--metadata ExtlClntAppOauthSettings:MyApp \
--target-org <target-org>
```
#### 3.4 Retrieve New Consumer Key
After deployment:
1. Go to Setup → External Client App Manager
2. Select your ECA
3. View Consumer Key (MFA required)
4. Securely store credentials
---
### Phase 4: Update Integrations
#### 4.1 Update External Systems
For each integrated system:
1. Update OAuth endpoint (if different environment)
2. Replace Consumer Key
3. Replace Consumer Secret
4. Test authentication flow
5. Verify API access
#### 4.2 Configuration Mapping
| Connected App Setting | ECA Equivalent |
|----------------------|----------------|
| Consumer Key | New Consumer Key (different) |
| Consumer Secret | New Consumer Secret (different) |
| Callback URL | Same (in `ecaGlblOauth`) |
| Scopes | Same (in `ecaOauth`) |
| IP Relaxation | In `ecaPlcy` (admin-managed) |
| Refresh Token Policy | In `ecaPlcy` (admin-managed) |
| OAuth security controls | In `ecaOauthSecurity` when source-controlled (retrieve-first) |
---
### Phase 5: Testing
#### 5.1 Test Checklist
- [ ] Authorization Code flow works
- [ ] Token refresh works
- [ ] API calls succeed
- [ ] Scopes are correct
- [ ] Error handling works
- [ ] Logout/revocation works
#### 5.2 Test Script
```bash
# Test Authorization Code Flow
curl "https://login.salesforce.com/services/oauth2/authorize?\
response_type=code&\
client_id=<NEW_CONSUMER_KEY>&\
redirect_uri=<CALLBACK_URL>&\
scope=api%20refresh_token"
# Test Token Exchange
curl -X POST https://login.salesforce.com/services/oauth2/token \
-d "grant_type=authorization_code" \
-d "code=<AUTH_CODE>" \
-d "client_id=<NEW_CONSUMER_KEY>" \
-d "client_secret=<NEW_CONSUMER_SECRET>" \
-d "redirect_uri=<CALLBACK_URL>"
```
---
### Phase 6: Cutover
#### 6.1 Production Deployment
```bash
# Deploy ECA to production
sf project deploy start \
--metadata ExternalClientApplication:MyApp \
--metadata ExtlClntAppGlobalOauthSettings:MyApp \
--metadata ExtlClntAppOauthSettings:MyApp \
--target-org production
```
#### 6.2 Cutover Steps
1. Deploy ECA to production
2. Configure policies in Setup
3. Update production integrations
4. Monitor for errors
5. Keep Connected App active as fallback
---
### Phase 7: Decommission
#### 7.1 Deactivate Connected App
1. Go to Setup → Connected Apps → Manage Connected Apps
2. Select the old Connected App
3. Click "Edit Policies"
4. Set "Permitted Users" to "Admin approved users are pre-authorized"
5. Remove all user/profile assignments
#### 7.2 Monitor Period
- Monitor for 30 days minimum
- Check for authentication failures
- Investigate any traffic to old app
#### 7.3 Delete Connected App
After monitoring period:
```bash
# Remove from source control
rm force-app/main/default/connectedApps/OldApp.connectedApp-meta.xml
# Or delete via Setup UI
```
---
## Rollback Plan
If migration fails:
1. **Immediate**: Revert external systems to old Consumer Key
2. **Short-term**: Keep Connected App active during transition
3. **Long-term**: Document issues and retry migration
---
## Common Issues
| Issue | Cause | Solution |
|-------|-------|----------|
| "Invalid consumer key" | Using old key | Update to new ECA key |
| "Callback URL mismatch" | URL not in ECA config | Add URL to `ecaGlblOauth` |
| "Scope not allowed" | Scope not in `ecaOauth` | Add required scope |
| "User not authorized" | No policy assignment | Assign user via Permission Set |
| "MFA required" | ECA security | Complete MFA challenge |
---
## Automation Script
```bash
#!/bin/bash
# migrate-connected-app.sh
APP_NAME=$1
TARGET_ORG=$2
echo "📦 Migrating Connected App: $APP_NAME"
# 1. Retrieve existing Connected App
sf project retrieve start \
--metadata "ConnectedApp:$APP_NAME" \
--target-org $TARGET_ORG \
--output-dir ./migration
# 2. Create ECA source directories
mkdir -p force-app/main/default/externalClientApps
mkdir -p force-app/main/default/extlClntAppGlobalOauthSets
mkdir -p force-app/main/default/extlClntAppOauthSettings
# Optional when you source-control security settings:
mkdir -p force-app/main/default/extlClntAppOauthSecuritySettings
# 3. Deploy ECA (assumes files are created)
sf project deploy start \
--source-dir force-app/main/default \
--target-org $TARGET_ORG
echo "✅ ECA deployed. Retrieve new Consumer Key from Setup."
```
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 |