configuring-connected-apps

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

configuring-connected-apps: Salesforce Connected Apps & External Client Apps

configuring-connected-apps：Salesforce Connected Apps与External Client Apps配置

Use this skill when the user needs OAuth app configuration in Salesforce: Connected Apps, External Client Apps (ECAs), JWT bearer setup, PKCE decisions, scope design, or migration from older Connected App patterns to newer ECA patterns.

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

Scope

适用范围

In scope:

```
.connectedApp-meta.xml
```
or
```
.eca-meta.xml
```
files
OAuth flow selection and callback / scope setup
JWT bearer auth, device flow, client credentials, or auth-code decisions
Connected App vs External Client App architecture choices
Consumer key / secret / certificate handling strategy

Out of scope — delegate elsewhere:

Configuring Named Credentials or runtime callouts → building-sf-integrations
Deploying metadata to orgs → deploying-metadata
Writing Apex token-handling code → generating-apex

包含范围：

```
.connectedApp-meta.xml
```
或
```
.eca-meta.xml
```
文件
OAuth流程选择及回调/权限范围设置
JWT承载认证、设备流程、客户端凭证或授权码决策
Connected App与External Client App架构选择
消费者密钥/密钥/证书处理策略

排除范围 — 请委托至其他技能：

配置Named Credentials或运行时调用 → building-sf-integrations
将元数据部署至组织 → deploying-metadata
编写Apex令牌处理代码 → generating-apex

First Decision: Connected App or External Client App

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

If the need is...	Prefer
simple single-org OAuth app	Connected App
new development with better secret handling	External Client App
multi-org / packaging / stronger operational controls	External Client App
straightforward legacy compatibility	Connected App

Default guidance:

Choose ECA for new regulated, packageable, or automation-heavy solutions.
Choose Connected App when simplicity and legacy compatibility matter more.
Spring '26 note: creation of new Connected Apps is disabled by default in orgs. For new integrations, prefer External Client Apps unless Connected App compatibility is explicitly required.

需求场景	推荐选择
简单的单组织OAuth应用	Connected App
具备更优密钥处理的新开发项目	External Client App
多组织/打包/更强运营管控	External Client App
直接的遗留系统兼容性	Connected App

默认指导原则：

对于新的受监管、可打包或自动化程度高的解决方案，选择ECA。
当简洁性和遗留兼容性更为重要时，选择Connected App。
Spring '26注意事项：组织中默认禁用新Connected App的创建。对于新集成，除非明确需要Connected App兼容性，否则优先选择External Client Apps。

Required Inputs

必要输入信息

Ask for or infer:

App type: Connected App or ECA
OAuth flow: auth code, PKCE, JWT bearer, device, client credentials
Client type: confidential vs public
Callback URLs / redirect surfaces
Required scopes
Distribution model: local org only vs packageable / multi-org
Whether certificates or secret rotation are required

需询问或推断：

应用类型：Connected App或ECA
OAuth流程：授权码、PKCE、JWT承载、设备、客户端凭证
客户端类型：机密型 vs 公开型
回调URL/重定向界面
所需权限范围
分发模式：仅本地组织 vs 可打包/多组织
是否需要证书或密钥轮换

Workflow

工作流程

1. Choose the app model

1. 选择应用模型

Decide whether a Connected App or ECA is the better long-term fit using the decision table above.

使用上述决策表确定Connected App或ECA哪个更适合长期需求。

2. Choose the OAuth flow

2. 选择OAuth流程

Use case	Default flow
backend web app	Authorization Code
SPA / mobile / public client	Authorization Code + PKCE
server-to-server / CI/CD	JWT Bearer
device / CLI auth	Device Flow
service account style app	Client Credentials (typically ECA)

使用场景	默认流程
后端Web应用	授权码流程
SPA/移动/公开客户端	授权码 + PKCE
服务器到服务器/CI/CD	JWT承载
设备/CLI认证	设备流程
服务账户类应用	客户端凭证（通常为ECA）

3. Start from the right template

3. 从正确的模板开始

Read the appropriate template before generating — do not build from scratch:

Template	Use case
`assets/connected-app-basic.xml`	Simple API integration, minimal OAuth
`assets/connected-app-oauth.xml`	Web app with full OAuth 2.0 configuration
`assets/connected-app-jwt.xml`	JWT bearer / server-to-server
`assets/connected-app-canvas.xml`	Embedding external apps in Salesforce UI (Canvas)
`assets/external-client-app.xml`	ECA header file — all new ECA builds start here
`assets/eca-global-oauth.xml`	ECA global OAuth settings (scopes, PKCE, rotation)
`assets/eca-oauth-settings.xml`	ECA per-app OAuth settings
`assets/eca-policies.xml`	ECA configurable policies

If you need source-controlled ECA OAuth security metadata, retrieve it from an org first and treat the retrieved file as the schema source of truth:

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

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

模板	使用场景
`assets/connected-app-basic.xml`	简单API集成，极简OAuth配置
`assets/connected-app-oauth.xml`	具备完整OAuth 2.0配置的Web应用
`assets/connected-app-jwt.xml`	JWT承载/服务器到服务器集成
`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安全元数据，请先从组织中检索，并将检索到的文件作为架构的事实来源：

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

4. Apply security hardening

4. 应用安全加固

Read

references/security-checklist.md

for the full 120-point security checklist. Favor:

Least-privilege scopes
Explicit callback URLs
PKCE for public clients
Certificate-based auth where appropriate
Rotation-ready secret / key handling
IP restrictions when realistic and maintainable

阅读

references/security-checklist.md

获取完整的120分安全检查清单。优先考虑：

最小权限范围
明确的回调URL
公开客户端使用PKCE
适当情况下使用基于证书的认证
支持轮换的密钥/密钥处理方式
在实际可行且可维护的情况下设置IP限制

5. Validate deployment readiness

5. 验证部署就绪状态

Read

references/testing-validation-guide.md

before handoff. Confirm:

Metadata file naming is correct (see Gotchas below)
Scopes are justified
Callback and auth model match the real client type
Secrets are not embedded in source

移交前阅读

references/testing-validation-guide.md

。确认：

元数据文件命名正确（见下方注意事项）
权限范围合理
回调和认证模型与实际客户端类型匹配
密钥未嵌入源代码中

6. Handle errors

6. 处理错误

If deployment fails, check the error output for:

```
DUPLICATE_VALUE
```
— a Connected App or ECA with this name already exists; rename or retrieve-then-update instead
```
INVALID_CROSS_REFERENCE_KEY
```
— the
```
externalClientApplication
```
name in an ECA settings file doesn't match the
```
.eca-meta.xml
```
filename exactly
```
INSUFFICIENT_ACCESS_OR_READONLY
```
— user lacks the "Manage Connected Apps" permission
If any step fails, do not proceed to the next step — surface the error to the user with the specific message above

如果部署失败，请检查错误输出：

```
DUPLICATE_VALUE
```
— 同名的Connected App或ECA已存在；请重命名或先检索再更新

INVALID_CROSS_REFERENCE_KEY

— ECA设置文件中的

externalClientApplication

名称与

.eca-meta.xml

文件名不完全匹配

```
INSUFFICIENT_ACCESS_OR_READONLY
```
— 用户缺少"Manage Connected Apps"权限
若任何步骤失败，请勿进行下一步骤 — 向用户展示上述具体错误信息

Rules / Constraints

规则/约束

Rule	Rationale
Never commit consumer secrets to source control	Credential exposure risk
Never use `Full` scope by default	Unnecessary privilege; request only what the app needs
Always use PKCE for public clients (mobile, SPA)	Prevents auth code interception
Never use wildcard or overly broad callback URLs	Token interception risk
ECA OAuth security settings must be retrieved from org before editing	File schema is not fully documented; retrieve-first ensures accuracy
Use `<alias>` placeholders in CLI commands, never hardcoded org URLs	Org URLs vary per environment
Detect actual `packageDirectory` from `sfdx-project.json` before writing files	Projects may not use the default `force-app/main/default/` layout

规则	理由
切勿将消费者密钥提交至源代码控制	存在凭证泄露风险
默认情况下切勿使用 `Full` 权限范围	不必要的权限；仅请求应用所需的权限
公开客户端（移动、SPA）始终使用PKCE	防止授权码拦截
切勿使用通配符或过于宽泛的回调URL	存在令牌拦截风险
ECA OAuth安全设置必须先从组织检索再编辑	文件架构未完全文档化；先检索可确保准确性
CLI命令中使用 `<alias>` 占位符，切勿硬编码组织URL	组织URL因环境而异
写入文件前从 `sfdx-project.json` 检测实际的 `packageDirectory`	项目可能不使用默认的 `force-app/main/default/` 布局

Metadata Notes That Matter

重要元数据说明

Connected App

Default source location (verify via

sfdx-project.json → packageDirectories

```
<packageDir>/connectedApps/
```

默认源代码位置（通过

sfdx-project.json → packageDirectories

验证）：

```
<packageDir>/connectedApps/
```

External Client App

ECA metadata spans multiple top-level source directories. Default locations (verify via

sfdx-project.json

Directory	Metadata type	File suffix
`<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`

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`

Gotchas

注意事项

Gotcha	Detail
`.ecaGlblOauth` not `.ecaGlobalOauth`	The global OAuth suffix is abbreviated — using the long form will break deployment
`.ecaPlcy` not `.ecaPolicy`	Same abbreviation pattern — the general policy suffix is short form
`.ecaOauthSecurity` for security settings	Use `.ecaOauthSecurity` , not `.ecaSecurity`
ECA OAuth security settings are retrieve-only	Cannot be created from scratch in source — always retrieve from org first
Spring '26: new Connected Apps disabled by default	New orgs block Connected App creation; use ECA unless explicitly required
Consumer key is generated post-deploy	You cannot set the consumer key in metadata — retrieve it after first deployment

注意点	详情
使用 `.ecaGlblOauth` 而非 `.ecaGlobalOauth`	全局OAuth后缀为缩写形式 — 使用全称会导致部署失败
使用 `.ecaPlcy` 而非 `.ecaPolicy`	相同的缩写规则 — 通用策略后缀为缩写形式
安全设置使用 `.ecaOauthSecurity`	使用 `.ecaOauthSecurity` ，而非 `.ecaSecurity`
ECA OAuth安全设置仅可检索	无法从源代码从零创建 — 始终先从组织检索
Spring '26：默认禁用新Connected Apps创建	新组织会阻止Connected App创建；除非明确要求，否则使用ECA
消费者密钥在部署后生成	无法在元数据中设置消费者密钥 — 首次部署后检索

Output Expectations

输出预期

When finishing, confirm and report in this order:

App type chosen — Connected App or External Client App
OAuth flow chosen
Files created or updated — list each metadata file path
Security decisions — scopes, PKCE, certs, secrets, IP policy
Next deployment / testing step

Suggested output shape:

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

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

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

建议输出格式：

App: <名称>
Type: Connected App | External Client App
Flow: <OAuth流程>
Files: <路径>
Security: <权限范围、PKCE、证书、密钥、IP策略>
Next step: <部署、检索消费者密钥或测试认证流程>
Score: <得分>/120

Cross-Skill Integration

跨技能集成

Need	Delegate to	Reason
Named Credential / callout runtime config	building-sf-integrations	runtime integration setup
Deploy app metadata	deploying-metadata	org validation and deployment
Apex token or refresh handling	generating-apex	implementation logic

需求	委托至	原因
Named Credential/调用运行时配置	building-sf-integrations	运行时集成设置
部署应用元数据	deploying-metadata	组织验证与部署
Apex令牌或刷新处理	generating-apex	实现逻辑

Score Guide

评分指南

Score	Meaning
80+	production-ready OAuth app config
54–79	workable but needs hardening review
< 54	block deployment until fixed

得分	含义
80+	可用于生产环境的OAuth应用配置
54–79	可用但需进行加固审查
< 54	阻止部署直至问题修复

Reference File Index

参考文件索引

File	When to read
`assets/connected-app-basic.xml`	Step 3 — template for simple Connected App with minimal OAuth
`assets/connected-app-oauth.xml`	Step 3 — template for full OAuth 2.0 Connected App
`assets/connected-app-jwt.xml`	Step 3 — template for JWT bearer / server-to-server Connected App
`assets/connected-app-canvas.xml`	Step 3 — template for Canvas app embedding in Salesforce UI
`assets/external-client-app.xml`	Step 3 — ECA header file template
`assets/eca-global-oauth.xml`	Step 3 — ECA global OAuth settings template (PKCE, rotation, callbacks)
`assets/eca-oauth-settings.xml`	Step 3 — ECA per-app OAuth settings template
`assets/eca-policies.xml`	Step 3 — ECA configurable policies template
`references/oauth-flows-reference.md`	Step 2 — detailed OAuth flow comparison and decision guide
`references/security-checklist.md`	Step 4 — full 120-point security scoring checklist
`references/testing-validation-guide.md`	Step 5 — pre-deployment validation and testing guide
`references/migration-guide.md`	When migrating from Connected App to ECA patterns
`references/example-usage.md`	Full end-to-end examples for common OAuth scenarios

文件	阅读时机
`assets/connected-app-basic.xml`	步骤3 — 极简OAuth配置的简单Connected App模板
`assets/connected-app-oauth.xml`	步骤3 — 完整OAuth 2.0配置的Connected App模板
`assets/connected-app-jwt.xml`	步骤3 — JWT承载/服务器到服务器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场景的完整端到端示例