【ペットクリニックサイト 制作日誌 Vol.3】外部クライアントアプリケーション(ECA)を用いたHeadless Identity認証設定

ヘッドレスでの認証フローを確立するためには、Salesforce側でAPIエンドポイントを開放し、適切な権限を割り当てるインフラ設定が必要です。

第三弾である本記事では、従来の接続アプリケーションに代わる「外部クライアントアプリケーション（ECA）」の設定手順と注意点を解説します。

前回の記事はこちら
【ペットクリニックサイト 制作日誌 Vol.2】Headless Identityでの自己登録ハンドラー実装とデータ処理の最適解

事実（仕様に基づく認証設定の前提）

• 認証コードおよびログイン情報フローを利用するヘッドレス認証では、接続アプリケーションまたはECAの設定が必須です。
• パスワードレスログインを行うためには、入力された識別子（メールアドレス等）から対象ユーザーを特定するための Auth.LoginDiscoveryHandler または Auth.HeadlessUserDiscoveryHandler の実装と登録が求められます。

実装コード（ユーザー検出ハンドラー）

global class SimpleHeadlessUserDiscoveryHandler implements Auth.LoginDiscoveryHandler {
    
    global PageReference login(String identifier, String startUrl, Map<String, String> requestAttributes) {
        // パスワードレスログイン時、入力された識別子（メールアドレス）からアクティブなユーザーを特定します
        List<User> users = [SELECT Id FROM User WHERE Username = :identifier AND IsActive = true LIMIT 1];
        
        if (users.isEmpty()) {
            // 一致するユーザーがいない場合はエラーをスローして処理を中断します
            throw new Auth.LoginDiscoveryException('ユーザーが見つかりません');
        }
        
        // 画面遷移は行わず、Headless Identityの標準パスワードレスフローへ制御を戻します
        return Auth.SessionManagement.finishLoginDiscovery(Auth.LoginDiscoveryMethod.PASSWORDLESS, users[0].Id);
    }
}

推測・見解（外部クライアントアプリケーションの設計判断）

ECA（外部クライアントアプリケーション）を採用する本当の理由

従来の「接続アプリケーション（Connected App）」ではなく、なぜECAを使うのか？その最大のメリットは CI/CD（自動デプロイ）との親和性 です。

ECAは「設定メタデータ」と「セキュリティメタデータ（コンシューマ鍵など）」が分離されているため、環境間（Sandboxから本番など）でのデプロイが安全かつ容易になっています。Headlessアーキテクチャのようなモダンな開発手法を取り入れるなら、インフラ設定もモダンなECAに移行すべきです。

OAuthポリシー「管理者が承認したユーザーは事前承認済み」の選択

ECAのポリシー設定で「すべてのユーザーは自己認証可能」を選択すると、OAuthフロー中に「アクセスを許可しますか？」という同意画面が表示されます。しかし、UIを持たないHeadless環境ではここで処理が停止し invalid_app_access エラーとなります。

そのため、「管理者が承認したユーザーは事前承認済み」を選択し、利用対象のプロファイルまたは権限セットを明示的に割り当てる設計を採用する必要があります。

OAuth 範囲とセキュリティ

開発時の知見（ハマりどころ）

• webスコープの欠落による403エラー
  ECAのOAuthスコープ設定において、「API (api)」や「ヘッドレスログインAPI (pwdless_login_api)」のみを設定し、「Webでデータを管理 (web)」を入れ忘れてしまいました。
  Headlessであっても最終的にExperience Cloudの画面セッション（UIセッション）へ変換する場合は web スコープが必須です。これが欠落していると、アクセストークン取得後のログイン画面遷移時に 403 Invalid_Scope が発生します。

まとめ

外部クライアントアプリケーション（ECA）を利用した認証インフラの構築では、UIを持たないHeadless環境特有の制約を考慮した設定が必要です。

同意画面の表示エラーを防ぐための「管理者が承認したユーザーは事前承認済み」ポリシーの選択や、最終的なUIセッション化を見据えたwebスコープの付与は、開発終盤での手戻りを防ぐための重要なポイントです。

設定画面の項目名と実際のAPI挙動を紐づけて理解し、必要なAPIアクセス権限のみをピンポイントで開放する安全な認証基盤を構築してください。

続いて第四弾の記事もご覧ください。

参考URL

Headless Identity APIs: Configure an External Client App for the Authorization Code and Credentials Flow