Keycloakは UMA 2.0 に準拠した認可サーバーとして、リソース所有者自身が他のユーザーへアクセス許可を委ねる「ユーザー主導の共有」を提供します。permission ticket と RPT の流れ、Protection API、そして現実的な採否判断まで、実装者の視点で整理します。
01UMA 2.0が解く「誰が許可を出すのか」問題
通常のOAuth2では、あるユーザー(リソース所有者)が、クライアントアプリケーションに対して自分のリソースへのアクセスを同意します。同意の相手はあくまで「自分の代わりに動くアプリ」です。ところがエンタープライズの現場では、これと似て非なる要求が頻繁に出てきます。「Aさんが所有するドキュメントを、Aさん自身の操作でBさんに共有させたい」というものです。ここで許可を出す主体は管理者でもアプリでもなく、リソース所有者本人です。
この「ユーザー同士の、非同期な、本人主導のアクセス許可」を標準化したのが User-Managed Access(UMA)2.0 です。KeycloakはAuthorization Servicesの一部として UMA 2.0 準拠の認可サーバー機能を備えており、公式ドキュメントは次のように述べています。UMAでは permission ticket が person-to-person(人対人)の共有、および person-to-organization(人対組織)の共有を支える中核であり、OAuth2がクライアントへの同意であるのに対し、UMAではリソース所有者が他のユーザーへ、完全に非同期な形でアクセスを許可できる、と。
02登場人物と用語を実装者の言葉で整理する
UMAは仕様が抽象的で、用語で挫折しがちです。Keycloakの実装に即して最小限に翻訳します。
- リソースサーバー：保護対象を持つアプリのバックエンド。Keycloak上ではAuthorization有効化したクライアントに対応します。
- リソース所有者(resource owner)：共有元のエンドユーザー。管理者ではありません。
- リクエスティングパーティ(requesting party)：共有先のエンドユーザー、あるいはその代理クライアント。
- permission ticket：UMA仕様が定義する特殊なトークン。「要求されているリソース/スコープ、アクセスコンテキスト、そして認可データ(RPT)発行のために適用すべきポリシー」を表す、形式は認可サーバーが決める不透明(opaque)な構造体です。
- RPT(Requesting Party Token)：許可済みのpermissionを内包したアクセストークン。Keycloakでは「permissionを持つアクセストークン」をRPTと呼びます。
- Protection API：リソースサーバーがリソース・スコープ・permission・ポリシーを管理するためのUMA準拠エンドポイント群。利用には
uma_protectionスコープが必要です。
混同しやすいのが、ユーザーが持つ uma_authorization というレルムロールです。これはデフォルトロールとして各ユーザーに付与され、認可フローに関与します。これを不用意に外すとログインや認可要求に影響が出るため、UMAを使わない場合でも安易な削除は避けてください。
03permission ticketからRPTへ:認可フローの全体像
UMAのフローは、初見だと往復が多く見えます。しかし要は「まず門前払い(チケット付き)→ そのチケットを認可サーバーに持ち込んでRPTを得る → RPTで再アクセス」という3段構えです。図で掴んでください。
最後の5番が要です。クライアントは Keycloak のトークンエンドポイントに対し、グラントタイプ urn:ietf:params:oauth:grant-type:uma-ticket と、受け取った ticket を送ります。ポリシー評価が通ればRPTが返り、通らなければ拒否またはクレーム収集(claim gathering)へと進みます。
04所有者がリソースを共有する:アカウントコンソールの「My Resources」
UMAが管理者不在で回る鍵は、リソース所有者本人がKeycloakのアカウントコンソールから共有を操作できる点にあります。Keycloak自身が sharing management service(共有管理サービス)として振る舞い、所有者は共有先ユーザーのユーザー名またはメールアドレスを入力し、付与したいpermission(スコープ)を選んで共有します。公式ドキュメントの表現どおり、これはOAuth2のクライアントへの同意とは異なり、所有者が他のエンドユーザーへ、非同期に、本人の意思でアクセスを許可する仕組みです。
裏側では、この共有操作が Protection API の Policy API / Permission API を通じてUMA policyやpermission ticketの承認として記録されます。所有者は同じ画面から、誰にどのスコープを渡しているかの一覧確認と取り消し(revoke)も行えます。運用上はこの「取り消し導線が所有者の手元にある」ことが監査・ガバナンス面で効いてきます。
05Protection APIとpermission requestの扱い
リソースサーバー側の実装で触るのが Protection API です。役割は大きく3つあります。
- Resource Registration：保護対象リソースとそのスコープをKeycloakに登録・更新・削除する。所有者(owner)を明示することで、そのリソースをユーザー所有にできます。
- Permission(ticket)管理：リソースサーバーがpermission ticketを発行(issue)する。前掲フローの2〜3番に相当します。所有者による共有承認・拒否といったpermission requestの作成・参照・更新・削除もここで行います。
- Policy API：ユーザー主導のpermission(UMA policy)をプログラム的に管理する。共有の付与・取り消しをアプリから自動化したい場合の入口です。
Protection APIの呼び出しには、クライアントに uma_protection スコープが与えられていることが前提です。実装では、リソースサーバー自身のサービスアカウントトークン(client_credentials)でこのAPIを叩くのが定石です。ユーザーのトークンで叩くのはowner-managedな共有承認など限定的な場面に留めると、権限境界が明確になります。
06RPTの検証とpermissionの取り出し
RPTを受け取ったリソースサーバーは、それを検証してどのpermissionが実際に付与されたかを判断します。Keycloakは token introspection エンドポイントを提供しており、RPTのactive状態と、Keycloakが付与したpermission群を取得できます。RPT内のpermissionは、リソース名/リソースIDとスコープの組で表現されます。
実装上の判断ポイントは「RPTをどこまで信頼して素通しするか」です。RPTは署名付きJWTとして扱えますが、失効(共有取り消し)を即時反映したい要件があるならintrospectionでの都度確認が必要になり、レイテンシとKeycloakへのRPS(1秒あたりリクエスト数)が増えます。ここは Infinispanキャッシュのチューニング や 可観測性の設計 と併せて負荷を見積もってください。UMAはトークン検証の回数が素のOIDCより増えがちだという前提で容量計画を立てるのが安全です。
07バージョン差と実装上の注意
Authorization ServicesとUMAサポート自体は長く安定して提供されている機能ですが、周辺は動いています。現行はQuarkusベースのディストリビューション(およびRed Hat build of Keycloak)が基準で、旧WildFlyベースは非推奨です。Quarkusディストリビューションへの移行を終えていない環境では、まずそこから着手してください。設定キーやアカウントコンソールのUI(Account Console v2/v3系)はバージョンで差があるため、共有UIの見た目や画面遷移は必ず利用中バージョンの公式ドキュメントで確認するのが安全です。
- Protection APIのエンドポイントパスやレスポンス形は概ね安定していますが、細部はマイナーバージョンで変わり得ます。新しめのバージョンを基準に、実環境のwell-known(
uma2-configuration)から実際のエンドポイントを引くのが確実です。 - claim gatheringやJavaScriptポリシーの可否・挙動はバージョンやビルド設定に依存します。特にJavaScriptポリシーはセキュリティ上デフォルト無効な構成があるため、有効化可否を含め公式で要確認です。
- 大規模共有ではpermission ticketやポリシー評価がDBとキャッシュに負荷をかけます。データベースチューニングと併読を推奨します。
08現実的な採否判断:UMAを選ぶ・選ばない
UMAは強力ですが、万能薬ではありません。実案件でのEMWの判断軸を共有します。
UMAが向くケース：ファイル共有、予約枠の代理管理、IoTデバイスの所有者間貸与など、「エンドユーザーが自分の持ち物を、その場で、別のエンドユーザーに」渡すユースケース。許可の主体が本人で、相手が動的に決まり、非同期な承認・取り消しが要件に含まれるとき、UMAは仕様が要件に素直に噛み合います。
UMAを避けるべきケース：許可の主体が管理者やロール設計であるとき、あるいは共有相手が固定的で組織構造から決まるときは、UMAの往復とpermission ticketの管理コストが割に合いません。この場合は fine-grained authorization のリソース/スコープ/ポリシーだけで組む、あるいはロール・グループ・属性で表現する方が、運用も検証もはるかに楽です。マルチアカウント統制のようなガバナンス主導の要件も、UMAより集中管理型の設計が適します。
—まとめ
UMA 2.0は「所有者本人が、その場で、相手を指名して、非同期に許可を出す」という、OAuth2では表現しづらい共有を標準化した仕組みです。Keycloakはpermission ticket・RPT・Protection API・アカウントコンソールの共有UIという形でこれを実装として提供します。鍵は仕様の網羅ではなく、自分の要件が本当に「本人主導・動的・非同期」なのかの見極めと、RPT検証の負荷・失効即時性・監査要件を数字で押さえることです。そこさえ外さなければ、UMAは実運用に耐える強力な選択肢になります。