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 のアーキテクチャ上の選択
• コンシューマーキー／シークレット／証明書の取り扱い方針

対象外 — 以下に委任してください:

• Named Credentials またはランタイムコールアウトの設定 → building-sf-integrations
• メタデータの組織へのデプロイ → deploying-metadata
• Apex のトークン処理コードの作成 → generating-apex

---

最初の判断：Connected App と External Client App のどちらを選ぶか

要件	推奨
シンプルな単一組織の OAuth アプリ	Connected App
シークレットの取り扱いを改善した新規開発	External Client App
複数組織／パッケージ化／より強力な運用管理	External Client App
既存システムとの互換性を簡潔に保つ	Connected App

基本方針：

• 新規の規制対象、パッケージ化可能、または自動化を多用するソリューションには ECA を選択してください。
• シンプルさと既存システムとの互換性を重視する場合は Connected App を選択してください。
• Spring '26 に関する注意：組織では、新しい Connected App の作成がデフォルトで無効になっています。新しいインテグレーションには、Connected App との互換性が明示的に必要な場合を除き、External Client App を優先してください。

---

必要な入力情報

以下を確認するか、推定してください：

• アプリの種類：Connected App または ECA
• OAuth フロー：認可コード、PKCE、JWT bearer、デバイス、クライアントクレデンシャル
• クライアントの種類：機密クライアントかパブリッククライアントか
• コールバック URL／リダイレクト先
• 必要なスコープ
• 配布モデル：ローカル組織のみか、パッケージ化／複数組織向けか
• 証明書またはシークレットのローテーションが必要かどうか

---

ワークフロー

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 セキュリティメタデータが必要な場合は、まず組織から取得し、取得したファイルをスキーマの信頼できる情報源として扱ってください：

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

4. セキュリティを強化する

完全版の 120 項目のセキュリティチェックリストについては、references/security-checklist.md をお読みください。以下を優先してください：

• 最小権限のスコープ
• 明示的なコールバック 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 コマンドではハードコードされた組織 URL ではなく、<alias> プレースホルダーを使用する	組織 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

---

注意点

注意点	詳細
.ecaGlobalOauth ではなく .ecaGlblOauth	グローバル OAuth のサフィックスは省略形です。長い形式を使うとデプロイに失敗します
.ecaPolicy ではなく .ecaPlcy	同じ省略パターンです。一般ポリシーのサフィックスは短縮形です
セキュリティ設定には .ecaOauthSecurity を使用する	.ecaSecurity ではなく .ecaOauthSecurity を使用してください
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

---

スキル間の連携

必要な作業	委任先	理由
名前付き認証情報／コールアウトの実行時設定	building-sf-integrations	実行時のインテグレーション設定
アプリのメタデータをデプロイする	deploying-metadata	組織の検証とデプロイ
Apex のトークンまたは更新処理	generating-apex	実装ロジック

---

スコアガイド

スコア	意味
80+	本番環境向けの OAuth アプリ設定
54–79	使用可能ですが、堅牢化のレビューが必要です
< 54	修正されるまでデプロイをブロックしてください

---

参照ファイル一覧

ファイル	読むタイミング
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 シナリオのエンドツーエンドの例