@salesforce/afv-skills 1.8.0 → 1.9.0

package/skills/configuring-connected-apps/references/example-usage.md

@@ -0,0 +1,256 @@
+<!-- Parent: configuring-connected-apps/SKILL.md -->
+# configuring-connected-apps Examples
+
+Real-world examples of using the configuring-connected-apps skill.
+
+## Example 1: Create a Basic API Integration Connected App
+
+**Request**:
+```
+Use the configuring-connected-apps skill to create a Connected App named "DataSyncIntegration"
+for syncing data with our external ERP system. It needs API access and refresh tokens.
+Contact email: admin@company.com
+```
+
+**Generated Output**:
+- `force-app/main/default/connectedApps/DataSyncIntegration.connectedApp-meta.xml`
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<ConnectedApp xmlns="http://soap.sforce.com/2006/04/metadata">
+    <label>DataSyncIntegration</label>
+    <contactEmail>admin@company.com</contactEmail>
+    <description>Data synchronization with external ERP system</description>
+    <oauthConfig>
+        <callbackUrl>https://erp.company.com/oauth/callback</callbackUrl>
+        <isAdminApproved>true</isAdminApproved>
+        <isConsumerSecretOptional>false</isConsumerSecretOptional>
+        <scopes>Api</scopes>
+        <scopes>RefreshToken</scopes>
+    </oauthConfig>
+    <oauthPolicy>
+        <ipRelaxation>ENFORCE</ipRelaxation>
+        <refreshTokenPolicy>infinite</refreshTokenPolicy>
+    </oauthPolicy>
+</ConnectedApp>
+```
+
+**Score**: 95/120 ⭐⭐⭐⭐
+
+---
+
+## Example 2: Create a JWT Bearer App for CI/CD
+
+**Request**:
+```
+Create a Connected App for our CI/CD pipeline using JWT Bearer flow.
+Name it "GitHubActionsDeployment" and use certificate "GH_Actions_Cert".
+```
+
+**Generated Output**:
+- `force-app/main/default/connectedApps/GitHubActionsDeployment.connectedApp-meta.xml`
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<ConnectedApp xmlns="http://soap.sforce.com/2006/04/metadata">
+    <label>GitHubActionsDeployment</label>
+    <contactEmail>devops@company.com</contactEmail>
+    <description>CI/CD deployment via GitHub Actions - JWT Bearer flow</description>
+    <oauthConfig>
+        <callbackUrl>https://localhost/oauth/callback</callbackUrl>
+        <certificate>GH_Actions_Cert</certificate>
+        <isAdminApproved>true</isAdminApproved>
+        <isConsumerSecretOptional>true</isConsumerSecretOptional>
+        <scopes>Api</scopes>
+    </oauthConfig>
+    <oauthPolicy>
+        <ipRelaxation>ENFORCE</ipRelaxation>
+        <refreshTokenPolicy>zero</refreshTokenPolicy>
+    </oauthPolicy>
+</ConnectedApp>
+```
+
+**Score**: 108/120 ⭐⭐⭐⭐⭐
+
+---
+
+## Example 3: Create a Mobile App with External Client App
+
+**Request**:
+```
+Create an External Client App for our mobile app "FieldServiceMobile".
+It needs PKCE enabled, refresh tokens, and should be packageable for distribution.
+```
+
+**Generated Files**:
+
+### 1. Header File: `FieldServiceMobile.eca-meta.xml`
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<ExternalClientApplication xmlns="http://soap.sforce.com/2006/04/metadata">
+    <contactEmail>mobile-team@company.com</contactEmail>
+    <description>Field Service mobile application for technicians</description>
+    <distributionState>Packageable</distributionState>
+    <isProtected>false</isProtected>
+    <label>FieldServiceMobile</label>
+</ExternalClientApplication>
+```
+
+### 2. Global OAuth: `FieldServiceMobile.ecaGlblOauth-meta.xml`
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<ExtlClntAppGlobalOauthSettings xmlns="http://soap.sforce.com/2006/04/metadata">
+    <callbackUrl>fieldservicemobile://oauth/callback</callbackUrl>
+    <externalClientApplication>FieldServiceMobile</externalClientApplication>
+    <isConsumerSecretOptional>true</isConsumerSecretOptional>
+    <isPkceRequired>true</isPkceRequired>
+    <label>Field Service Mobile Global OAuth</label>
+    <shouldRotateConsumerKey>true</shouldRotateConsumerKey>
+    <shouldRotateConsumerSecret>true</shouldRotateConsumerSecret>
+</ExtlClntAppGlobalOauthSettings>
+```
+
+### 3. OAuth Settings: `FieldServiceMobile.ecaOauth-meta.xml`
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<ExtlClntAppOauthSettings xmlns="http://soap.sforce.com/2006/04/metadata">
+    <commaSeparatedOauthScopes>Api, RefreshToken, OpenID</commaSeparatedOauthScopes>
+    <externalClientApplication>FieldServiceMobile</externalClientApplication>
+    <label>Field Service Mobile OAuth Settings</label>
+</ExtlClntAppOauthSettings>
+```
+
+### 4. Optional OAuth Security Settings (retrieve-first)
+```bash
+sf project retrieve start \
+  --metadata ExtlClntAppOauthSecuritySettings:FieldServiceMobile \
+  --target-org my-devhub
+```
+
+**Score**: 115/120 ⭐⭐⭐⭐⭐
+
+---
+
+## Example 4: Review Existing Connected Apps
+
+**Request**:
+```
+Review and score my existing Connected Apps for security best practices.
+```
+
+**Process**:
+1. Scan: `Glob: **/*.connectedApp-meta.xml`
+2. Read each file
+3. Validate against scoring criteria
+4. Generate report
+
+**Sample Report**:
+```
+📊 CONNECTED APP SECURITY REVIEW
+════════════════════════════════════════════════════════════════
+
+🔍 Apps Scanned: 3
+📅 Review Date: 2025-01-15
+
+┌────────────────────────────┬────────┬────────┬──────────────────┐
+│ App Name                   │ Score  │ Rating │ Critical Issues  │
+├────────────────────────────┼────────┼────────┼──────────────────┤
+│ LegacyERPConnector         │ 45/120 │ ⭐     │ 3                │
+│ MobileAppV2                │ 82/120 │ ⭐⭐⭐  │ 0                │
+│ DataSyncIntegration        │ 95/120 │ ⭐⭐⭐⭐│ 0                │
+└────────────────────────────┴────────┴────────┴──────────────────┘
+
+🚨 CRITICAL ISSUES
+
+LegacyERPConnector:
+  ❌ Wildcard callback URL detected (https://*)
+  ❌ Full scope granted (overly permissive)
+  ❌ No IP restrictions configured
+  ⚠️ Recommend: Migrate to External Client App
+
+✅ RECOMMENDATIONS
+
+1. LegacyERPConnector: URGENT - Fix security issues or migrate to ECA
+2. MobileAppV2: Enable PKCE for mobile security
+3. DataSyncIntegration: Consider enabling token rotation
+```
+
+---
+
+## Example 5: Migrate Connected App to External Client App
+
+**Request**:
+```
+Migrate our "SalesPortal" Connected App to an External Client App for better security.
+```
+
+**Process**:
+1. Read existing Connected App configuration
+2. Map OAuth settings to ECA structure
+3. Generate all required ECA files
+4. Provide migration checklist
+
+**Output**:
+```
+📦 MIGRATION PLAN: SalesPortal → External Client App
+════════════════════════════════════════════════════════════════
+
+📋 Source Configuration
+   Type: Connected App
+   OAuth Flow: Authorization Code
+   Scopes: Api, RefreshToken, OpenID
+   IP Policy: ENFORCE
+
+📄 Files to Generate:
+   1. SalesPortalECA.eca-meta.xml
+   2. SalesPortalECA.ecaGlblOauth-meta.xml
+   3. SalesPortalECA.ecaOauth-meta.xml
+   4. (Optional) SalesPortalECA.ecaOauthSecurity-meta.xml after retrieve-first validation
+
+🔄 Migration Steps:
+   1. ✓ Generate ECA metadata files
+   2. □ Deploy ECA to DevHub
+   3. □ Generate new Consumer Key/Secret
+   4. □ Update external application with new credentials
+   5. □ Test OAuth flow
+   6. □ Configure policies in subscriber orgs
+   7. □ Deactivate old Connected App
+   8. □ Monitor for 30 days before deletion
+
+⚠️ Breaking Change: New Consumer Key/Secret required
+```
+
+---
+
+## Deployment Commands
+
+### Deploy Connected App
+```bash
+sf project deploy start \
+  --source-dir force-app/main/default/connectedApps \
+  --target-org my-org
+```
+
+### Deploy External Client App
+```bash
+sf project deploy start \
+  --metadata ExternalClientApplication:MyECAName \
+  --metadata ExtlClntAppGlobalOauthSettings:MyECAName \
+  --metadata ExtlClntAppOauthSettings:MyECAName \
+  --target-org my-devhub
+```
+
+### Retrieve Existing Apps
+```bash
+# Connected Apps
+sf project retrieve start \
+  --metadata ConnectedApp:MyAppName \
+  --target-org my-org
+
+# External Client Apps (header + companions)
+sf project retrieve start \
+  --metadata ExternalClientApplication:MyECAName \
+  --metadata ExtlClntAppGlobalOauthSettings:MyECAName \
+  --metadata ExtlClntAppOauthSettings:MyECAName \
+  --target-org my-org
+```

package/skills/configuring-connected-apps/references/migration-guide.md

@@ -0,0 +1,328 @@
+<!-- Parent: configuring-connected-apps/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
+
+```
+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."
+```