integration-connectivity-connected-app-configure

integration-connectivity-connected-app-configure：Salesforce Connected Apps 和 External Client Apps

当用户需要在 Salesforce 中进行 OAuth 应用配置时使用此技能：包括 Connected Apps、External Client Apps（ECA）、JWT bearer 配置、PKCE 决策、范围设计，或从旧版 Connected App 模式迁移到新版 ECA 模式。

范围

适用范围：

• .connectedApp-meta.xml 或 .eca-meta.xml 文件
• OAuth 流程选择以及回调 / 范围设置
• JWT bearer 身份验证、设备流、客户端凭据或授权码决策
• Connected App 与 External Client App 的架构选择
• Consumer key / secret / 证书处理策略

不适用范围 — 委派给其他技能：

• 配置 Named Credentials 或运行时调用 → integration-connectivity-generate
• 将元数据部署到 org → platform-metadata-deploy 技能
• 编写 Apex 令牌处理代码 → platform-apex-generate 技能

---

首要决策：Connected App 还是 External Client App

如果需求是……	优先选择
简单的单 org OAuth 应用	Connected App
更妥善处理密钥的新开发项目	External Client App
多 org / 打包 / 更强的运维控制	External Client App
直接兼容旧版	Connected App

默认建议：

• 对新的受监管、可打包或自动化程度高的解决方案，选择 ECA。
• 更看重简便性和旧版兼容性时，选择 Connected App。
• Spring '26 说明：默认情况下，org 中已禁用创建新的 Connected App。对于新的集成，除非明确需要兼容 Connected App，否则优先选择 External Client App。

---

必需输入

询问用户或推断以下信息：

• 应用类型：Connected App 或 ECA
• OAuth 流程：授权码、PKCE、JWT bearer、设备流、客户端凭据
• 客户端类型：机密客户端还是公共客户端
• 回调 URL / 重定向入口
• 所需范围
• 分发模式：仅限本地 org，还是支持打包 / 多 org
• 是否需要证书或密钥轮换

---

工作流

1. 选择应用模型

根据上方决策表，判断 Connected App 或 ECA 哪个更适合长期使用。

2. 选择 OAuth 流程

用例	默认流程
后端 Web 应用	Authorization Code
SPA / 移动应用 / 公共客户端	Authorization Code + PKCE
服务器到服务器 / CI/CD	JWT Bearer
设备 / CLI 身份验证	Device Flow
服务账户式应用	Client Credentials（通常为 ECA）

3. 从合适的模板开始

生成前先阅读相应模板 — 不要从头开始构建：

模板	用例
assets/connected-app-basic.xml	简单的 API 集成、最基本的 OAuth
assets/connected-app-oauth.xml	具有完整 OAuth 2.0 配置的 Web 应用
assets/connected-app-jwt.xml	JWT bearer / 服务器到服务器
assets/connected-app-canvas.xml	在 Salesforce UI 中嵌入外部应用（Canvas）
assets/external-client-app.xml	ECA 头文件 — 所有新的 ECA 构建都从这里开始
assets/eca-global-oauth.xml	ECA 全局 OAuth 设置（范围、PKCE、轮换）
assets/eca-oauth-settings.xml	ECA 的单应用 OAuth 设置
assets/eca-policies.xml	ECA 可配置策略

如果需要纳入源代码控制的 ECA OAuth 安全元数据，先从 org 中检索，并将检索到的文件视为架构事实来源：

sf project retrieve start --metadata ExtlClntAppOauthSecuritySettings:<AppName> --target-org <alias>

4. 加强安全性

阅读 references/security-checklist.md，查看完整的 120 项安全检查清单。优先采用：

• 最小权限范围
• 明确指定的回调 URL
• 为公共客户端启用 PKCE
• 在适当情况下使用基于证书的身份验证
• 支持轮换的密钥 / 密钥材料处理方式
• 在切实可行且易于维护时限制 IP

5. 验证部署就绪情况

交接前请阅读 references/testing-validation-guide.md。确认：

• 元数据文件命名正确（参见下文“注意事项”）
• 请求的权限范围有充分依据
• 回调和身份验证模型与实际客户端类型一致
• 源代码中未嵌入机密

6. 处理错误

如果部署失败，请检查错误输出，留意以下内容：

• DUPLICATE_VALUE — 已存在同名的 Connected App 或 ECA；请更改名称，或先检索再更新
• INVALID_CROSS_REFERENCE_KEY — ECA 设置文件中的 externalClientApplication 名称与 .eca-meta.xml 文件名不完全匹配
• INSUFFICIENT_ACCESS_OR_READONLY — 用户缺少“Manage Connected Apps”权限
• 如果任何步骤失败，请勿继续下一步；请向用户显示错误，并提供上述具体信息

---

规则 / 约束

规则	原因
切勿将使用者机密提交到源代码管理中	凭据泄露风险
默认情况下切勿使用 Full 权限范围	权限过度；仅请求应用所需的权限
公共客户端（移动应用、SPA）始终使用 PKCE	防止授权码被截取
切勿使用通配符或范围过宽的回调 URL	令牌被截取的风险
编辑 ECA OAuth 安全设置前，必须先从组织检索	文件架构尚未完整记录；先检索可确保准确性
在 CLI 命令中使用 <alias> 占位符，切勿硬编码组织 URL	组织 URL 因环境而异
写入文件前，请从 sfdx-project.json 检测实际的 packageDirectory	项目可能未采用默认的 force-app/main/default/ 布局

---

重要的元数据说明

Connected App

默认源位置（通过 sfdx-project.json → packageDirectories 验证）：

• <packageDir>/connectedApps/

External Client App

ECA 元数据分布在多个顶层源目录中。默认位置（通过 sfdx-project.json 验证）：

目录	元数据类型	文件后缀
<packageDir>/externalClientApps/	ExternalClientApplication	.eca-meta.xml
<packageDir>/extlClntAppGlobalOauthSets/	ExtlClntAppGlobalOauthSettings	.ecaGlblOauth-meta.xml
<packageDir>/extlClntAppOauthSettings/	ExtlClntAppOauthSettings	.ecaOauth-meta.xml
<packageDir>/extlClntAppOauthSecuritySettings/	ExtlClntAppOauthSecuritySettings	.ecaOauthSecurity-meta.xml
<packageDir>/extlClntAppOauthPolicies/	ExtlClntAppOauthConfigurablePolicies	.ecaOauthPlcy-meta.xml
<packageDir>/extlClntAppPolicies/	ExtlClntAppConfigurablePolicies	.ecaPlcy-meta.xml

---

注意事项

注意事项	详情
使用 .ecaGlblOauth，而非 .ecaGlobalOauth	全局 OAuth 后缀采用缩写 — 使用全称会导致部署失败
使用 .ecaPlcy，而非 .ecaPolicy	同样采用缩写 — 通用策略后缀为简写
安全设置使用 .ecaOauthSecurity	使用 .ecaOauthSecurity，而非 .ecaSecurity
ECA OAuth 安全设置只能检索	无法在源代码中从零创建 — 必须先从组织检索
Spring '26：默认禁用新建 Connected App	新组织会阻止创建 Connected App；除非明确需要，否则请使用 ECA
使用者密钥在部署后生成	无法在元数据中设置使用者密钥 — 首次部署后再检索

---

输出要求

完成时，请按以下顺序确认并报告：

1. 所选应用类型 — Connected App 或 External Client App
2. 所选 OAuth 流程
3. 创建或更新的文件 — 列出每个元数据文件路径
4. 安全决策 — 权限范围、PKCE、证书、机密、IP 策略
5. 下一步部署 / 测试步骤

建议的输出格式：

App: <name>
Type: Connected App | External Client App
Flow: <oauth flow>
Files: <paths>
Security: <scopes, PKCE, certs, secrets, IP policy>
Next step: <deploy, retrieve consumer key, or test auth flow>
Score: <x>/120

---

跨技能集成

需求	委派给	原因
Named Credential / callout 运行时配置	integration-connectivity-generate	运行时集成设置
部署应用元数据	platform-metadata-deploy skill	组织验证和部署
Apex 令牌或刷新处理	platform-apex-generate skill	实现逻辑

---

评分指南

分数	含义
80+	可用于生产的 OAuth 应用配置
54–79	可用，但需要加固审查
< 54	修复前禁止部署

---

参考文件索引

文件	何时阅读
assets/connected-app-basic.xml	第 3 步 — 简易 Connected App（含最少 OAuth 配置）的模板
assets/connected-app-oauth.xml	第 3 步 — 完整 OAuth 2.0 Connected App 的模板
assets/connected-app-jwt.xml	第 3 步 — JWT bearer / 服务到服务 Connected App 的模板
assets/connected-app-canvas.xml	第 3 步 — 在 Salesforce UI 中嵌入 Canvas 应用的模板
assets/external-client-app.xml	第 3 步 — ECA 头文件模板
assets/eca-global-oauth.xml	第 3 步 — ECA 全局 OAuth 设置模板（PKCE、轮换、回调）
assets/eca-oauth-settings.xml	第 3 步 — ECA 单应用 OAuth 设置模板
assets/eca-policies.xml	第 3 步 — ECA 可配置策略模板
references/oauth-flows-reference.md	第 2 步 — OAuth 流程详细对比和决策指南
references/security-checklist.md	第 4 步 — 完整的 120 分安全评分检查清单
references/testing-validation-guide.md	第 5 步 — 部署前验证和测试指南
references/migration-guide.md	从 Connected App 迁移到 ECA 模式时阅读
references/example-usage.md	常见 OAuth 场景的端到端完整示例