integration-connectivity-connected-app-configure

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

integration-connectivity-connected-app-configure: Salesforce Connected Apps & External Client Apps

integration-connectivity-connected-app-configure: 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 bearer设置、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 → integration-connectivity-generate
Deploying metadata to orgs → platform-metadata-deploy
Writing Apex token-handling code → platform-apex-generate

包含范围：

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

排除范围 — 请转至对应技能：

配置Named Credentials或运行时调用 → integration-connectivity-generate
向组织部署元数据 → platform-metadata-deploy
编写处理令牌的Apex代码 → platform-apex-generate

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
直接的 legacy 兼容性需求	Connected App

默认指导原则：

对于受监管、可打包或自动化需求高的新解决方案，选择ECA。
当简洁性与legacy兼容性更为重要时，选择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 bearer、设备、客户端凭证
客户端类型：机密型 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 Bearer流程
设备/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 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安全元数据，请先从组织中检索，并将检索到的文件视为架构的可信来源：

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 App创建	新组织会阻止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策略
下一步部署/测试步骤

建议输出格式：

应用: <名称>
类型: Connected App | External Client App
流程: <oauth流程>
文件: <路径>
安全设置: <权限范围、PKCE、证书、密钥、IP策略>
下一步: <部署、检索消费者密钥或测试认证流程>
评分: <x>/120

Cross-Skill Integration

跨技能集成

Need	Delegate to	Reason
Named Credential / callout runtime config	integration-connectivity-generate	runtime integration setup
Deploy app metadata	platform-metadata-deploy	org validation and deployment
Apex token or refresh handling	platform-apex-generate	implementation logic

需求	转至技能	原因
Named Credential/调用运行时配置	integration-connectivity-generate	运行时集成设置
部署应用元数据	platform-metadata-deploy	组织验证与部署
Apex令牌或刷新处理	platform-apex-generate	实现逻辑

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 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场景的完整端到端示例