Keycloakでマルチテナントを設計するとき、最初に決めるのが「realmをどう切るか」です。顧客ごとに切るのか、環境で分けるのか、そもそも分けないのか。realmの独立性という強みは、そのまま運用負荷という重さにもなります。判断軸と、Organizationsという新しい選択肢との使い分けを整理します。
01まず「realmとは何を分離する単位か」を揃える
設計の議論に入る前に、realmという単位の定義を関係者で揃えておくと後の迷いが減ります。Keycloak公式のServer Administration Guideは、realmを「ユーザー、認証情報、ロール、グループの集合を管理する単位」と定義し、さらに "Realms are isolated from one another and can only manage and authenticate the users that they control." と明記しています。つまりrealmは、ユーザー空間・認証設定・ロール/グループ・鍵・IdP連携までをまるごと隔離する境界です。
この「まるごと隔離」という性質が、マルチテナント設計での最大の武器であり、同時に運用負荷の源泉でもあります。realmをテナント境界に使うと分離は極めて強固になりますが、realm単位で発生する設定・鍵・アップグレード検証がテナント数に比例して増えていきます。設計とは、この分離の強さと運用の重さのトレードオフをどこで取るか、という一点に集約されます。
02realmの切り方は大きく3パターン
マルチテナントでrealmをどう切るかは、実務上おおむね次の3つに整理できます。それぞれ独立性と運用負荷の位置づけが異なります。
- 顧客別realm(realm-per-tenant)：顧客企業ごとに1 realm。ユーザー空間・パスワードポリシー・IdP連携・ブランディングまで完全に分離できます。分離要件が厳しいB2Bエンタープライズで採用されやすい形です。
- 単一realm+テナント属性(shared realm)：全テナントを1 realmに収容し、グループ・ロール・属性でテナントを表現します。運用は軽い一方、テナント間のデータ隔離はアプリ側のクエリと認可に依存します。
- 環境別realm(env-per-realm)：本番・ステージング・開発でrealmを分ける切り方。テナント分離とは別軸で、テナント切りと組み合わせて使います。
環境別は多くの現場で採用されますが、テナント分離とは目的が違う点に注意します。環境別realmは「本番設定を検証で汚さない」ための分離であって、顧客間の分離ではありません。この2軸を混同すると、realm数が不必要に爆発します。
02の続き 参考
この番号付けミスを避けるため、以降は連番で続けます。実際の判断軸を次節から掘り下げます。
03realm間は「共有できない」ものが多い
顧客別realmを選ぶ前に、realmを跨いで共有できないものを正確に把握しておく必要があります。realmが独立している以上、次はrealmごとに個別管理になります。
- ユーザーとクレデンシャル：同じ人物が複数テナントに関わる場合、realmごとに別ユーザーになります。SSOもrealm単位です。
- 署名鍵(realm keys)：トークン署名鍵はrealm固有です。鍵ローテーションもrealmごとの運用になります。
- 認証フロー・パスワードポリシー・必須アクション：realmごとに定義。標準化したい場合は外部から流し込む仕組みが要ります。
- クライアント/クライアントスコープ/マッパー：realm境界を越えて共有できません。
- ロール・グループ：realmローカルです。テナント横断のロール体系は持てません。
逆に言えば、これらを「テナントごとに完全に別で運用したい」要件があるなら、顧客別realmは素直な答えです。顧客ごとにIdP(顧客のAzure ADやADFS)をフェデレーションし、パスワードポリシーやブランディングも顧客要件に合わせる——こうしたB2Bエンタープライズの典型要件では、realm境界がそのまま契約・責任分界の境界と一致します。IdP連携の具体はIdentity Brokeringの記事やLDAP/AD連携の記事も併せてご覧ください。
04共通設定をどう配るか——realm数が増えると効く
顧客別realmの弱点は、共通設定の横展開です。realmは独立しているため、「全テナント共通の認証フローを1箇所直したら全realmに反映」という操作が標準では効きません。テナントが5個なら手作業でも回りますが、30個、100個になると破綻します。ここを設計時に手当てするかどうかで、数年後の運用が変わります。
実務での定石は、realm設定をコード化(IaC)し、テンプレートから各realmを生成・更新する運用です。Keycloakは Admin REST API を備えており、realmのエクスポート/インポートJSONやTerraform Provider(keycloak provider)、あるいは自前スクリプトで、共通部分をテンプレート化してrealmごとにパラメータ差し込みする形が取れます。この設計にしておくと、「共通フローの変更を全realmへ順次適用」がパイプラインで回ります。
05テナント数が増えたときの運用負荷
顧客別realmは、テナント数の増加に対して運用コストがほぼ線形に増えます。見落としやすいのは、日々の運用ではなくアップグレードとキャパシティです。
- アップグレード検証：Keycloak本体は現行のQuarkusベース(旧WildFlyベースは非推奨)で、バージョンアップ時の互換確認が必要です。realmごとに認証フローやカスタムSPIの依存が違うと、検証マトリクスがrealm数だけ膨らみます。
- 鍵・証明書のローテーション：realmごとの署名鍵、IdP連携証明書の更新を、テナント数だけ管理する必要があります。
- キャパシティ：realm数そのものより、realmが増えると総ユーザー数・セッション数・キャッシュ量が増える点が効きます。Infinispanのキャッシュ設計やDB負荷は、テナント成長を見込んでサイジングします(キャッシュチューニング/DBチューニング参照)。
- 管理権限の委譲：テナントごとに管理者を分けたい場合、realm-management相当の権限設計が要ります。realm境界があると権限も自然に分離される一方、横断管理者の設計は別途必要です。
実案件では、この運用負荷を見越して「顧客別realmにするのは分離要件が明確な顧客だけ、それ以外は共通realmに寄せる」というハイブリッドを取ることが多いです。全テナントを一律に顧客別realmへ倒すと、契約規模の小さいテナントの運用コストが割に合わなくなります。統制の観点の全体像はマルチアカウント統制の考え方とも通じます。
06Organizationsという第三の選択肢
従来、Keycloakのマルチテナントは「realmで分ける」か「単一realmで属性管理」の二択でした。ここに公式が加えたのがOrganizations機能です。公式アナウンスは、この機能を "multi-tenancy when a realm needs to integrate with third parties such as customers and business partners" と位置づけ、B2B/B2B2CのCIAMユースケースを対象としています。
Organizationsは、realmを分けずに1つのrealm内で複数の組織(テナント)を表現する仕組みです。組織ごとのメンバー管理、招待リンクやブローカリングによるオンボーディング、トークンへの組織メタデータ付与を提供します。realmでOrganizations設定を有効にすると、認証フローが自動更新され、identity-first(メールアドレスなどで先にユーザーを識別してから認証先を切り替える)ログインが導入されます。この「識別してから認証」は、属性ベースの単一realm運用では作り込みが必要だった部分を標準化する点で大きい変化です。
公式の位置づけとしては、Keycloak 25でテクノロジープレビュー、26でサポート化という流れです。さらにKeycloak 26.6.0では Organization Groups が追加され、組織ごとに独立したグループ階層を持てるようになりました。公式は "Organization A's /Engineering/Backend and Organization B's /Engineering/Backend are completely separate groups" と説明しており、組織間でグループ名前空間が衝突しない設計です。グループメンバーシップはOIDCトークンやSAMLアサーションにも載せられ、/admin/realms/{realm}/organizations/{orgId}/groups のAdmin REST APIで自動化できます。バージョン依存が大きい領域なので、採用時は使用バージョンの公式ドキュメントで機能範囲を必ず確認してください。
07realm分割とOrganizationsの使い分け
三者をどう選ぶか。実務での判断軸を整理します。
- 顧客別realmが向くケース：テナントごとにパスワードポリシー・認証フロー・署名鍵・IdPを完全に分けたい。契約上、データと設定の分界を厳密にしたい。テナント数が限られており、IaCで運用が回る。
- 単一realm+Organizationsが向くケース：テナント数が多い、または増減が激しい。テナントを跨いだ共通の認証体験を1箇所で管理したい。B2B/B2B2Cで、顧客企業がメンバーを自己管理し、招待やIdPブローカリングでオンボードする。トークンに組織情報を載せてアプリ側で認可したい。
- 単一realm+素の属性管理が向くケース：Organizationsを使わない理由がある(旧バージョン固定など)、かつテナント分離要件がアプリ側の認可で十分に満たせる。
重要なのは、realm分割とOrganizationsは排他ではない点です。「事業ライン単位ではrealmを分け、その中の顧客企業はOrganizationsで表現する」といった二層構成も現実的です。分離の粒度を1段で決めず、事業構造に合わせて階層化すると、realm爆発を避けつつ必要な分離を確保できます。Organizations自体の詳細はOrganizationsの記事で個別に掘り下げます。
—まとめ
Keycloakのマルチテナント設計は、realmという「まるごと隔離する境界」をどこに引くかの判断に尽きます。realm分割は分離が強い反面、共通設定・鍵・アップグレード検証がテナント数に比例して重くなります。この重さをIaCで抑え込めるか、そもそもOrganizationsで単一realmに寄せられるか——分離要件と運用体制の両面から、テナントごとに粒度を選ぶのが実務解です。realm分割とOrganizationsを二層で組み合わせる設計も、選択肢として持っておくと引き出しが増えます。EMWはこの判断を実案件で重ねてきました。設計方針の壁打ちが必要でしたら導入事例もご参照ください。