8.2. パーミッションの取得

PDF

Red Hat build of Keycloak からパーミッションを取得するには、認可要求をトークンエンドポイントに送信します。これにより、Red Hat build of Keycloak はリソースに関連付けられたすべてのポリシーを評価し、スコープが要求され、サーバーで付与されるすべてのパーミッションで RPT を発行します。

以下のパラメーターを使用して、クライアントはトークンエンドポイントに認可要求を送信できます。

grant_type
このパラメーターは必須です。urn:ietf:params:oauth:grant-type:uma-ticket である必要があります。
ticket
このパラメーターは任意です。UMA 認可プロセスの一部として、クライアントが受信する最新のパーミッションチケットです。
claim_token
このパラメーターは任意です。要求されるリソースおよびスコープのパーミッションを評価する際にサーバーによって考慮される必要のある追加の要求を表す文字列。このパラメーターにより、クライアントは要求を Red Hat build of Keycloak にプッシュできます。サポートされるすべてトークン形式に関する詳細は、claim_token_format パラメーターを参照してください。
claim_token_format
このパラメーターは任意です。claim_token パラメーターで指定されたトークンの形式を示す文字列。Red Hat build of Keycloak は、urn:ietf:params:oauth:token-type:jwt および https://openid.net/specs/openid-connect-core-1_0.html#IDToken の 2 つのトークン形式をサポートします。urn:ietf:params:oauth:token-type:jwt 形式は、claim_token パラメーターがアクセストークンを参照することを示します。https://openid.net/specs/openid-connect-core-1_0.html#IDToken は、claim_token パラメーターが OpenID Connect ID トークンを参照することを示しています。
rpt
このパラメーターは任意です。以前は、パーミッションを評価する RPT を発行して、新しいパーミッションに追加する必要がある。このパラメーターにより、クライアントが RPT の所有しているクライアントに対して、パーミッションがオンデマンドで追加される増分認可を実行できます。
permission
このパラメーターは任意です。クライアントがアクセスを求めている 1 つまたは複数のリソースとスコープのセットを表す文字列です。このパラメーターは、複数のリソースおよびスコープのパーミッションを要求するために複数回定義できます。このパラメーターは、クライアントがパーミッションチケットなしで認可要求を送信できるようにする urn:ietf:params:oauth:grant-type:uma-ticket 付与タイプの拡張です。文字列の形式は RESOURCE_ID#SCOPE_ID にする必要があります。たとえば、Resource A#Scope A、Resource A#Scope A, Scope B, Scope C、Resource A、#Scope A です。
permission_resource_format
このパラメーターは任意です。permission パラメーター内のリソースを示す形式を表現する文字列。可能な値は id と uri です。id は、形式が RESOURCE_ID であることを示します。uri は、形式が URI であることを示します。指定しない場合、デフォルトは id です。
permission_resource_matching_uri
このパラメーターは任意です。permission パラメーターでリソースを URI 形式で表すときに、パスマッチングを使用するかどうかを示すブール値。指定しない場合、デフォルトは false です。
audience
このパラメーターは任意です。クライアントがアクセスを表示しているリソースサーバーのクライアント識別子。permission パラメーターが定義されている場合、このパラメーターは必須です。これは、Red Hat build of Keycloak へのヒントとして機能し、パーミッションの評価に使用するコンテキストを示します。
response_include_resource_name
このパラメーターは任意です。リソース名を RPT のパーミッションに含めるかどうかを示すブール値。false の場合、リソース識別子のみが含まれます。
response_permissions_limit
このパラメーターは任意です。RPT が持つパーミッションの量の制限を定義する整数 N。rpt パラメーターとともに使用する場合は、最後に要求されたパーミッションのみが RPT に保持されます。
submit_request
このパラメーターは任意です。サーバーがリソースに対するパーミッション要求を作成するかどうか、およびパーミッションチケットによって参照されるスコープを許可するかどうかを示すブール値。このパラメーターは、UMA 認可プロセスの一部として ticket パラメーターとともに使用する場合にのみ有効です。
response_mode
このパラメーターは任意です。サーバーが認可要求に応答する方法を示す文字列値。このパラメーターは、標準の OAuth2 応答ではなく、サーバー全体またはサーバーによって付与されたパーミッションに主に関心がある場合に特に便利です。可能な値は次のとおりです。
- decision
  サーバーからの応答は、以下の形式で JSON を返すことで全体的な決定内容のみを表す必要があることを示します。
```
{
    'result': true
}
```
  認可要求がパーミッションにマップされない場合、代わりに 403 HTTP ステータスコードが返されます。
- permissions
  以下の形式で JSON を返して、サーバーからの応答に、サーバーによって付与されたパーミッションが含まれることを示します。
```
[
    {
        'rsid': 'My Resource'
        'scopes': ['view', 'update']
    },

    ...
]
```
  認可要求がパーミッションにマップされない場合、代わりに 403 HTTP ステータスコードが返されます。

リソースサーバーが保護する 2 つのリソースへのアクセスをクライアントがシークしている場合の認可要求の例。

curl -X POST \
  http://${host}:${port}/realms/${realm}/protocol/openid-connect/token \
  -H "Authorization: Bearer ${access_token}" \
  --data "grant_type=urn:ietf:params:oauth:grant-type:uma-ticket" \
  --data "audience={resource_server_client_id}" \
  --data "permission=Resource A#Scope A" \
  --data "permission=Resource B#Scope B"

クライアントがすべてのリソースへのアクセスを生み、リソースサーバーによって保護されるスコープを指定する際の認可要求の例。注記: すべてのリソースのパーミッションが評価されるわけではありません。代わりに、リソースサーバーが所有するリソース、要求側ユーザーが所有するリソース、および他の所有者によって要求側ユーザーに明示的に付与されたリソースのパーミッションが評価されます。

curl -X POST \
  http://${host}:${port}/realms/${realm}/protocol/openid-connect/token \
  -H "Authorization: Bearer ${access_token}" \
  --data "grant_type=urn:ietf:params:oauth:grant-type:uma-ticket" \
  --data "audience={resource_server_client_id}"

認可プロセスの一環として、リソースサーバーからパーミッションチケットを受信した後に、クライアントが UMA 保護リソースにアクセスできるようにする場合に認可要求の例:

curl -X POST \
  http://${host}:${port}/realms/${realm}/protocol/openid-connect/token \
  -H "Authorization: Bearer ${access_token}" \
  --data "grant_type=urn:ietf:params:oauth:grant-type:uma-ticket" \
  --data "ticket=${permission_ticket}

Red Hat build of Keycloak アセスメントプロセスでパーミッションが発行されると、パーミッションが関連付けられている RPT が発行されます。

Red Hat build of Keycloak は RPT でクライアントに応答します

HTTP/1.1 200 OK
Content-Type: application/json
...
{
    "access_token": "${rpt}",
}

サーバーからの応答は、他の付与タイプを使用する場合にトークンエンドポイントからの他の応答と同様になります。RPT は access_token 応答パラメーターから取得できます。クライアントが認可されていない場合、Red Hat build of Keycloak は 403 HTTP ステータスコードで応答します。

Red Hat build of Keycloak は認可要求を拒否します

HTTP/1.1 403 Forbidden
Content-Type: application/json
...
{
    "error": "access_denied",
    "error_description": "request_denied"
}

8.2.1. クライアント認証方法

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

ベアラートークン
クライアントは、アクセストークンを HTTP Authorization ヘッダーの Bearer 認証情報としてトークンエンドポイントに送信する必要があります。
例: アクセストークンを使用してトークンエンドポイントに対して認証を行う認可要求
```
curl -X POST \
  http://${host}:${port}/realms/${realm}/protocol/openid-connect/token \
  -H "Authorization: Bearer ${access_token}" \
  --data "grant_type=urn:ietf:params:oauth:grant-type:uma-ticket"
```
この方法は、クライアントがユーザーの代わりに動作している場合などに便利です。この場合、ベアラートークンは、Red Hat build of Keycloak が以前、ユーザーの代わりに (または自身の代わりに) クライアントに発行したアクセストークンです。パーミッションは、アクセストークンで表されるアクセスコンテキストを考慮します。たとえば、ユーザー A に代わってアクセストークンがクライアント A に発行された場合、リソースおよびユーザー A がアクセス可能なスコープに応じてパーミッションが付与されます。
クライアント認証情報
クライアントは、Red Hat build of Keycloak でサポートされている任意のクライアント認証方法を使用できます。たとえば、client_id/client_secret または JWT などがあります。
例: クライアント ID およびクライアントシークレットを使用してトークンエンドポイントに対して認証を行う認可要求
```
curl -X POST \
  http://${host}:${port}/realms/${realm}/protocol/openid-connect/token \
  -H "Authorization: Basic cGhvdGg6L7Jl13RmfWgtkk==pOnNlY3JldA==" \
  --data "grant_type=urn:ietf:params:oauth:grant-type:uma-ticket"
```

8.2.2. クレームのプッシュ

サーバーからパーミッションを取得する場合、任意の要求をプッシュし、パーミッションの評価時にこれらの要求をポリシーに対して利用可能にすることができます。

パーミッションチケット (UMA フロー) を 使用せず にサーバーからパーミッションを取得する場合は、以下のように認可要求をトークンエンドポイントに送信できます。

curl -X POST \
  http://${host}:${port}/realms/${realm}/protocol/openid-connect/token \
  --data "grant_type=urn:ietf:params:oauth:grant-type:uma-ticket" \
  --data "claim_token=ewogICAib3JnYW5pemF0aW9uIjogWyJhY21lIl0KfQ==" \
  --data "claim_token_format=urn:ietf:params:oauth:token-type:jwt" \
  --data "client_id={resource_server_client_id}" \
  --data "client_secret={resource_server_client_secret}" \
  --data "audience={resource_server_client_id}"

claim_token パラメーターには、以下の例のような形式を持つ、BASE64 でエンコードされた JSON が必要になります。

{
    "organization" : ["acme"]
}

この形式では、各要求の値が文字列の配列である必要がある 1 つ以上の要求を想定します。

8.2.2.1. UMA を使用した要求のプッシュ

UMA およびパーミッションチケットの使用時に要求をプッシュする方法は、パーミッション API を参照してください。

8.2. パーミッションの取得

8.2.1. クライアント認証方法

8.2.2. クレームのプッシュ

8.2.2.1. UMA を使用した要求のプッシュ

詳細情報

試用、購入および販売

コミュニティー

Red Hat ドキュメントについて

多様性を受け入れるオープンソースの強化

会社概要

Red Hat legal and privacy links

Red Hat legal and privacy links