sf-connected-apps

sf-connected-apps：Salesforce Connected Apps 与 External Client Apps

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

此技能负责的任务

在工作涉及以下内容时，请使用 sf-connected-apps：

• .connectedApp-meta.xml 或 .eca-meta.xml 文件
• OAuth 流程选择，以及 callback / scope 设置
• JWT bearer 身份验证、device flow、client credentials 或 auth-code 选择
• Connected App 与 External Client App 的架构选择
• consumer-key / secret / certificate 处理策略

以下情况请委派给其他技能：

• 配置 Named Credentials 或运行时 callout → sf-integration
• 分析访问权限 / 权限策略分配 → sf-permissions
• 编写 Apex token 处理代码 → sf-apex
• 将 metadata 部署到 org → sf-deploy

---

首要决策：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。对于新的集成，优先使用 External Client App，除非明确需要兼容 Connected App。

---

首先收集必要的上下文

请询问或推断：

• 应用类型：Connected App 或 ECA
• OAuth 流程：auth code、PKCE、JWT bearer、device、client credentials
• 客户端类型：confidential 或 public
• callback URL / redirect 接入点
• 所需 scopes
• 分发模式：仅限本地 org，还是可打包 / 多 org
• 是否需要证书或 secret 轮换

---

建议的工作流

1. 选择应用模型

决定 Connected App 或 ECA 哪种更适合长期使用。

2. 选择 OAuth 流程

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

3. 从正确的模板开始

请使用提供的资源，而不是从头构建：

• assets/connected-app-basic.xml
• assets/connected-app-oauth.xml
• assets/connected-app-jwt.xml
• assets/external-client-app.xml
• assets/eca-global-oauth.xml
• assets/eca-oauth-settings.xml
• assets/eca-policies.xml

如果需要纳入源代码控制的 ECA OAuth 安全 metadata，请先从 org 中检索，并将检索到的文件作为 schema 的事实依据：

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

4. 加强安全性

优先采用：

• 最小权限 scopes
• 明确的 callback URL
• 对 public 客户端使用 PKCE
• 在适当情况下使用基于证书的身份验证
• 支持轮换的 secret / key 处理方式
• 在可行且易于维护时限制 IP

5. 验证部署就绪情况

交接前，请确认：

• metadata 文件命名正确
• scopes 有合理依据
• callback 和身份验证模型与实际客户端类型相符
• 源代码中未嵌入 secrets

---

高信号安全规则

避免以下反模式：

反模式	失败原因
通配符／范围过宽的回调 URL	存在令牌拦截风险
默认使用 Full 范围	权限过多
公共客户端禁用 PKCE	存在代码拦截风险
将使用者密钥提交到源代码	凭据泄露
自动化缺少轮换／证书策略	长期运维脆弱

默认改进方向：

• 缩小范围
• 限制回调
• 为公共客户端启用 PKCE
• 将密钥保存在版本控制之外
• 在适当情况下使用 JWT 证书或受控的密钥存储

---

重要元数据说明

Connected App

通常位于：

• force-app/main/default/connectedApps/

External Client App

当前受源代码支持的 ECA 元数据使用多个顶层源目录，而非单个 externalClientApps/ 文件夹：

• force-app/main/default/externalClientApps/ → ExternalClientApplication（.eca-meta.xml）
• force-app/main/default/extlClntAppGlobalOauthSets/ → ExtlClntAppGlobalOauthSettings（.ecaGlblOauth-meta.xml）
• force-app/main/default/extlClntAppOauthSettings/ → ExtlClntAppOauthSettings（.ecaOauth-meta.xml）
• force-app/main/default/extlClntAppOauthSecuritySettings/ → ExtlClntAppOauthSecuritySettings（.ecaOauthSecurity-meta.xml）
• force-app/main/default/extlClntAppOauthPolicies/ → ExtlClntAppOauthConfigurablePolicies（.ecaOauthPlcy-meta.xml）
• force-app/main/default/extlClntAppPolicies/ → ExtlClntAppConfigurablePolicies（.ecaPlcy-meta.xml）

重要的文件名注意事项：

• 全局 OAuth 后缀是 .ecaGlblOauth，而非 .ecaGlobalOauth
• 通用策略后缀是 .ecaPlcy，而非 .ecaPolicy
• ExtlClntAppOauthSecuritySettings 应使用 .ecaOauthSecurity

---

输出格式

完成后，按以下顺序报告：

1. 所选应用类型
2. 所选 OAuth 流程
3. 已创建或更新的文件
4. 安全决策
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>

---

跨技能集成

需求	委托给	原因
Named Credential／调用运行时配置	sf-integration	运行时集成设置
部署应用元数据	sf-deploy	组织验证和部署
Apex 令牌或刷新处理	sf-apex	实现逻辑
部署后权限审查	sf-permissions	访问治理

---

参考索引

从这里开始

• references/oauth-flows-reference.md
• references/security-checklist.md
• references/testing-validation-guide.md

迁移／示例

• references/migration-guide.md
• references/example-usage.md
• assets/

---

评分指南

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