KeycloakのIdentity Brokeringは、Google/Entra IDなど外部IdPを「上流」に据え、Keycloakを社内向けのブローカ兼ハブとして機能させる仕組みです。設定項目は少なく見えて、first broker login flowと属性マッピング、そして既存ユーザとの突合が絡むと途端に難しくなります。本稿では現場で踏みやすい落とし穴を軸に、設計の勘所を整理します。
01Identity Brokeringとは何を仲介するのか
Identity Brokering（IDブローカリング）は、Keycloak自身が上流の外部IdP（Identity Provider）に対しては「クライアント」として振る舞い、下流のアプリケーションに対しては「IdP」として振る舞う、いわば認証の中継役を担う機能です。ユーザは普段どおりGoogleやMicrosoft Entra IDでログインし、Keycloakはそのトークン／アサーションを受け取って、自分のrealm内にローカルなユーザ表現（brokered user）を作り、そこにアプリ向けのトークンを発行します。
この構成のメリットは明快です。アプリはKeycloakのOIDC/SAMLだけを知っていればよく、上流IdPが増えても減ってもアプリ側は無変更で済みます。SAML専用のレガシーアプリに対してGoogleログインを提供する、といった「プロトコル変換」もブローカが吸収します。エンタープライズでは、複数事業部がそれぞれ別のEntra IDテナントを持っているようなケースで、Keycloakを共通ハブに据える設計が定番です。realm設計と絡む論点はマルチrealm設計の記事も併せてご参照ください。
02外部IdPの登録 — OIDCとSAMLの実務差
外部IdPの登録は Realm settings ではなく Identity providers から行います。OIDC系（Google、Entra ID、汎用OIDC）であれば、可能な限りDiscovery（.well-known/openid-configuration）のURLを食わせて自動設定させるのが安全です。エンドポイントを手打ちすると、上流のローテーションやリージョン差でJWKS URIがずれたときに気づけません。
- OIDC：Client IDとClient Secretを上流で発行し、KeycloakのRedirect URI（
/realms/{realm}/broker/{alias}/endpoint）を上流に登録します。aliasはURLに出るので、後から変えられない前提で命名してください。 - SAML v2.0：上流のIdPメタデータをインポートするのが基本です。NameID Policy Format（persistent / emailAddress など）と、Want AuthnRequests Signed の要否は上流仕様に厳密に合わせます。ADFSやEntra IDのSAML連携は署名・暗号化の要件が細かく、詳細はSAML/ADFS連携の記事に切り出しています。
共通設定として重要なのが Trust Email と Store Tokens です。Trust Emailは後述のアカウント突合の挙動を根本的に変えるスイッチで、安易にONにすると乗っ取りの経路になります。Store Tokensは上流のトークンを保持してAPI呼び出し（Token Exchange含む）に使う場合のみONにし、不要ならOFFが原則です。トークン中継の設計はToken Exchangeの記事で扱っています。
03first broker login flow — 分岐の全体像
外部IdPで「初めて」ログインしてきたユーザに対して何をするか。これを定義するのが first broker login flow です。IdPごとに First Login Flow を差し替えられるので、社内IdPと公開ソーシャルログインで別フローを当てる、といった作り分けが可能です。デフォルトのフローは複数のauthenticatorの連なりで構成されており、それぞれのRequirement（REQUIRED / ALTERNATIVE / DISABLED）を変えることで挙動を大きく調整できます。認証フローの土台はAuthentication Flowの記事も参照してください。
04各authenticatorの役割と調整ポイント
公式のFirst Login Flowの定義に沿って、実務で触る順に整理します。
- Review Profile：上流から取得したプロフィールの確認・補完画面を出します。Update Profile On First Login が ON なら常に表示、MISSING なら email・姓・名などの必須項目が欠けているときだけ表示、OFF なら原則出しません。上流が必須属性を返さないIdPでは、ここでUXが決まります。
- Create User If Unique：上流アカウントと同じemail／usernameを持つ既存Keycloakアカウントがあるかを確認します。衝突がなければ新規ローカルユーザを作成してリンクし、フローを終了します。
- Confirm Link Existing Account：emailが既存ユーザと衝突した場合、「同じemailのアカウントが既にある」ことを提示し、リンクするか、別のemail/usernameでやり直すかをユーザに選ばせます。
- Verify Existing Account By Email：デフォルトでALTERNATIVE。SMTP設定済みなら確認メールを送り、メール到達をもって本人確認とします。
- Verify Existing Account By Re-authentication：デフォルトでALTERNATIVE。既存アカウントのパスワード（や別の連携IdP）で再認証させ、確かに本人であることを確認したうえでリンクします。
05既存ユーザとの突合とアカウントリンク
Identity Brokeringで最も設計判断が求められるのが、上流アカウントと社内の既存ユーザをどう突き合わせるか、です。パターンは大きく三つあります。
- プロンプトありリンク（デフォルト）：emailが一致したら本人確認（メール or 再認証）を経てリンク。ソーシャルログインを含む一般的な構成で無難な選択です。
- 自動リンク（Automatically link）：Trust Email が有効で、かつ上流のemailが検証済みとみなせる場合、確認画面を挟まずに既存ユーザへ自動リンクします。上流を自社で統制しているEntra IDやGoogle Workspaceの管理ドメインなら現実的です。
- 新規作成を無効化（Disabling automatic user creation）：Create User If Unique と Confirm Link Existing Account を DISABLED にし、代わりに再認証で突合させる構成。「このrealmには事前登録済みユーザしかログインさせない」ポリシーを実現できます。さらに Detect Existing Broker User＋Automatically Set Existing User を使う detect existing user flow では、登録済みユーザをプロンプトなしで自動リンクします。
事前プロビジョニング済みのユーザだけを通したい場合、LDAP/AD federationで社内ディレクトリをKeycloakに取り込んでおき、ブローカ側は突合専用に振る設計が効きます。ディレクトリ連携はLDAP/AD連携を参照してください。組織単位での統制方針はマルチアカウント統制の観点も絡みます。
06Trust Email と「サイレントな乗っ取り経路」
ここは声を大にして書きます。Trust Email をONにして自動リンクを有効化する際は、上流が返すemailが本当に検証済みかを必ず確認してください。上流が未検証のemailをそのまま渡してくるIdPで自動リンクを有効にすると、攻撃者が「被害者のemail」で上流アカウントを作り、Keycloak経由でログインするだけで、被害者の既存ローカルアカウントに自分の連携IDが紐づいてしまいます。以後、攻撃者は自分の上流アカウントで被害者になりすませます。
判断基準はシンプルです。emailを必ず検証すると仕様・運用で確認できる上流（自社統制下のEntra ID / Okta / 管理ドメインのGoogle Workspace 等）に限って自動リンクを許可し、公開ソーシャルプロバイダではデフォルトの検証フロー（メール確認 or 再認証）を残す。これが安全側の既定値です。
07属性マッピング — 何を、いつ取り込むか
上流のクレーム／アサーションをローカルユーザにどう写すかは、Identity Provider Mappers で定義します。Mapping Claims and Assertionsで規定された代表的なマッパは次のとおりです。
- Attribute Importer：OIDCのIDトークン／アクセストークンのクレーム、またはSAMLアサーションの属性を、ローカルユーザの属性（email、firstName、任意の属性）へ写します。突合の起点になるemailは、まずここで確実に入るよう設計します。
- Username Template Importer：
${ALIAS}.${CLAIM.sub}のようなテンプレートでusernameを生成します。ソーシャルログインを複数束ねると別IdP間でusernameが衝突しがちなので、aliasを前置して名前空間を分けるのが定石です。 - Hardcoded Attribute / Role：特定IdP経由のユーザに固定の属性・ロールを付与します。「このIdPから来たら外部パートナー扱い」のような統制に使えます。
マッパには Sync Mode（IMPORT＝初回のみ / FORCE＝毎回上書き / LEGACY）があり、これが属性の鮮度を決めます。役職や所属を上流のマスタに追従させたいならFORCE、初回登録値を守りたいならIMPORTです。ロール・グループ・属性の設計はロール/グループ/属性設計も併せてご覧ください。なお、これらの設定はConsoleではなくIaC（Terraform / Admin REST API）で宣言的に管理することを強く推奨します。realm export の差分で構成を追える状態を保つと、監査もバージョンアップも格段に楽になります。
—まとめ
Identity Brokeringは、外部IdP登録・first broker login flow・属性マッピング・既存ユーザ突合の四つが噛み合って初めて安全に回ります。とりわけ Trust Email と自動リンクは、UXを軽くする誘惑と乗っ取りリスクが表裏一体です。上流のemail検証保証を確認し、統制下のIdPに限って自動化する。公開ソーシャルにはデフォルトの検証フローを残す。この線引きを設計初期に決めておくことが、後々のインシデントを防ぎます。バージョン依存の挙動（現行のディストリビューションはQuarkus版のみ。WildFly版はKeycloak 17.0.0で非推奨化され、18.0.0以降は削除されサポート対象外です）やセキュリティ修正の取り込みは、必ず公式ドキュメントで最新を確認してください。EMWではKeycloakによる認証基盤の実構築実績があり、導入事例もご参照いただけます。
—参考（一次情報）
- Keycloak Server Administration Guide — Integrating identity providers
- Keycloak Server Administration Guide — First Login Flow
- Keycloak Server Administration Guide — Mapping Claims and Assertions
- Keycloak GitHub Issue #49175 — CVE-2026-9087: Cross-Session Email Verification Proof Not Bound to Upstream Identity in First-Broker-Login
- Keycloak — Migrating to Quarkus distribution（WildFly版の非推奨化・削除について）