KeycloakのRealmとは？初心者が最初につまずく概念を解説

この記事の最終更新日: 2026年5月25日

Keycloakを使い始めると、最初に出てくる重要な概念が Realm です。

管理画面を開くと、まずRealmを選ぶ必要があります。

しかし初心者のうちは、

Realmって何？
Clientとは何が違うの？
UserやRoleはRealmの中にあるの？
環境ごとにRealmを分けるべき？
サービスごとにRealmを分けるべき？

と混乱しやすいです。

KeycloakのRealmは、認証・認可の設定をまとめるための 管理単位 です。Keycloak公式ドキュメントでも、Realmはユーザー、認証情報、ロール、グループを管理する単位であり、ユーザーはRealmに所属してログインすると説明されています。さらに、Realm同士は分離されており、それぞれが管理するユーザーだけを認証できます。(Keycloak)

この記事では、KeycloakのRealmとは何か、なぜ初心者がつまずきやすいのか、どう設計すればよいのかをわかりやすく解説します。

Realmとは？

Realm とは、Keycloakの中でユーザー、アプリケーション、ロール、グループなどを管理するための空間です。

初心者向けに一言でいうと、Realmは 認証管理の箱 です。

Realm
├── User
├── Client
├── Role
├── Group
├── Identity Provider
└── 認証設定

Keycloak公式ドキュメントでは、Realmはユーザー、アプリケーション、ロール、グループなどのオブジェクトを管理する空間であり、1つのKeycloak環境に複数のRealmを作成できると説明されています。(Keycloak)

たとえば、次のようにRealmを分けられます。

社内システム用Realm
顧客向けサービス用Realm
開発環境用Realm
検証環境用Realm
本番環境用Realm

Realmを分けると、その中にあるユーザー、Client、Role、Groupなども分かれます。

つまり、RealmはKeycloakにおける 認証・認可設定の境界線 です。

Realmを「マンション」にたとえるとわかりやすい

Realmは、マンションやビルにたとえると理解しやすいです。

Keycloakサーバー = 建物全体
Realm = フロア・区画
User = その区画に入れる人
Client = その区画にある部屋・アプリ
Role = 入室権限
Group = 部署・チーム

1つのKeycloakサーバーの中に、複数のRealmを作れます。

Keycloakサーバー
├── master Realm
├── company-a Realm
├── company-b Realm
└── internal-system Realm

それぞれのRealmは分離されています。

たとえば、company-a Realmのユーザーは、基本的には company-b Realmのユーザーとは別管理です。

公式ドキュメントでも、Realmは互いに分離されており、自分が管理するユーザーだけを認証できると説明されています。(Keycloak)

master Realmとは？

Keycloakを起動すると、最初から master Realm があります。

このmaster Realmは、Keycloak全体を管理するための特別なRealmです。

初心者が注意すべきなのは、普段のアプリケーション用ユーザーをmaster Realmに作らない方がよい という点です。

master Realmは、Keycloak管理者用のRealmとして扱うのが基本です。

アプリケーション用には、新しくRealmを作成するのが一般的です。

master Realm
→ Keycloak管理者用

myapp Realm
→ アプリケーション利用者用

このように分けることで、Keycloak自体の管理者と、アプリケーションの一般ユーザーを混同しにくくなります。

Realmの中にあるもの

Realmの中には、Keycloakの主要な設定がまとまっています。

代表的なものは次の通りです。

公式ドキュメントでも、Realmはユーザー、アプリケーション、ロール、グループなどを管理する空間として説明されています。(Keycloak)

つまり、Realmを作るということは、単に名前付きの箱を作るだけではありません。

そのRealmの中で、どのアプリがログインを使うのか、どのユーザーがログインできるのか、どの権限を使うのかを管理することになります。

Clientとの違い

Realmと一緒に必ず出てくるのが Client です。

初心者は、RealmとClientの違いでつまずきやすいです。

結論から言うと、次の違いがあります。

Realm：認証管理の箱
Client：Keycloakを使うアプリケーション

たとえば、ECサイトをKeycloakで認証したい場合を考えます。

Realm: ec-service
Client: frontend-app
Client: admin-app
Client: backend-api

この場合、ec-service Realmの中に、複数のClientを作ります。

Clientは、Keycloakに認証を依頼するアプリケーションやサービスです。Keycloak公式ドキュメントでも、ClientはKeycloakにユーザー認証を依頼できるエンティティであり、多くの場合はKeycloakで保護したいアプリケーションやサービスだと説明されています。(Keycloak)

つまり、Realmは大きな管理単位で、Clientはその中に登録されるアプリケーションです。

Userとの関係

Userは、Realmに所属します。

たとえば、myapp Realmにユーザーを作成すると、そのユーザーは myapp Realmでログインします。

myapp Realm
├── user01
├── user02
└── user03

別のRealmに同じメールアドレスのユーザーを作ることもできますが、それは別Realmの別ユーザーとして扱われます。

dev Realm
└── taro@example.com

prod Realm
└── taro@example.com

この2つは、同じメールアドレスでも別Realmのユーザーです。

公式ドキュメントでも、ユーザーはRealmに所属してログインすると説明されています。(Keycloak)

この性質を理解していないと、「同じKeycloakにユーザーを作ったのに別のアプリでログインできない」という混乱が起きます。

実際には、アプリがどのRealmを見ているかが重要です。

Roleとの関係

Roleは、Realmの中で定義される権限です。

たとえば、次のようなRoleを作れます。

admin
user
manager
viewer
editor

Roleには、大きく分けて Realm Role と Client Role があります。

Realm Role
→ Realm全体で使う権限

Client Role
→ 特定のClient向けの権限

たとえば、社内システム全体で使う admin や employee のような権限はRealm Roleとして扱いやすいです。

一方で、特定アプリだけに関係する article-editor や billing-viewer のような権限はClient Roleとして扱う方が自然な場合があります。

初心者のうちは、まず次のように理解するとよいです。

Realm Role：全体的な役割
Client Role：アプリごとの役割

Groupとの関係

Groupは、ユーザーをまとめるための仕組みです。

たとえば、次のようなGroupを作れます。

管理者グループ
営業部
開発部
有料会員
外部パートナー

Keycloakでは、GroupにRoleを割り当てることもできます。

Group: 管理者グループ
└── Role: admin

このGroupにユーザーを入れると、そのユーザーはGroupに紐づいたRoleを受け継げます。

公式ドキュメントでも、Groupはユーザーのグループを管理し、GroupにRoleを割り当てることができ、Groupに所属するユーザーはその属性やRoleマッピングを継承すると説明されています。(Keycloak)

ユーザーごとにRoleを直接付けるより、Groupで管理した方が運用しやすいことがあります。

Realmを分けるべきケース

Realmは便利ですが、何でもかんでも分ければよいわけではありません。

まずは、Realmを分けるべき代表的なケースを見ていきます。

1. 環境を分けたい場合

開発環境、検証環境、本番環境を分けたい場合、Realmを分けることがあります。

myapp-dev
myapp-stg
myapp-prod

このように分けると、開発用ユーザー、本番用ユーザー、Client設定、Role設定などを分離できます。

ただし、環境ごとにKeycloakサーバー自体を分ける運用もあります。

開発用Keycloak
検証用Keycloak
本番用Keycloak

どちらがよいかは、システム規模や運用方針によります。

初心者向けには、まず次のように考えるとよいです。

小規模な検証：Realmで環境を分ける
本格的な本番運用：Keycloak環境自体を分けることも検討する

2. 顧客・組織ごとに完全分離したい場合

SaaSのように、顧客ごとにユーザーや設定を完全に分けたい場合、Realmを分けることがあります。

customer-a Realm
customer-b Realm
customer-c Realm

このようにすると、顧客Aのユーザーと顧客BのユーザーをRealm単位で分離できます。

Realmは互いに分離されるため、ユーザー、Role、Group、Client設定を分けて管理できます。(Keycloak)

ただし、顧客数が非常に多い場合、Realmを大量に作る設計が運用上つらくなる可能性もあります。

その場合は、1つのRealm内でGroupや属性を使ってテナントを分ける設計も検討します。

3. 認証ポリシーを大きく変えたい場合

Realmごとにログイン設定や認証フローを変えられます。

たとえば、次のような違いがある場合です。

社内ユーザーは二要素認証必須
外部ユーザーはメール認証必須
管理者はより厳しい認証フロー
顧客向けサービスはソーシャルログインあり
社内システムはAzure AD連携

認証方式やログインポリシーが大きく違うなら、Realmを分ける意味があります。

Realmを分けない方がよいケース

一方で、Realmを分けすぎると管理が複雑になります。

次のような場合は、Realmを分けない方がよいこともあります。

同じユーザーが複数アプリを使う
SSOを効かせたい
RoleやGroupを共通管理したい
アプリ間で認証体験を統一したい
単にアプリが複数あるだけ

たとえば、社内に複数のアプリがある場合でも、同じ社員がすべて使うなら、1つのRealmに複数Clientを作る方が自然なことがあります。

internal Realm
├── attendance-app
├── expense-app
├── crm-app
└── admin-app

この構成なら、同じRealmの中でSSOしやすく、ユーザーやRoleも共通管理しやすいです。

初心者におすすめのRealm設計

初心者は、まず次の方針で考えるとわかりやすいです。

1つのサービス・組織 = 1つのRealm
その中に複数のClientを作る

たとえば、次のような構成です。

my-company Realm
├── staff-web-app
├── admin-web-app
├── mobile-app
└── backend-api

この場合、同じ会社・同じサービス内のアプリケーションを1つのRealmにまとめます。

ユーザーやRoleを共通管理しやすく、SSOも考えやすくなります。

逆に、まったく別のサービスや、ユーザーを完全に分けたい組織がある場合は、Realmを分けることを検討します。

Realm設計の判断基準

Realmを分けるかどうか迷ったら、次の質問をするとよいです。

ユーザーを完全に分けたいか？
SSOを共有したいか？
RoleやGroupを共有したいか？
ログイン画面や認証フローを分けたいか？
外部IdP連携を分けたいか？
管理者を分けたいか？
本番・検証・開発をどこまで分離したいか？

判断の目安は次の通りです。

Realmは「分ければ安全」という単純なものではありません。

分けるほど独立性は高まりますが、管理対象も増えます。

Realmを分けすぎるデメリット

Realmを分けすぎると、次のような問題が出ます。

同じRoleを複数Realmに作る必要がある
同じClient設定を何度も作る必要がある
ユーザー移行が面倒になる
Realmごとの設定差分を管理しづらい
運用ルールが複雑になる
管理画面で探しにくくなる

たとえば、開発・検証・本番でRealmを分けた場合、同じClientやRoleをそれぞれ作る必要があります。

myapp-dev Realm
└── admin-app Client

myapp-stg Realm
└── admin-app Client

myapp-prod Realm
└── admin-app Client

この構成自体は悪くありません。

しかし、設定差分をどう管理するかを考えないと、「devでは動くがprodではログインできない」という問題が起きます。

本格的に運用するなら、Realm設定のエクスポート・インポートやIaC化も検討したくなります。

RealmとURLの関係

Keycloakでは、Realm名がURLに含まれます。

たとえば、Realm名が myapp の場合、OpenID Connect関連のURLには次のようにRealm名が入ります。

/realms/myapp

KeycloakのAdmin REST APIでも、URIスキームとして {base url}/admin/realms が使われ、Realm名をパスに含めるAPIが定義されています。(Keycloak)

つまり、アプリ側のOIDC設定では、どのRealmを使うかが非常に重要です。

よくある設定項目としては、次のようなものがあります。

Issuer URL
Authorization Endpoint
Token Endpoint
JWKS URL

これらにはRealm名が含まれます。

そのため、アプリ側が dev Realmを見ているのか、prod Realmを見ているのかを間違えると、ログインできない、トークン検証に失敗する、といった問題が起きます。

Realm名の付け方

Realm名は、後からアプリ設定やURLにも関わるため、わかりやすい名前にするのがおすすめです。

悪い例です。

test
new
realm1
sample
prod2

よい例です。

myapp-dev
myapp-stg
myapp-prod
internal
customer-a
medical-records-stg

Realm名を見ただけで、どのサービス・環境なのかがわかるようにしましょう。

特にチーム開発では、命名ルールを決めておくと混乱しにくくなります。

RealmとSSOの関係

SSOを考える場合、Realmの分け方は重要です。

基本的に、同じRealm内のClient同士はSSOを構成しやすいです。

internal Realm
├── app-a
├── app-b
└── app-c

この場合、ユーザーはKeycloakに一度ログインすれば、同じRealm内の複数Clientでログイン状態を共有しやすくなります。

一方で、Realmを分けると、認証の境界も分かれます。

realm-a
└── app-a

realm-b
└── app-b

この場合、アプリAとアプリBは別Realmの認証を使うため、SSOの扱いも別になります。

そのため、「複数アプリで同じログイン体験にしたい」のか、「完全に分離したい」のかを先に決める必要があります。

開発・検証・本番でRealmをどう分けるか

現場でよくある悩みが、開発・検証・本番のRealm設計です。

主なパターンは2つあります。

パターン1：1つのKeycloak内でRealmを分ける

Keycloak
├── myapp-dev
├── myapp-stg
└── myapp-prod

この方法は、検証や小規模運用ではわかりやすいです。

ただし、本番と開発が同じKeycloakサーバーに同居するため、運用面では注意が必要です。

パターン2：環境ごとにKeycloak自体を分ける

開発用Keycloak
└── myapp

検証用Keycloak
└── myapp

本番用Keycloak
└── myapp

本番運用では、こちらの方が分離度は高いです。

本番環境と開発環境の影響範囲を分けやすくなります。

ただし、Keycloak環境自体が増えるため、運用コストは上がります。

初心者向けには、まずローカルや検証環境でRealmを分けて練習し、本番ではより慎重に構成を考えるのがおすすめです。

Realmでよくあるつまずき

1. master Realmにアプリ用ユーザーを作ってしまう

master RealmはKeycloak管理用として扱うのが基本です。

アプリケーション用には、新しいRealmを作りましょう。

NG: master Realmに一般ユーザーを作る
OK: myapp Realmを作って一般ユーザーを管理する

2. RealmとClientを混同する

Realmは認証管理の箱です。

ClientはKeycloakを使うアプリです。

Realm: myapp
Client: frontend
Client: backend-api

この違いを理解すると、Keycloakの管理画面がかなり読みやすくなります。

3. 別Realmのユーザーでログインしようとする

ユーザーはRealmに所属します。

そのため、dev Realmに作ったユーザーでは、prod Realmのログインには使えません。

dev Realmのuser01
≠
prod Realmのuser01

同じユーザー名でも、Realmが違えば別ユーザーです。

4. Redirect URIのRealmを間違える

アプリ側のKeycloak設定でRealm名を間違えると、ログインが失敗します。

特に、開発・検証・本番でRealmを分けている場合は注意が必要です。

/realms/myapp-dev
/realms/myapp-stg
/realms/myapp-prod

設定ファイルや環境変数でRealm名を切り替えられるようにしておくと安全です。

5. RoleをどのRealmに作ったかわからなくなる

Realmを分けると、RoleもRealmごとに管理されます。

そのため、dev Realmに作ったRoleは、prod Realmには存在しません。

環境ごとに必要なRoleを揃える仕組みがないと、環境差分でハマります。

初心者がまず作るべきRealm構成

Keycloak初心者が学習するなら、まずはシンプルな構成で十分です。

Realm: demo
Client: demo-web
User: test-user
Role: user

最初から複数Realm、複数Client、外部IdP連携、複雑なRole設計を入れると混乱します。

まずは次の流れを体験しましょう。

Realmを作る
↓
Clientを作る
↓
Userを作る
↓
Roleを作る
↓
UserにRoleを付ける
↓
アプリからログインする

この一連の流れを理解すると、Realmの意味がかなり見えてきます。

Realm設計のベストプラクティス

初心者向けに、Realm設計の基本方針をまとめると次の通りです。

master Realmは管理用として扱う
アプリ用には新しいRealmを作る
同じユーザー・SSOを共有したいアプリは同じRealmにまとめる
完全に分離したいサービスや組織はRealmを分ける
Realmを分けすぎない
環境名・サービス名がわかるRealm名にする
本番環境ではKeycloak環境自体の分離も検討する

特に大事なのは、Realmは認証・認可の境界線 だと考えることです。

この境界線をどう切るかによって、SSO、ユーザー管理、Role管理、運用のしやすさが変わります。

Realmを理解するとKeycloak全体が見えやすくなる

Keycloakは、最初は用語が多くて難しく感じます。

しかし、Realmを理解すると全体像がつかみやすくなります。

Realm
├── 誰がログインするか：User
├── どのアプリが使うか：Client
├── 何を許可するか：Role
├── どうまとめるか：Group
└── どうログインするか：Authentication / Identity Provider

Realmは、Keycloakの主要な概念をまとめる土台です。

そのため、Keycloakを学ぶときは、まずRealmをしっかり理解するのがおすすめです。

まとめ

KeycloakのRealmは、ユーザー、Client、Role、Group、認証設定などを管理するための空間です。

初心者向けに言うと、Realmは 認証管理の箱 です。

Keycloak公式ドキュメントでも、Realmはユーザー、認証情報、ロール、グループを管理する単位であり、ユーザーはRealmに所属してログインすると説明されています。また、Realm同士は互いに分離されています。(Keycloak)

初心者がまず押さえるべきポイントは次の通りです。

Realm：認証管理の箱
Client：Keycloakを使うアプリ
User：Realmに所属してログインする人
Role：ユーザーやアプリに与える権限
Group：ユーザーをまとめる単位

Realm設計で迷ったら、次の基準で考えましょう。

同じユーザー・SSOを共有したいなら同じRealm
完全に分離したいなら別Realm
アプリが複数あるだけなら、まずは同じRealmに複数Client
master Realmは管理用として扱う

Realmを理解できると、Keycloakの管理画面やClient設定、Role設計、SSO構成がかなりわかりやすくなります。

daigoro

大阪のエンジニアが書いているブログ。