13.6. クライアントスコープ

クライアントスコープを作成する場合は、Protocol を選択します。同じスコープにリンクされるクライアントには、同じプロトコルが必要です。

各レルムには、メニューに事前に定義されたビルトインクライアントスコープのセットがあります。

クライアントスコーププロファイル、profile、email、address、および phone は、OpenID Connect 仕様 に定義されています。これらのスコープにはロールスコープマッピングが定義されていませんが、プロトコルマッパーが定義されます。これらのマッパーは、OpenID Connect 仕様で定義されているクレームに対応しています。

たとえば、phone クライアントスコープを開いて Mappers タブを開くと、phone スコープの仕様で定義されているクレームに対応するプロトコルマッパーが表示されます。

phone クライアントスコープがクライアントにリンクされると、そのクライアントは phone クライアントスコープで定義されたすべてのプロトコルマッパーを自動的に継承します。このクライアントに発行されたアクセストークンには、ユーザーに関する電話番号 (電話番号が定義されているか) が含まれます。

ビルトインクライアントスコープには、仕様で定義されているプロトコルマッパーが含まれます。クライアントスコープを編集し、プロトコルマッパーまたはロールスコープマッピングを作成、更新、または削除できます。

クライアントスコープには、同意画面に関連するオプションが含まれます。これらのオプションは、リンクされたクライアントで Consent Required が有効になっている場合に、役立ちます。

クライアントスコープに Include in token scope のスイッチがあります。オンの場合、このクライアントスコープの名前がアクセストークンプロパティースコープと、トークンレスポンスおよびトークンイントロスペクションエンドポイントレスポンスクレーム scope に追加されます。オフの場合、このクライアントスコープはトークンおよびトークンイントロスペクションエンドポイント応答から省略されます。前述のように、一部の組み込みクライアントスコープではこのスイッチが無効になっています。つまり、特定のリクエストに適用されても、scope クレームには含まれません。

クライアントスコープとクライアント間のリンクは、クライアントの Client Scopes タブで設定されます。クライアントアプリケーション myclient の場合は次のようになります。

クライアントスコープとクライアントをリンクする方法は 2 つあります。

scope=openid phone

scope=openid phone

Mappers タブにはプロトコルマッパーが含まれ、Scope タブにはこのクライアントに対して宣言されたロールスコープマッピングが含まれます。クライアントスコープから継承されるマッパーおよびスコープのマッピングは含まれません。有効なプロトコルマッパー (クライアント自体に定義されたプロトコルマッパー、リンクされたクライアントスコープから継承されるプロトコルマッパー) と、クライアントのトークンの生成時に使用される効果的なロールスコープマッピングを確認できます。

これにより、scope パラメーターの値も表示されます。このパラメーターは、アプリケーションから Red Hat build of Keycloak OpenID Connect 認証エンドポイントに送信する必要があります。

また、このクライアントに発行されたアクセストークン、ID トークン、または UserInfo 応答が、選択された特定のユーザーと、audience パラメーターの特定の値をどのように検索するかをシミュレートすることもできます。現時点では、audience パラメーターはトークン交換許可に対してのみサポートされていることに注意してください。他の付与をシミュレートする場合は、空のままにすることを推奨します。

すべての例は、scope パラメーターに指定された値を使用して、特定のユーザー用に生成され、特定のクライアント用に発行されます。この例には、使用されるすべてのクレームとロールマッピングが含まれています。

ユーザーにトークンを発行する場合、クライアントスコープは、ユーザーがトークンを使用できる場合にのみ適用されます。

クライアントスコープにロールスコープマッピングが定義されていない場合は、各ユーザーはこのクライアントスコープを使用できます。ただし、クライアントスコープにロールスコープマッピングが定義されている場合に、ユーザーは少なくとも 1 つのロールに所属する必要があります。ユーザーロールとクライアントスコープのロール間に交差部分が必要です。この交差点の評価には、複合ロールが考慮されます。

ユーザーがクライアントスコープを使用できない場合には、トークンの生成時にプロトコルマッパーまたはロールスコープのマッピングは使用されません。クライアントスコープはトークンの scope 値には表示されません。

Realm Default Client Scopes を使用して、新たに作成されたクライアントに自動的にリンクされるクライアントスコープのセットを定義します。

レルムのデフォルトクライアントスコープを表示するには、管理コンソールの左側にある Client Scopes タブをクリックします。Assigned type 列で、特定のクライアントスコープを Default Client Scope または Optional Client Scope として新規作成されるクライアントに追加するかどうかを指定できます。デフォルト および オプション のクライアントスコープの詳細は、このセクション を参照してください。

クライアントが作成されると、必要に応じて、デフォルトのクライアントスコープのリンクを解除できます。これは、デフォルトロール の削除に似ています。

スコープ という用語は、Red Hat build of Keycloak 内および OAuth/OIDC 仕様において複数の意味を持ちます。以下で、Red Hat build of Keycloak で使用されるさまざまな スコープ を明確に説明しています。