Role・Group・Attribute — Keycloak権限モデルの設計指針

Keycloakには権限を表現する手段が複数あります。realm role、client role、composite role、group、そしてuser attribute。どれを使うかで、数年後の運用しやすさが大きく変わります。本稿では各要素の役割とトークンへの載り方を踏まえ、破綻しない設計指針を整理します。

Keycloakで認証基盤を組むとき、最初の設計判断でありながら後から効いてくるのが「権限を何で表現するか」です。同じ「営業部の課長だけがこの画面を使える」という要件でも、realm roleで表すか、group継承で表すか、user attributeで条件分岐するかで、運用負荷もトークンの中身もまったく変わります。本稿ではKeycloakが提供する各手段の性質を、公式ドキュメントの定義に沿って整理し、破綻しない設計指針を示します。バージョンはQuarkus版の新しめのリリース(26系)を前提としますが、モデルの基本概念はバージョン間で大きく変わりません。挙動の細部は必ずお使いのバージョンの公式ドキュメントでご確認ください。

014つの部品を正しく区別する

まず用語を揃えます。Keycloakで権限に関わる部品は、大きく4つです。混同したまま設計すると必ず破綻するので、定義を厳密に押さえます。

• realm role — realm全体に適用されるロール。realm内のどのユーザー・どのクライアントにも割り当て可能な、横断的な権限カテゴリです。
• client role — 特定クライアントに属するロール。公式は「a role namespace dedicated to the client(そのクライアント専用のロール名前空間)」と表現しています。アプリごとにeditorやviewerが衝突せず定義できます。
• composite role — 他のロールを内包するロール。superuserにsales-adminとorder-entry-adminを紐付ければ、superuserを付与されたユーザーは両者を継承します。
• group — ユーザーの集合。属性(attribute)とロールマッピングを持ち、メンバーになったユーザーはそれらを継承します。

加えて、ユーザーとグループはそれぞれ任意のattribute(キーと値)を持てます。email・部署コード・費用センターといった「属性情報」を保持する箱です。ここまでが道具立てです。

02Role と Group は役割が違う

最頻出の混乱が「roleとgroup、どっちで権限を管理するのか」です。公式のServer Administration Guideは「Groups compared to roles」という独立した節を設け、両者を意図的に区別しています。整理するとこうです。

• role は「権限の種類」を表す。アプリが「このロールを持つ人だけ許可する」という判断に使う、アクセス制御の単位です。
• group は「ユーザーの束ね方」を表す。組織構造や職務のまとまりで人を集め、そこにroleや属性をまとめて付与する器です。

設計指針としては、権限そのものはroleで定義し、そのroleをgroupにマッピングして人に配るのが基本形です。ユーザーに直接roleを付けるのではなく、groupを経由させることで「異動＝group移動」だけで権限が付け替わり、棚卸しも「このgroupに誰がいるか」で完結します。逆に、group名をそのままアプリの認可判断に使うのはアンチパターンです。組織変更でgroup構造が変わるたびにアプリ側の判定ロジックが壊れます。group構造は組織都合で変わる前提、role体系はアプリ都合で安定させる前提——この非対称を意識すると設計がぶれません。

03group継承と、roleの継承経路

groupは階層構造を持てます。/営業の下に/営業/東日本を作れば、子グループのメンバーは親グループのattributeとロールマッピングを継承します。ロール解決の観点で重要なのは、公式が明言している通り、ユーザーの実効ロールが「direct roles set to the user, its groups and their parent groups(ユーザー直付けのロール＋所属グループ＋その親グループ)」から合成される点です。つまり最終的な権限は、次の3経路の和集合になります。

• ユーザーに直接付与されたrole
• 所属groupにマッピングされたrole(親groupのぶんも継承)
• 上記roleがcomposite roleだった場合、その内包roleすべて

この「3経路 × composite展開」の掛け算が、Keycloak権限設計の勘所です。表現力は高いのですが、経路が増えるほど「なぜこの人にこの権限があるのか」の追跡が難しくなります。破綻を避けるには、継承経路を意図的に絞ることです。実務では「roleの付与はgroup経由に一本化し、ユーザー直付けは例外運用のみ」「composite roleのネストは1〜2段まで」といったルールを最初に決めておくと、後の監査が楽になります。

04attribute は「権限」ではなく「文脈」

3つ目の混乱が「attributeで権限を表現していいか」です。結論から言うと、attributeを認可の主軸に据えるのは推奨しません。attributeはあくまで属性情報(部署コード、費用センター、社員区分など)を保持する箱であって、Keycloakのロールベース・アクセス制御(RBAC)の一次市民ではないからです。

ただしattributeが無力なわけではありません。適材適所は次の通りです。

• 属性情報の保持 — 従業員番号や所属コードなど、アプリが「権限判断ではなく参照値として」使いたい情報。これはattributeの本来の用途です。
• トークンへの追加claim — protocol mapperでattributeをclaimとして載せ、アプリ側でビジネスロジックに使う。
• 属性ベースのポリシー — Authorization Services(fine-grained authz)で、role判定に加えて属性条件を組み合わせる高度なケース。詳細はマルチアカウント統制のような横断ガバナンスとあわせて設計します。

逆に、「role=adminというattributeを付けてアプリがそれを見る」ような設計はやめるべきです。それはroleでやるべき仕事をattributeで代替しているだけで、Keycloakの標準的なrole mapperやスコープ制御の恩恵をすべて捨てることになります。権限はrole、属性はattribute——この境界を最初に引くことが、後の破綻を防ぎます。

05トークンにどう載せるか

設計したrole・group・attributeは、そのままではアプリに届きません。アプリが受け取るのはOIDCトークン(またはSAMLアサーション)であり、そこに何を載せるかはクライアントごとのprotocol mapperで制御します。公式が言う通り「for each client you can tailor what claims and assertions are stored in the OIDC token(クライアントごとにトークンに格納するclaimを調整できる)」わけです。代表的なものを挙げます。

• realm rolesのmapper — UserRealmRoleMappingMapperが、ユーザーのrealm roleをID/Accessトークンのclaimにマッピングします。
• client rolesのmapper — クライアント単位のroleを対象claim(慣例ではresource_access配下)に載せます。
• group membershipのmapper — groupの名前またはパスを、指定したclaim名に載せます。アプリがgroup情報を参照したい場合に使いますが、前述の通りアプリの認可判断にgroupパスを直接使うのは避けます。
• attributeのmapper — user attributeを任意のclaim名に載せます。

ここで効いてくるのが「トークンに載るroleは何か」の制御です。KeycloakにはFull Scope Allowedという設定があり、管理コンソールで作成した新規クライアントでは既定で有効になっています(既定で無効になるのはClient Registration Service経由で作成したクライアントに限られます)。有効のままだと、そのクライアントはrealm内の全roleやスコープ外のroleまでトークンに載せてしまうため、推奨は明示的にオフにし、Scopeタブで必要なrealm roleだけを許可することです。オフにすれば、client scopeで明示的に許可したroleだけがトークンに載ります(合成roleも展開対象として考慮されます)。これは単なる好みの問題ではなく、トークンの肥大化を防ぐ実務的なレバーでもあります。

06トークンが太る問題を設計で防ぐ

role設計が破綻する典型が「トークンが巨大化する」です。composite roleを多用し、全roleを全クライアントに載せる設定にすると、Accessトークンに数十〜数百のroleが並び、ヘッダサイズ制限に抵触したり、ネットワーク往復のたびに無駄な帯域を食ったりします。対策は設計段階で打てます。

• Full Scope Allowedを明示的にオフにする — 既定で有効なので忘れずにオフにし、client scope経由で「そのアプリが本当に必要とするrole」だけを載せます。
• client scope + scopeパラメータで条件付き付与 — 公式が示す通り、claimやroleをscopeパラメータの値に応じて条件的に載せられます。全部を常時載せる必要はありません。
• audience単位でclient roleを絞る — audienceパラメータで対象クライアントを指定すると、そのクライアントのclient roleだけにフィルタされます。マイクロサービス間で相手ごとに必要なroleだけを渡す設計に有効です。
• Lightweight Access Tokenの活用 — 26系ではadmin-consoleなど一部の内蔵クライアントで軽量アクセストークンが既定になっています。自前クライアントでも、必要最小限のclaim構成を検討する価値があります。

07マルチテナントとOrganization Groups

SIer案件では「1つのrealmで複数の顧客組織を収容したい」というマルチテナント要件がしばしば出ます。従来、realm直下のgroupを組織ごとに切ると、/Engineering/Backendのような同名パスが組織間で衝突し、cross-organization leakage(組織をまたいだ情報漏れ)のリスクがありました。

これに対しKeycloak 26.6.0で導入されたのがOrganization Groupsです。Organizations機能に階層的なグループ管理を持ち込み、公式の言葉を借りれば「Organization Aの/Engineering/BackendとOrganization Bの/Engineering/Backendは完全に別のグループ」として、組織ごとに独立した階層・メンバー・attributeを持てます。group membershipは組織claimの中でOIDCトークン/SAMLアサーションに載ります。

ただし設計上の注意があります。公式が明記する通り、Organization GroupsはKeycloakのauthorizationポリシー(Authorization Services)では使えません。つまりテナント分離の構造化には使えても、そのまま細粒度認可の判定材料にはできないということです。マルチテナントを組む際は、テナント境界をOrganization Groupsで表し、テナント内の権限は従来通りrealm/client roleで表す、という役割分担が現実解になります。realm自体を分けるかどうかの判断とあわせて、テナント設計の初期に決めておくべき論点です。

—まとめ：破綻しない設計のチェックリスト

Keycloakの権限モデルは表現力が高いぶん、放っておくと経路が絡み合って破綻します。最後に、設計時に立ち返る指針をまとめます。

• 権限はrole、束ねはgroup、属性はattribute。境界を混ぜない。
• roleの付与はgroup経由に一本化し、ユーザー直付けは例外運用のみ。
• アプリが認可判断に見るのはroleに限定。groupパスやattributeを直接if文に使わない。
• composite roleのネストは浅く保つ(目安1〜2段)。継承経路を追える状態を維持。
• トークンにはそのアプリが必要とするroleだけを載せる。Full Scope Allowedは既定で有効なので明示的にオフにする。
• マルチテナントはOrganization Groupsで境界を表し、テナント内権限は従来のroleで表す。

これらは机上論ではなく、運用フェーズで棚卸しや監査、組織変更に耐えるための実務指針です。関連して、認可フローの組み立ては認証フロー設計、細粒度の認可はFine-Grained Authorization、トークン発行時のclaim整形はClient ScopesとMapperの各記事もあわせてご覧ください。EMWの実案件事例は導入事例にまとめています。

—参考(一次情報)

• Keycloak Server Administration Guide — Roles、Groups(compared to roles)、Attributes、Role mappingsの定義
• Keycloak Authorization Services Guide — RBAC、realm/client roleを用いたポリシー、属性ベース認可
• UserRealmRoleMappingMapper (Keycloak Javadoc) — realm roleをトークンclaimにマッピングするmapper、ロール解決の経路
• Organization Groups: Structure Your Organizations with Hierarchical Group Management — Keycloak 26.6.0で導入された組織単位の階層グループ