configuring-connected-apps

configuring-connected-apps：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 或运行时 callout → building-sf-integrations
• 将元数据部署到 org → deploying-metadata
• 编写 Apex 令牌处理代码 → generating-apex

---

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

如果需求是……	优先选择
简单的单 org OAuth 应用	Connected App
需要更完善的 secret 处理方式的新开发	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
• 是否需要证书或 secret 轮换

---

工作流

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
• 适当时采用基于证书的身份验证
• 支持轮换的 secret／密钥处理方式
• 在切实可行且易于维护时限制 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 运行时配置	building-sf-integrations	运行时集成设置
部署应用元数据	deploying-metadata	组织验证和部署
Apex 令牌或刷新处理	generating-apex	实现逻辑

---

评分指南

分数	含义
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 / server-to-server 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 场景的端到端完整示例