integration-connectivity-connected-app-configure

integration-connectivity-connected-app-configure: Salesforce 接続アプリと外部クライアントアプリ

Salesforce で Connected App、External Client App（ECA）、JWT ベアラーの設定、PKCE の判断、スコープの設計、または従来の Connected App パターンから新しい ECA パターンへの移行など、OAuth アプリの設定が必要な場合にこのスキルを使用します。

対象範囲

対象:

• .connectedApp-meta.xml または .eca-meta.xml ファイル
• OAuth フローの選択とコールバック／スコープの設定
• JWT ベアラー認証、デバイスフロー、クライアントクレデンシャル、または認可コードの判断
• Connected App と External Client App のアーキテクチャ選択
• コンシューマーキー／シークレット／証明書の取り扱い方針

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

• Named Credentials または実行時のコールアウトの設定 → integration-connectivity-generate
• メタデータの組織へのデプロイ → platform-metadata-deploy スキル
• Apex のトークン処理コードの作成 → platform-apex-generate スキル

---

最初の判断：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 ベアラー、デバイス、クライアントクレデンシャル
• クライアントの種類: confidential または public
• コールバック URL／リダイレクト先
• 必要なスコープ
• 配布モデル: ローカル組織のみ、またはパッケージ化可能／複数組織
• 証明書またはシークレットのローテーションが必要かどうか

---

ワークフロー

1. アプリモデルを選択する

上記の判断表を使って、Connected App と ECA のどちらが長期的に適しているかを判断します。

2. OAuth フローを選択する

ユースケース	デフォルトのフロー
バックエンドの Web アプリ	認可コード
SPA／モバイル／パブリッククライアント	認可コード + PKCE
サーバー間通信／CI/CD	JWT ベアラー
デバイス／CLI 認証	デバイスフロー
サービスアカウント型アプリ	クライアントクレデンシャル（通常は ECA）

3. 適切なテンプレートを使用する

生成する前に、適切なテンプレートを読み込んでください。ゼロから作成しないでください:

テンプレート	ユースケース
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. セキュリティを強化する

完全版の 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

---

スキル間の連携

必要な内容	委任先	理由
名前付き認証情報／コールアウトのランタイム設定	integration-connectivity-generate	ランタイムの統合設定
アプリのメタデータをデプロイする	platform-metadata-deploy スキル	組織の検証とデプロイ
Apex のトークンまたはリフレッシュの処理	platform-apex-generate スキル	実装ロジック

---

スコアガイド

スコア	意味
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 シナリオのエンドツーエンドの完全な例