Authorization Services Guide

アプリケーションに対するきめ細かな認可を可能にするために、Keycloakの使用方法を理解する上で必要な手順を定義する3つの主要なプロセスは、以下のとおりです。

認可サービスは以下のRESTFulエンドポイントで構成されています。

これらの各サービスは、認可プロセスに関わるさまざまなステップをカバーする特定のAPIを提供します。

OAuth2の用語では、リソースサーバーは保護されたリソースをホスティングし、保護されたリソースへのリクエストを受け入れてレスポンスを返すことができるサーバーです。

通常、リソースサーバーは、保護されたリソースへのアクセスを許可するかどうかを決定するために、何らかの情報を頼りにします。 RESTfulベースのリソースサーバーの場合、大抵、その情報はセキュリティー・トークンに格納され、一般的に、サーバーへのすべてのリクエストと一緒にベアラートークンとして送信されます。セッションを利用してユーザーを認証するWebアプリケーションは、その情報をユーザーのセッションに格納し、リクエストごとにそこから取得します。

Keycloakでは、 confidential クライアント・アプリケーションはリソースサーバーとして動作できます。このクライアントのリソースとそれぞれのスコープは、一連の認可ポリシーによって保護、管理されます。

リソースは、アプリケーションと組織の資産の一部です。これは、1つ以上のエンドポイントのセット（HTMLページなどの古典的なWebリソースなど）です。認可ポリシーの用語では、リソースは保護される オブジェクト です。

すべてのリソースには、単一のリソースまたはリソースのセットを表すことができる一意の識別子があります。たとえば、すべての銀行口座に対して一連の認可ポリシーを表し定義する Banking Account Resource を管理することができます。ただし、 Alice’s Banking Account と呼ばれる別のリソースを持つこともできます。これは、単一の顧客が所有する単一のリソースを表し、独自の一連の認可ポリシーを持つことができます。

リソースのスコープは、リソース上で実行可能な限定されたアクセスの範囲です。認可ポリシーの用語では、スコープは論理的にリソースに適用できる、潜在的に多くの 動詞 の1つです。

通常は、特定のリソースで何ができるかを示します。スコープの例としては、表示、編集、削除などです。ただし、リソースによって提供される特定の情報に関連付けることもできます。この場合、プロジェクト・リソースとコスト・スコープを持つことができます。コスト・スコープは、ユーザーがプロジェクトのコストにアクセスするための特定のポリシーとパーミッションを定義するために使用されます。

シンプルでとても一般的なパーミッションを考えてみましょう。

パーミッションは、保護されるオブジェクトと、アクセスが許可されるかどうかを判断するために評価されなければならないポリシーとを関連付けます。

Keycloakは、単純なルールから非常に複雑なルールベースの動的なパーミッションまで、幅広いパーミッション戦略を構築するための豊富なプラットフォームを提供します。柔軟性を提供し、次のことに役立ちます。

ポリシーは、オブジェクトへのアクセスを許可するために必要な条件を定義します。パーミッションとは異なり、保護されるオブジェクトを指定するのではなく、特定のオブジェクト（リソース、スコープ、またはその両方）へのアクセスを満たす条件を指定します。ポリシーは、リソースを保護するために使用できるさまざまなアクセス・コントロール・メカニズム（ACM）に強く関連しています。ポリシーを使用すると、属性ベースのアクセス・コントロール（ABAC）、ロールベースのアクセス・コントロール（RBAC）、コンテキストベースのアクセス・コントロール、またはこれらの任意の組み合わせのための戦略を実装できます。

Keycloakは、"ポリシーのポリシー"を構築して評価の動作を制御できる集約されたポリシーの概念を提供することによって、ポリシーの概念とその定義方法を活用します。特定のリソースへのアクセスを満たすすべての条件を含んだ1つの大きなポリシーを書くのではなく、Keycloak認可サービスのポリシー実装は分割統治のテクニックに従います。つまり、個々のポリシーを作成し、異なる権限でそれらを再利用し、個々のポリシーを組み合わせてより複雑なポリシーを構築することができます。

ポリシー・プロバイダーは、特定のポリシー・タイプの実装です。Keycloakには、対応するポリシー・プロバイダーに基づいた組み込みのポリシーが用意されており、独自のポリシー・タイプを作成して特定の要件をサポートすることができます。

Keycloakには、独自のポリシー・プロバイダー実装をプラグイン化するために使用できるSPI（サービス・プロバイダー・インターフェイス）が用意されています。

パーミッション・チケットは、UMA（User-Managed Access）仕様で定義された特別なタイプのトークンで、その形式が認可サーバーによって決定されるOpaque構造体を提供します。この構造体は、クライアントによって要求されているリソースおよび/またはスコープ、アクセス・コンテキスト、および認可データ（リクエスティング・パーティ・トークン[RPT]を要求する）に適用する必要のあるポリシーを表します。

UMAでは、個人対個人の共有や個人対組織の共有をサポートするためにパーミッション・チケットが重要です。承認ワークフローにパーミッション・チケットを使用すると、単純なものから複雑なものまでさまざまなシナリオが可能になります。リソースオーナーとリソースサーバーは、これらのリソースへのアクセスを管理するきめ細かいポリシーに基づいてリソースを完全に制御できます。

UMAのワークフローでは、パーミッション・チケットは認可サーバーによってリソースサーバーに発行されます。リソースサーバーは、保護されたリソースにアクセスしようとするクライアントにパーミッション・チケットを返します。クライアントは、チケットを受信すると、チケットを認可サーバーに送り返すことによって、RPT（認可データを保持する最後のトークン）を要求することができます。

パーミッション・チケットの詳細については、User-Managed Accessおよび UMA の仕様を参照してください。

リソースサーバー設定ページでは、ポリシーの強制モードの設定や、リモートリソース管理の許可、認可構成の設定のエクスポートができます。

デフォルトの設定を変更するには、デフォルトのリソース、ポリシー、またはパーミッションの定義を削除し、独自の定義を作成します。

デフォルトのリソースは、 /* パターンを使用してアプリケーション内の任意のリソースまたはパスにマップされる URI で作成されます。独自のリソース、パーミッション、ポリシーを作成する前に、デフォルト設定が自分の設定と競合しないことを確認してください。

設定ファイルはJSON形式でエクスポートされ、テキストエリアに表示されます。そこからコピーして貼り付けることができます。また、 Download をクリックし、設定ファイルをダウンロードして保存することもできます。

リソースサーバーの設定ファイルをインポートすることができます。

リソースには属性が関連付けられている場合があります。これらの属性を使用すると、リソースに関する追加情報を提供したり、リソースに関連付けられているアクセス許可を評価するときにポリシーに追加情報を提供できます。

各属性はキーと値のペアで、値は1つ以上の文字列のセットになります。属性に複数の値を定義するには、各値をカンマで区切ります。

リソースのタイプ・フィールドは、異なるリソースをグループ化するために使用できます。そのため、共通のパーミッションのセットを使用してそれらのリソースを保護することができます。

リソースにはオーナーがいます。デフォルトでは、リソースはリソースサーバーによって所有されています。

ただし、リソースはユーザーと関連付けることもできるため、リソースオーナーに基づいてパーミッションを作成できます。たとえば、リソースオーナーだけが特定のリソースを削除または更新することができます。

リソース管理は、Protection APIを介しても公開され、リソースサーバーがリソースをリモートで管理できます。

Protection APIを使用すると、リソースサーバーを実装して、ユーザーが所有するリソースを管理できます。この場合、リソースを特定のユーザーに属するものとして設定するためのユーザー識別子を指定できます。

ロールベース・ポリシーを定義するとき、特定のロールを Required と指定することができます。こうすることで、 全て の 必須 ロールを付与されたユーザーにのみアクセス権を与えることができます。レルムロールとクライアントロールの両方にこの設定を適用することができます。

ロールを必須と指定するには、そのロールの Required チェックボックスをチェックします。

複数のロールがポリシーに定義されており、そのうちのいくつかが必須の場合にこの機能は有用です。より細かいロールベース・アクセス・コントロール(RBAC)のためにレルムロールとクライアントロールを組み合わせることが可能です。たとえば、あるクライアントに適用されるポリシーがある場合、そのクライアントに関連付けられた特定のクライアントロールを必須とすることができます。また、特定のレルムロールを持つ場合のみアクセスを許可することもできます。1つのポリシーに両方のアプローチを適用することもできます。

Keycloakを使用すると、JARファイルをデプロイして、サーバーにスクリプトをデプロイできます。詳細については、JavaScript Providersを参照してください。

スクリプトをデプロイしたら、利用可能なポリシー・プロバイダーのリストからデプロイしたスクリプトを選択できるようになります。

アクセスは、すべての条件が満たされている場合にのみ許可されます。Keycloakは、各条件の結果に基づいて AND を実行します。

集約されたポリシーを作成する際には、各ポリシーの結果に基づいて最終的な決定をするために使用される決定戦略を定義することもできます。

デフォルトでは、グループをポリシーに追加したとき、選択されたグループのみにアクセス制限が適用されます。

このアクセス制限を、選択したグループだけでなく、その子グループにも適用したい場合があるかもしれません。その場合、 Extend to Children のチェックボックスをチェックすることで、任意のグループへのアクセス権をその子グループにまで拡大適用することができます。

上の例では、 IT グループとその子グループに属する任意のユーザーに対してアクセス権が付与されます。

クライアント・スコープ・ベースのポリシーを作成するときに、特定のクライアント・スコープを Required として指定できます。これを行うと、アクセスを要求しているクライアントに 全て の 必須 クライアント・スコープが付与されている場合にのみ、ポリシーはアクセスを許可します。

クライアント・スコープを必須と指定するには、そのクライアント・スコープの Required チェックボックスをチェックします。

必須のクライアント・スコープは、ポリシーで複数のクライアント・スコープが定義されているが、それらのサブセットのみが必須である場合に役立ちます。

評価コンテキストは、評価中にポリシーに有用な情報を提供します。

このインターフェイスから、ポリシーは以下を取得できます。

Identity は、認可リクエストと共に送られたOAuth2アクセストークンに基づいて構築され、この構造は元のトークンから抽出されたすべてのクレームへのアクセスを有します。たとえば、 Protocol Mapper を使用してカスタムクレームをOAuth2アクセストークンに含める場合は、ポリシーからこのクレームにアクセスして、それを使用して条件を構築することもできます。

EvaluationContext は、実行およびランタイム環境の両方に関連する属性へのアクセスも提供します。今のところ、いくつかの組み込み属性しかありません。

リソース・パーミッションは、特定のタイプのすべてのリソースに適用されるポリシーを定義するためにも使用できます。この形式のリソース・ベースのパーミッションは、共通のアクセス要件と制約を共有するリソースを持つ場合に役立ちます。

多くの場合、アプリケーション内のリソースは、カプセル化したデータまたは提供する機能に基づいて分類（またはタイプ指定）できます。たとえば、金融アプリケーションは、ある特定の顧客が属している異なる銀行口座を管理することができます。それらは異なる銀行口座ですが、銀行組織によって全体的に定義される共通のセキュリティー要件および制約を共有します。タイプ付きのリソース・パーミッションを使用して、以下のようなすべての銀行口座に適用する共通ポリシーを定義することができます。

タイプ付きのリソース・パーミッションを作成するには、新しいリソース・ベースのパーミッションを作成するときに、Apply to Resource Typeをクリックします。 Apply to Resource Type を On に設定すると、保護するタイプと、指定したタイプのすべてのリソースへのアクセスを制御するために適用されるポリシーを指定できます。

クライアントは、RPTを取得するためにトークン・エンドポイントで認証する必要があります。 urn:ietf:params:oauth:grant-type:uma-ticket グラントタイプを使う際に、クライアントは以下の認証方式のどれかを使用できます。

サーバーからパーミッションを取得する際に、パーミッションの評価においてクレームをポリシーで利用できるようにするために、任意のクレームをプッシュできます。

パーミッション・チケットを使用 せずに サーバーからパーミッションを取得している場合（UMAフロー）、次のようにトークン・エンドポイントに認可リクエストを送信できます。

claim_token パラメーターは、以下の例のような形式のBASE64でエンコードされたJSONを期待します。

この形式では、1つ以上のクレームを想定しており、各クレームの値は文字列型の配列である必要があります。

UMAでは、クライアントがUMAで保護されたリソースサーバーにアクセスしようとすると、認可プロセスが開始されます。

UMAで保護されたリソースサーバーは、リクエスト内のベアラートークンがRPTであることを想定しています。クライアントがRPTなしでリソースサーバーにリソースを要求する場合、次のようになります。

リソースサーバーは、RPTを取得するためにチケットが送られるべきKeycloakサーバーの場所とともに、パーミッション ticket と as_uri パラメーターを持つレスポンスをクライアントに返します。

パーミッション・チケットは、Keycloak Permission APIによって発行される特別なタイプのトークンです。これらは、要求されるパーミッション（たとえば、リソースおよびスコープ）、ならびにリクエストに関連する他の情報を表します。リソースサーバーのみがこれらのトークンを作成できます。

クライアントはパーミッション・チケットを持つとともにKeycloakサーバーの場所も知っているので、クライアントはディスカバリー文書を使用してトークン・エンドポイントの場所を取得し、認可リクエストを送信できます。

Keycloakの評価処理の結果、パーミッションが発行されると、そのパーミッションに関連付けられているRPTが発行されます。

サーバーからのレスポンスは、他のグラントタイプを使用しているときのトークン・エンドポイントからの任意のレスポンスとまったく同じです。RPTは access_token レスポンス・パラメーターから取得できます。パーミッションを得るためにクライアントが認可されていない場合、Keycloakは次のように 403 HTTPステータスコードで応答します。

認可プロセスの一環として、クライアントはKeycloakトークン・エンドポイントでRPTと交換するために、まずUMAで保護されたリソースサーバーからパーミッション・チケットを取得する必要があります。

クライアントがRPTを発行できない場合、デフォルトでKeycloakは 403 HTTPステータスコードと request_denied エラーで応答します。

このようなレスポンスは、Keycloakがパーミッション・チケットによって表されるパーミッションを持つRPTを発行できないことを意味します。

状況によっては、クライアント・アプリケーションが非同期認可フローを開始して、要求されているリソースオーナーにアクセスを許可するかどうかを決定させたい場合があります。そのために、次のようにクライアントは submit_request リクエスト・パラメーターをトークン・エンドポイントへの認可リクエストとともに使用できます。

submit_request パラメーターを使用すると、Keycloakは、アクセスが拒否された各リソースに対して、パーミッション・リクエストを永続化します。作成されると、リソースオーナーは自分のアカウントを確認し、パーミッション・リクエストを管理できます。

この機能は、アプリケーション内の Request Access ボタンとして考えることができます。このボタンは、ユーザーが他のユーザーにリソースへのアクセスを求めることを可能にします。

ユーザーは、Keycloakのアカウント・コンソールを使用して、自分のリソースへのアクセスを管理することができます。この機能を有効にするには、まずレルムに対してUser-Managed Accessを有効にする必要があります。

Protection APIトークン （PAT）は、 uma_protection として定義されたスコープを持つ特殊なOAuth2アクセストークンです。リソースサーバーを作成すると、Keycloakは対応するクライアント・アプリケーションのロール uma_protection を自動的に作成し、クライアントのサービス・アカウントに関連付けます。

リソースサーバーは、Keycloakから他のOAuth2アクセストークンと同様にPATを取得できます。たとえば、次のようにcurlを使用します。

上記の例では、 client_credentials グラントタイプを使用してサーバーからPATを取得しています。その結果、サーバーは次のような応答を返します。

リソースサーバーは、UMA準拠のエンドポイントを使用して、リモートでリソースを管理できます。

このエンドポイントは、以下に概説されている操作を提供します（明確にするため、パス全体が省略されています）。

各操作の規約の詳細については、 UMA Resource Registration API を参照してください。

UMAプロトコルを使用するリソースサーバーは、特定のエンドポイントを使用してパーミッション・リクエストを管理できます。このエンドポイントは、パーミッション・リクエストを登録し、パーミッション・チケットを取得するためのUMA準拠のフローを提供します。

パーミッション・チケットは、パーミッション・リクエストを表す特殊なセキュリティー・トークン・タイプです。UMA仕様における、パーミッション・チケットは次のとおりです。

認可サーバーからリソースサーバー、リソースサーバーからクライアント、最終的にはクライアントから認可サーバーに伝達され、認可サーバーが認可データの要求に適用する正しいポリシーを評価できるようにする相関ハンドル。

ほとんどの場合、このエンドポイントを直接処理する必要はありません。Keycloakは、リソースサーバーのUMAを有効にするポリシー・エンフォーサーを提供し、認可サーバーからパーミッション・チケットを取得し、このチケットをクライアント・アプリケーションに戻し、最後にリクエスティング・パーティ・トークン（RPT）に基づいて認可決定を実施することができます。

Keycloakからパーミッション・チケットを取得するプロセスは、通常のクライアント・アプリケーションではなく、リソースサーバーによって実行されます。パーミッション・チケットは、クライアントが保護されたリソースにアクセスするために必要な許可なしにアクセスしようとしたときに取得されます。パーミッション・チケットの発行は、リソースサーバーに次のことを許可するため、UMAを使用する際の重要な側面です。

クライアントから見ると、パーミッション・チケットには重要な側面もあります。

これらは、UMAの他の側面が、特にプライバシーとリソースへのアクセス制御されたユーザーに関するパーミッション・チケットに強く基づいたUMAのメリットのほんの一部です。

KeycloakはUMA Protection APIを利用して、リソースサーバーがユーザーのパーミッションを管理できるようにします。KeycloakはリソースAPIとパーミッションAPIに加えて、ユーザーの代わりにリソースサーバーによって、リソースにパーミッションを設定できるPolicy APIを提供します。

Policy APIは次の場所にあります。

このAPIは、ユーザーからリソースサーバーへの承諾を表すベアラトークンによって保護されています。ベアラトークンは、以下を使用することで、トークン・エンドポイントから取得された通常のアクセストークンとすることができます。

場合によっては、リクエスティング・パーティー・トークン（RPT）をイントロスペクトして、その有効性をチェックしたり、トークン内のパーミッションを取得して、リソースサーバー側で認可の決定を行うことがあります。

トークン・イントロスペクションが役立つ2つの主なユースケースがあります。

トークン・イントロスペクションは基本的に、RPTに関する情報を取得するための OAuth2トークン・イントロスペクション 準拠のエンドポイントです。

このエンドポイントを使用してRPTをイントロスペクションするには、次のようにしてサーバーにリクエストを送信します。

イントロスペクション・エンドポイントには2つのパラメータが必要です。

その結果、サーバーの応答は次のようになります。

RPTがアクティブでない場合、代わりにこのレスポンスが返されます。

Keycloakサーバーが発行する通常のアクセストークンと同様に、RPTもJWT（JSON Web Token）仕様をデフォルトのフォーマットとして使用します。

リモート・イントロスペクション・エンドポイントを呼び出さずにこれらのトークンを検証する場合は、RPTをデコードしてローカルでその有効性を問い合わせることができます。トークンをデコードすると、トークン内のパーミッションを使用して認可の決定を行うこともできます。

これは、基本的にポリシー・エンフォーサーが行うことです。以下を確認してください。

クライアントの設定は、 keycloak.json ファイルで次のように定義されています。

設定ファイルは通常、クライアントの keycloak.json ファイルを見つける際のデフォルトのローケーションであるアプリケーションのクラスパスにあります。

クラスパスに keycloak.json ファイルがあることを前提として、次のように新しい AuthzClient インスタンスを作成することができます。

ユーザー・エンタイトルメントを取得する方法の例を示します。

1つ以上のリソースのセットに対してユーザー・エンタイトルメントを取得する方法の例を示します。

HTTPリクエストからクレームを抽出する方法を示すいくつかの例を以下に示します。

外部HTTPサービスからクレームを抽出する方法を示すいくつかの例を以下に示します。

ビルトインのプロバイダーでは要件を満たすことができない場合、異なるクレーム情報ポイントをサポートするために、開発者はクレーム情報プロバイダーSPIを使用することができます。

たとえば、新しいCIPプロバイダーを実装するには、 org.keycloak.adapters.authorization.ClaimInformationPointProviderFactory と ClaimInformationPointProvider を実装し、アプリケーションのクラスパスに META-INF/services/org.keycloak.adapters.authorization.ClaimInformationPointProviderFactory ファイルを提供する必要があります。

org.keycloak.adapters.authorization.ClaimInformationPointProviderFactory の例：

すべてのCIPプロバイダーは、上記の MyClaimInformationPointProviderFactory.getName メソッドで定義されている名前に関連付けられている必要があります。この名前は policy-enforcer 設定の claim-information-point セクションから実装への設定をマッピングするために使用されます。

リクエストを処理する際に、ポリシー・エンフォーサーは、MyClaimInformationPointProviderのインスタンスを取得するため、MyClaimInformationPointProviderFactory.createメソッドを呼び出します。呼び出されると、この特定のCIPプロバイダー用に定義された設定（claim-information-pointを経由）がマップとして渡されます。

ClaimInformationPointProvider の例：

リソースサーバーがポリシー・エンフォーサーによって保護されている場合、リソースサーバーは、ベアラートークンとともに搬送されるパーミッションに基づいてクライアント・リクエストに応答します。通常、保護されたリソースにアクセスする権限がないベアラトークンを使用してリソースサーバーにアクセスしようとすると、リソースサーバーは 401 ステータスコードと WWW-Authenticate ヘッダーで応答します。

詳細については、UMAの認可プロセスを参照してください。

クライアントが行う必要があるのは、リソースサーバーから返された WWW-Authenticate ヘッダーからパーミッション・チケットを抽出し、ライブラリーを使用して次のように認可リクエストを送信することです。

authorize 関数は完全に非同期で、サーバーからの通知を受け取るためのいくつかのコールバック関数をサポートしています。

ほとんどのアプリケーションは、 onGrant コールバックを使用して401応答後にリクエストをリトライする必要があります。以降のリクエストには、RPTをリトライのためのベアラー・トークンとして含める必要があります。

keycloak-authz.js ライブラリーは、クライアントがアクセスしたいリソースとスコープを提供することによって、サーバーからRPTを取得するために使用できる entitlement 関数を提供します。

entitlement を使用する場合は、アクセスするリソースサーバーの client_id を指定する必要があります。

entitlement 関数は完全に非同期で、サーバーからの通知を受け取るためのコールバック関数をいくつかサポートしています。

authorize と entitlement の両方の関数は、認可リクエスト・オブジェクトを受け入れます。このオブジェクトは、次のプロパティーで設定できます。

ライブラリによって提供されている認可関数を使用してRPTをすでに取得している場合は、認可オブジェクトから次のようにRPTを得ることができます（前述のいずれかの手法で初期化されているものとします）。