Keycloak Organizations — マルチテナントSaaSの新選択肢

Keycloak 26でOrganizationsが正式サポートとなり、顧客企業ごとにrealmを増やさずに1つのrealm内でマルチテナントを表現できるようになりました。B2B/B2B2C SaaSの認証基盤設計にとって、realm分割一辺倒だった選択肢が大きく広がっています。本稿では機能の実像とrealm分割との使い分けを、現場の実務目線で整理します。

「顧客企業が増えるたびにrealmを1つ切る」——B2B SaaSでKeycloakを使うと、この運用にどこかで無理が出てきます。realmはそれ自体が独立した設定・鍵・テーマ・クライアント群を持つ重い箱で、テナントが数十を超えると管理コストが跳ね上がります。Keycloak 26で正式サポートとなったOrganizationsは、この課題に対して「1つのrealmの中で組織を分ける」という別解を提供します。本稿では、その実像とrealm分割との使い分けを整理します。

01Organizationsとは何か

Organizationsは、Keycloakの既存のIAM機能を土台に、B2B(Business-to-Business)やB2B2CといったCIAM(Customer Identity and Access Management)のユースケースを1realm内で扱うための機能です。公式には2024年6月にKeycloak 25でテクノロジープレビューとして発表され、Keycloak 26で正式サポート(supported)かつデフォルト有効となりました。

ざっくり言えば、1つのrealmの中に「組織(Organization)」という論理的な区切りを作り、そこにメンバー(ユーザー)を所属させ、組織ごとに外部IdPやドメイン、属性を紐付けられる仕組みです。従来のように顧客ごとにrealmを増やすのではなく、realmは共通基盤として1つに保ちつつ、テナントの境界をOrganizationとして表現します。

現場のコツ：機能フラグ名は organization(内部的には organization:v1)です。Keycloak 26系ではデフォルト有効なので、明示的に --features=organization を付ける必要は基本的にありません。逆に使わない環境では --features-disabled=organization で無効化できます。バージョンによる差があるため、採用バージョンのEnabling and disabling featuresのページで有効状態を必ず確認してください。

02realm分割との違い — 何が「軽い」のか

realmとOrganizationの決定的な違いは、共有される範囲です。realmを分けると、ユーザーストア・クライアント・ロール・認証フロー・テーマ・署名鍵まで、すべてが独立します。テナント間で完全に隔離したいならこれは長所ですが、共通のアプリケーション(クライアント)を全テナントに提供したいSaaSでは、realmごとにクライアントを複製・同期する手間が発生します。

Organizationsでは、クライアント定義・認証フロー・ロール・テーマといったrealmレベルの資産を全組織で共有したまま、ユーザーの所属先と組織固有のIdP・ドメイン・属性だけをテナント単位で切り替えます。SaaSの典型である「アプリは1つ、顧客は多数」というモデルにきれいに一致します。

図：realm分割は設定・鍵まで複製されるのに対し、Organizationsは共通基盤を保ったままテナント境界だけを組織単位で切り替える。

02identity-firstログインフロー

Organizationsを有効にしたrealmでは、ログイン体験が変わります。従来のように「ユーザー名とパスワードを同一画面で」ではなく、まずメールアドレス(またはユーザー名)を入力させ、その結果に応じて次のステップを分岐させる「identity-firstログイン」が導入されます。

この分岐が重要です。入力されたメールのドメインが、ある組織に登録されたドメインと一致すれば、Keycloakはその組織に紐付いた外部IdPへユーザーをリダイレクトできます。一致しなければ通常のパスワード入力に進みます。「まず誰か(どの組織か)を確定してから、認証手段を決める」という順序が、マルチテナントの入口としてきれいに働きます。

現場のコツ：identity-firstフローは既存のブラウザフローに割り込む形で挙動が変わります。カスタム認証フローや独自Authenticatorを組み込んでいる環境では、Organizations有効化前に検証realmで一連のフローを通し、step-up認証やパスキーなどとの相互作用を必ず確認してください。ログイン画面のテーマ調整が必要になるケースもあります。

03メンバーシップ — managed と unmanaged

Organizationのメンバーには2種類あります。unmanaged memberは、realm内に独立して存在するユーザーを組織に紐付けたもので、組織との関連を外してもユーザー自体は残ります。一方managed memberは、組織を通じて(招待や組織IdP経由で)オンボードされ、ライフサイクルが組織に強く結び付いたメンバーです。組織から外れる/組織が削除されると、こうしたユーザーの扱いも連動します。

オンボーディングの経路は主に2つです。1つは招待(invitation)で、メールアドレスを指定して招待を送り、受諾したユーザーがメンバーになります。招待はデータベースに永続化され、Admin ConsoleとREST APIの双方からPending/Expiredといった状態を追跡・管理できます(この永続化と一覧管理は比較的新しいバージョンで強化された点です)。もう1つは後述する組織IdP経由で、外部IdPでの認証成功時に自動でアカウント作成と組織への所属を行う経路です。

既存ユーザーの追加:realmにいるユーザーを組織メンバーに加える(unmanaged寄り)。
招待:未登録者にメール招待を送り、受諾でメンバー化。状態は永続管理。
IdPオンボーディング:組織ドメインに一致する外部IdP認証で自動オンボード(managed寄り)。

04組織別IdPとドメイン

Organizationsの実務的な主役が、組織ごとの外部IdPとドメインの紐付けです。各組織には1つ以上のドメイン(例:example.co.jp)を登録でき、そのドメインを外部IdPに関連付けられます。ユーザーがidentity-first画面で tanaka@example.co.jp と入力すると、Keycloakはドメインからその組織を特定し、対応するIdP(顧客企業のAzure AD / Entra ID、ADFS、別のOIDCプロバイダなど)へリダイレクトします。

認証が成功すると、ユーザーはアカウントが自動作成され、その組織のメンバーとしてオンボードされます。B2B SaaSでよくある「顧客企業ごとに社内IdPでSSOさせたい」という要件が、realmを増やさずに実現できるわけです。IdPブローカリング自体の設計はIdentity Brokeringの記事、Entra ID/ADFS連携の勘所はSAML×ADFSの記事も併せて参照してください。

図：メール入力→ドメイン照合→組織IdPへリダイレクト→認証成功で自動オンボード。realmを増やさず顧客社内SSOを実現する。

05トークンへの組織情報の反映

アプリケーション側が「このユーザーはどの組織のコンテキストで認証したか」を知るには、トークンに組織情報を載せる必要があります。クライアントが組織スコープ(organization scope)を要求して認証すると、発行されるOIDCトークン(およびSAMLアサーション)に組織のクレームが含まれます。アプリはこのクレームを使ってテナントの識別やアクセス制御を行います。

スコープ・マッパーの構成はrealmレベルのクライアントスコープとして共有されるため、クライアントスコープとマッパー設計の考え方がそのまま効いてきます。組織を跨いで同じユーザーが複数組織に所属しうる設計では、「どの組織のコンテキストで発行されたトークンか」を明示的に扱う必要があるため、アプリ側の認可ロジックと合わせて早い段階で設計を固めておくのが安全です。

06Organization Groups(26.6以降)

2026年4月のKeycloak 26.6.0で、Organization Groupsが追加されました。これは組織ごとに独立したグループ階層を持てる機能です。従来のrealmグループは名前空間がrealm全体で共有されるため、複数組織で同名のグループ(例:/Engineering/Backend)を作れませんでした。Organization Groupsでは、Org AとOrg Bがそれぞれ独立した /Engineering/Backend を持て、メンバー・属性・識別子も別物として扱われます。

命名衝突の解消:組織スコープで隔離されるため、テナント間の同名グループが両立する。
federated userの自動振り分け:「Hardcoded Group」でIdP経由の全ユーザーを特定グループへ、「Advanced Claim to Group」で外部IdPのクレーム値(部署属性など)に応じて振り分けるマッパーが使える。
トークン反映:組織スコープを要求した認証では、グループメンバーシップが組織クレームのコンテキスト内(組織からの相対パス)としてOIDCトークン/SAMLアサーションに載る。

現場のコツ：Organization GroupsはあくまでテナントSaaSのメンバー整理・トークン反映が目的で、Keycloakの認可ポリシー(fine-grained authorization)には使えません。realm横断の細粒度認可が必要な要件はrealmグループやきめ細かい認可の枠組みで、テナント内のメンバー構造化はOrganization Groupsで、と役割を分けて設計するのが実務的です。

—まとめ：realm分割との使い分け

Organizationsは「realm分割か、共有realkか」の二択に、現実的な中間解を持ち込みました。判断の目安は次のとおりです。

Organizationsが向く:共通アプリを多数の顧客企業に提供するB2B/B2B2C SaaS。テナントごとに社内IdP(Entra ID/ADFS等)でSSOさせたいが、クライアントや認証フロー、テーマは共通で管理したい。テナント数が多く、realm増殖の運用が破綻しそう。
realm分割が向く:テナント間で署名鍵・認証フロー・テーマまで完全に隔離したい。規制やコンプライアンス上、データ・設定を物理的に分けたい。テナント数が少数で固定的。この判断軸はマルチrealm設計の記事で詳しく扱っています。

実際の案件では「基盤realmは1つ、その中でOrganizationsによりテナントを表現し、特別に隔離が必要な顧客だけ別realm」というハイブリッドに落ち着くこともあります。バージョン差(特にOrganization Groupsや招待の永続管理は新しめのバージョンで強化)があるため、採用バージョンの公式ドキュメントで機能範囲を確認したうえで設計してください。EMWではKeycloakでエンタープライズの認証基盤を実構築しており、こうした設計判断を含めて導入事例のような形で支援しています。

—参考(一次情報)

B2B SaaSやエンタープライズ向けのKeycloak認証基盤の設計でお困りの際は、実構築の実績を踏まえてお問い合わせください。

相談する

← ブログ一覧へ戻る