13.4. OIDC トークンおよび SAML アサーションマッピング
ID トークン、アクセストークン、または SAML アサーションを受信するアプリケーションは、異なるロールおよびユーザーメタデータが必要になる場合があります。
Red Hat build of Keycloak では、以下を行えます。
- ロール、要求、およびカスタム属性をハードコーディングする。
- ユーザーメタデータをトークンまたはアサーションにプルする。
- ロールの名前を変更する。
これらのアクションは、管理コンソールの Mappers タブで実行します。
Mappers タブ
新しいクライアントにはビルトインマッパーがありませんが、クライアントスコープから一部のマッパーを継承できます。詳細は、クライアントスコープ セクションを参照してください。
プロトコルマッパーは項目 (メールアドレスなど) を ID およびアクセストークンの特定の要求にマッピングします。マッパーの機能は、その名前を見ただけでわかるようにしておく必要があります。Add Builtin をクリックして、事前設定されたマッパーを追加します。
各マッパーには共通の設定のセットがあります。マッパーのタイプに応じて、追加の設定を利用できます。マッパーの横にある Edit をクリックして設定画面にアクセスし、これらの設定を調整します。
マッパーの設定
各オプションの詳細は、ツールチップの上にマウスをかざして表示できます。
要求を配置する場所を制御するには、ほぼどの OIDC マッパーでも使用できます。Add to ID token と Add to access token のスイッチを調整して、id および access トークンから要求を追加するか、除外することができます。
以下のようにマッパータイプを追加できます。
手順
- Mappers タブに移動します。
Configure a new mapper をクリックします。
マッパーの追加
- リストボックスから Mapper Type を選択します。
13.4.1. 優先順位
マッパー実装には 優先順位 があります。優先順位 はマッパーの設定プロパティーではありません。これはマッパーの具体的な実装のプロパティーです。
マッパーは、マッパーリストの順番にソートされます。トークンまたはアサーションの変更は、最も低いものから順に適用されます。そのため、他の実装に依存する実装は必要な順序で処理されます。
たとえば、トークンに含まれるロールを計算するには、以下を実行します。
- それらのロールに基づいて対象を解決します。
- トークンにすでに利用可能なロールおよび対象を使用する JavaScript スクリプトを処理します。
13.4.2. OIDC ユーザーセッションノートマッパー
ユーザーセッションの詳細はマッパーを使用して定義され、クライアントで機能を使用できません。Add builtin をクリックして、セッションの詳細を追加します。
切り替え後のユーザーセッションは以下の詳細を提供します。
- IMPERSONATOR_ID: 偽装ユーザーの ID
- IMPERSONATOR_USERNAME: 偽装ユーザーのユーザー名
サービスアカウントセッションは以下の詳細を提供します。
- clientID: サービスアカウントのクライアント ID
- client_id: サービスアカウントのクライアント ID。
- clientAddress: サービスアカウントの認証されたデバイスのリモートホスト IP
- clientHost: サービスアカウントの認証デバイスのリモートホスト名
13.4.3. スクリプトマッパー
Script Mapper を使用して、ユーザー定義の JavaScript コードを実行して要求をトークンにマッピングします。スクリプトをサーバーにデプロイする方法の詳細は、JavaScript プロバイダー を参照してください。
スクリプトのデプロイ時に、利用可能なマッパーのリストからデプロイされたスクリプトを選択できるはずです。
13.4.4. サブジェクト識別子マッパー(pairwise サブジェクト識別子マッパー)
Subject claim サブ パスは、デフォルトのクライアントスコープ basic の Subject (sub) プロトコルマッパーによってデフォルトでマップされます。
ペア単位サブジェクト識別子などのプロトコルマッパーを使用してペア 単位のサブジェクト識別子 を使用するには、基本 クライアントスコープから Subject (sub) プロトコルマッパーを削除できます。ただし、Pairwise サブジェクト識別子 マッパーの前に Subject (sub) プロトコルマッパーが厳密に必要ではないため、pairwise 値は Subject マッパーによって追加された値を上書きします。これは Subject マッパーの 優先度 が原因です。したがって、ビルトイン Subject (sub) マッパーを削除する唯一の利点は、プロトコルマッパーを使用しないことでパフォーマンスを少し保存することですが、効果がない場合があります。
13.4.5. 軽量アクセストークンの使用
Red Hat build of Keycloak のアクセストークンには、個人識別情報 (PII) などの機密情報が含まれています。そのため、リソースサーバーからこの種の情報をクライアントなどの第三者に開示する必要がない場合のために、Red Hat build of Keycloak では、アクセストークンから PII を削除する軽量アクセストークンをサポートしています。さらに、アクセストークンから削除された PII をリソースサーバーで取得する場合は、アクセストークンを Red Hat build of Keycloak のトークンイントロスペクションエンドポイントに送信することで PII を取得できます。
- 軽量アクセストークンから削除できない情報
-
プロトコルマッパーは、アクセストークンに格納される情報を制御でき、軽量アクセストークンはプロトコルマッパーを使用します。したがって、以下の情報は軽量アクセスから削除できません。
exp,iat,jti,iss,typ,azp,sid,scopecnf - Red Hat build of Keycloak での軽量アクセストークンの使用
-
クライアントポリシー の
use-lightweight-access-tokenエグゼキューターをクライアントに適用すると、クライアントがアクセストークンの代わりに軽量アクセストークンを受け取れるようになります。プロトコルマッパーの設定Add to lightweight access token(デフォルトはオフ) がオンの場合、軽量アクセストークンに、プロトコルマッパーによって制御されるクレームが追加されます。また、プロトコルマッパーのAdd to token introspection設定をオンにすると、クライアントがアクセストークンを Red Hat build of Keycloak のトークンイントロスペクションエンドポイントに送信してクレームを取得できるようになります。 - イントロスペクションエンドポイント
-
場合によっては、
Accept: application/jsonではなく HTTP ヘッダーAccept: application/jwtでトークンイントロスペクションエンドポイントをトリガーすると便利です。これは、特に軽量アクセストークンの場合に役立ちます。アプリケーションのセキュリティー保護 セクション のトークンイントロスペクションエンドポイント の詳細を 参照し てください。
