認可サービスガイド

3つの主要なプロセスが、Keycloakを使用してアプリケーションへのきめ細かい認可を有効にする方法を理解するために必要なステップを定義します

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

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

OAuth2用語に従い、リソースサーバーは、保護されたリソースをホストし、保護されたリソースリクエストを受け入れて応答できるサーバーです。

リソースサーバーは通常、保護されたリソースへのアクセスを許可する必要があるかどうかを決定するために、何らかの情報に依存しています。RESTfulベースのリソースサーバーの場合、その情報は通常、セキュリティトークンに含まれており、通常はサーバーへのすべてのリクエストとともにベアラートークンとして送信されます。ユーザーを認証するためにセッションに依存するWebアプリケーションは、通常、その情報をユーザーのセッションに保存し、各リクエストごとにそこから取得します。

Keycloakでは、すべてのコンフィデンシャルクライアントアプリケーションはリソースサーバーとして機能できます。このクライアントのリソースとそれぞれのスコープは、一連の認可ポリシーによって保護および管理されます。

リソースは、アプリケーションと組織の資産の一部です。これは、1つまたは複数のエンドポイントのセット、HTMLページなどの従来のWebリソースなどです。認可ポリシ

すべてのリソースは、単一のリソースまたはリソースのセットを表すことができる一意の識別子を持ちます。たとえば、すべての銀行口座に対する認可ポリシーのセットを表し、定義する銀行口座リソースを管理できます。しかし、単一の顧客が所有する単一のリソースを表し、独自の認可ポリシーのセットを持つことができる、アリスの銀行口座という別のリソースを持つこともできます。

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

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

このシンプルで非常に一般的なパーミッションについて考えてみましょう。

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

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

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

Keycloakは、集約ポリシーの概念を提供することにより、ポリシーの概念とポリシーの定義方法を活用しています。ここでは、「ポリシーのポリシー」を構築し、評価の動作を制御できます。特定のリソースへのアクセスに対して満たす必要のあるすべての条件を含む1つの大きなポリシーを作成する代わりに、Keycloak Authorization Servicesのポリシー実装は分割統治法に従います。つまり、個々のポリシーを作成し、それらを異なるパーミッションで再利用し、個々のポリシーを組み合わせることでより複雑なポリシーを構築できます。

ポリシープロバイダーは、特定のポリシータイプの実装です。Keycloakは、対応するポリシープロバイダーによってバックアップされた組み込みポリシーを提供し、特定の要件をサポートするために独自のポリシータイプを作成できます。

Keycloakは、独自のポリシープロバイダー実装をプラグインするために使用できるSPI（サービスプロバイダーインターフェース）を提供します。

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

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

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

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

リソースサーバー設定ページでは、ポリシー適用モードを設定し、リモートリソース管理を許可し、認可構成設定をエクスポートできます。

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

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

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

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

リソースには、属性を関連付けることができます。これらの属性は、リソースに関する追加情報を提供したり、リソースに関連付けられたパーミッションを評価する際にポリシーに追加情報を提供したりするために使用できます。

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

リソースのタイプフィールドを使用すると、さまざまなリソースをグループ化して、共通のパーミッションセットを使用して保護できます。

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

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

リソース管理は、リソースサーバーがリソースをリモートで管理できるように、Protection APIを通じて公開されています。

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

ロールベースのポリシーを作成するときに、特定のロールをRequiredとして指定できます。これを行うと、アクセスをリクエストしているユーザーにすべての必須ロールが付与されている場合にのみ、ポリシーはアクセスを許可します。レルムロールとクライアントロールの両方をこのように構成できます。

ロールを必須として指定するには、必須として構成するロールの必須チェックボックスをオンにします。

必須ロールは、ポリシーが複数のロールを定義しているが、そのサブセットのみが必須である場合に役立ちます。この場合、レルムロールとクライアントロールを組み合わせて、アプリケーションのよりきめ細かいロールベースのアクセス制御（RBAC）モデルを有効にできます。たとえば、クライアント固有のポリシーを持ち、そのクライアントに関連付けられた特定のクライアントロールを必須にすることができます。または、特定のレルムロールが存在する場合にのみアクセスが許可されるように強制することもできます。同じポリシー内で両方のアプローチを組み合わせることもできます。

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

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

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

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

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

状況によっては、グループ自体だけでなく、階層内の任意の子グループへのアクセスを許可する必要がある場合があります。追加された任意のグループについて、子グループへのアクセスを拡張するために子グループにも適用チェックボックスをオンにすることができます。

上記の例では、ポリシーは IT またはその子グループのメンバーであるすべてのユーザーにアクセスを許可しています。

クライアントスコープベースのポリシーを作成する際に、特定のクライアントスコープをRequiredとして指定できます。その場合、アクセスをリクエストしているクライアントがすべての必須クライアントスコープを許可されている場合にのみ、ポリシーはアクセスを許可します。

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

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

評価コンテキストは、ポリシーの評価中にポリシーに役立つ情報を提供します。

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

Identityは、認証リクエストとともに送信されたOAuth2アクセストークンに基づいて構築されており、この構成は元のトークンから抽出されたすべてのクレームにアクセスできます。たとえば、プロトコルマッパーを使用してカスタムクレームをOAuth2アクセストークンに含める場合、ポリシーからこのクレームにアクセスして、条件を構築するために使用することもできます。

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

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

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

タイプ指定されたリソースパーミッションを作成するには、新しいリソースベースのパーミッションを作成するときにリソースタイプに適用をクリックします。リソースタイプに適用をオンに設定すると、保護するタイプと、指定したタイプを持つすべてのリソースへのアクセスを管理するために適用されるポリシーを指定できます。

クライアントが RPT を取得するには、トークンエンドポイントに対して認証を行う必要があります。urn:ietf:params:oauth:grant-type:uma-ticketグラントタイプを使用する場合、クライアントはこれらの認証方法のいずれかを使用できます。

サーバーから許可を取得するときに、任意のクレームをプッシュして、許可を評価するときにポリシーでこれらのクレームを利用できるようにすることができます。

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

claim_tokenパラメータは、以下の例と同様の形式の BASE64 エンコードされた JSON を予期しています。

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

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

UMA で保護されたリソースサーバーは、リクエストでベアラートークンを予期しており、そのトークンは RPT です。クライアントが RPT なしでリソースサーバーでリソースをリクエストすると

リソースサーバーは、クライアントにパーミッションチケットと、RPT を取得するためにチケットを送信する必要がある Keycloak サーバーの場所を示す as_uri パラメータを含むレスポンスを返送します。

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

クライアントは、パーミッションチケットと Keycloak サーバーの場所を取得したので、ディスカバリードキュメントを使用してトークンエンドポイントの場所を取得し、認可リクエストを送信できます。

Keycloak 評価プロセスが許可の発行につながった場合、許可が関連付けられている RPT を発行します。

サーバーからのレスポンスは、他のグラントタイプを使用する場合のトークンエンドポイントからの他のレスポンスとまったく同じです。RPT は、access_token レスポンスパラメータから取得できます。クライアントが許可を持つ権限がない場合、Keycloak は 403 HTTP ステータスコードで応答します

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

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

このような応答は、Keycloak がパーミッションチケットによって表される許可で RPT を発行できなかったことを意味します。

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

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

この機能は、アプリケーションの アクセスリクエスト ボタンのように考えることができます。ユーザーは他のユーザーに自分のリソースへのアクセスを要求できます。

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

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

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

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

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

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

これらの各操作の契約の詳細については、UMA リソース登録 API を参照してください。

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

パーミッションチケットは、パーミッションリクエストを表す特別なセキュリティトークンタイプです。UMA仕様に従って、パーミッションチケットは

認可サーバーからリソースサーバーへ、リソースサーバーからクライアントへ、そして最終的にはクライアントから認可サーバーへと伝達される関連ハンドルであり、認可サーバーが認可データのリクエストに適用する適切なポリシーを評価できるようにします。

ほとんどの場合、このエンドポイントを直接扱う必要はありません。Keycloakは、リソースサーバーのUMAを有効にするポリシーエンフォーサーを提供し、認可サーバーからパーミッションチケットを取得し、このチケットをクライアントアプリケーションに返し、最終的なリクエスターパーティートークン（RPT）に基づいて認可決定を適用できるようにします。

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

クライアント側では、パーミッションチケットには強調する価値のある重要な側面もあります。

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

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

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

このAPIは、ユーザーが自分の代わりにパーミッションを管理するためにリソースサーバーに付与した同意を表すベアラートークンによって保護されています。ベアラートークンは、トークンエンドポイントから取得した通常のアクセストークンにすることができます。

リクエスターパーティートークン（RPT）をイントロスペクトして、その有効性を確認したり、トークン内のパーミッションを取得してリソースサーバー側で認可決定を適用したりすることが必要な場合があります。

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

トークンイントロスペクションは、基本的にOAuth2トークンイントロスペクション準拠のエンドポイントであり、ここからRPTに関する情報を取得できます。

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

イントロスペクションエンドポイントは、次の2つのパラメーターを想定しています。

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

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

いいえ。Keycloakサーバーによって発行された通常のアクセストークンと同様に、RPTもデフォルト形式としてJSONウェブトークン（JWT）仕様を使用しています。

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

これは基本的にポリシーエンフォーサーが行うことです。必ず次のことを行ってください。

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

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

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

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

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

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

entitlement 関数を使用する場合、アクセスしたいリソースサーバーの client_id を提供する必要があります。

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

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

ライブラリによって提供される認可関数のいずれかを使用して RPT をすでに取得している場合は、認可オブジェクトから次のように RPT を常に取得できます (以前に示された手法のいずれかによって初期化されていると仮定します)。