ロール・グループのマッピングとトークン反映の確認

目標

レルムロールとクライアントロール、グループ、コンポジットロールを作って、トークンにどのように載るかを自分で確認し、スコープでトークンを絞り込む方法まで身につけます。

なぜ重要なのか

「ロールを与えたのに、トークンに見えません」は、Keycloakを使うチームが必ず一度は経験する問題です。原因は、たいてい次の3つのどれかです。レルムロールとクライアントロールがトークンの異なるパスに入ることを知らない(realm_access.roles対resource_access.<클라이언트>.roles、プレースホルダーはクライアント名です)、クライアントのフルスコープの許可がオフになっている、グループの継承を期待していたのにマッピングされていない、という場合です。このラボでは、3つをそれぞれ作って、目で確認します。特にステップ7のスコープ制限は、トークンのサイズを減らして最小権限を守る実務の手法であると同時に、この問題の定番の原因でもあります。

ステップ

レルムlabhub2に、レルムロールorder-readerとorder-adminを作成してください。kcadm.sh get roles -r labhub2に、両方が表示されなければなりません。
クライアントapi-svcに、クライアントロールrefundを作成してください。
ユーザーdev1に、レルムロールorder-readerとクライアントロールrefundを付与してください。
dev1でパスワードグラントのトークンを受け取り、/root/kr/claims.jsonにペイロードを保存してください。realm_access.rolesにorder-readerが、resource_access.api-svc.rolesにrefundがなければなりません。
グループteam-paymentsを作成してレルムロールorder-adminをマッピングし、dev1をそのグループに入れてください。新しいトークンのrealm_access.rolesにorder-adminが現れなければなりません。/root/kr/group.txtにgroup=team-payments inherited=order-adminを書いてください。
order-adminをコンポジットロールにして、order-readerを含めてください。/root/kr/composite.txtにcomposite=true includes=order-readerを書いてください。
クライアントweb-appのfullScopeAllowedをfalseに変更し、そのクライアントで受け取ったトークンからorder-adminが外れるかを確認してください。/root/kr/scope.txtにfull_scope=false order_admin_in_token=falseを書いてください。

参考

ロールの付与: kcadm.sh add-roles -r labhub2 --uusername dev1 --rolename order-reader
クライアントロールの付与: kcadm.sh add-roles -r labhub2 --uusername dev1 --cclientid api-svc --rolename refund
トークンのペイロードは、2番目の断片をBase64URLデコードすれば得られます。
よくあるミス1: レルムロールをresource_accessで探すことです。
よくあるミス2: グループにユーザーだけを入れて、ロールのマッピングを忘れることです。グループ自体が権限を与えるわけではありません。

レルムロールを作る

レルムlabhub2に、レルムロールorder-readerとorder-adminを作成してください。kcadm.sh get roles -r labhub2に、両方が表示されなければなりません。

レルム全体で意味を持つロールです。2つ作っておけば、後でコンポジットとしてまとめられます。

クライアントロールを作る

クライアントapi-svcに、クライアントロールrefundを作成してください。

特定のクライアントの中でだけ意味を持ちます。サービスが複数あるときに、名前の衝突を防いでくれます。

ユーザーにロールを付与する

ユーザーdev1に、レルムロールorder-readerとクライアントロールrefundを付与してください。

付与コマンドでの対象の指定方法が、レルムロールとクライアントロールで異なります。

トークンにロールが載っているかを確認する

dev1でパスワードグラントのトークンを受け取り、/root/kr/claims.jsonにペイロードを保存してください。realm_access.rolesにorder-readerが、resource_access.api-svc.rolesにrefundがなければなりません。

レルムロールとクライアントロールが入るJSONのパスは、互いに異なります。

グループを作り、ロールをマッピングして、ユーザーを入れる

グループteam-paymentsを作成してレルムロールorder-adminをマッピングし、dev1をそのグループに入れてください。新しいトークンのrealm_access.rolesにorder-adminが現れなければなりません。/root/kr/group.txtにgroup=team-payments inherited=order-adminを書いてください。

ユーザー300人に個別に与える代わりに、グループに与えて、ユーザーを入れます。継承されます。

コンポジットロールを構成する

order-adminをコンポジットロールにして、order-readerを含めてください。/root/kr/composite.txtにcomposite=true includes=order-readerを書いてください。

ロールが他のロールを含みます。上位のロールだけを与えても、下位のロールも一緒に載るのが正常です。

スコープでトークンからロールを外してみる

クライアントweb-appのfullScopeAllowedをfalseに変更し、そのクライアントで受け取ったトークンからorder-adminが外れるかを確認してください。/root/kr/scope.txtにfull_scope=false order_admin_in_token=falseを書いてください。

クライアントのフルスコープの許可をオフにすると、マッピングされていないロールがトークンから外れます。