7.5. RoleMappingsProvider 要素

Red Hat build of Keycloak には、properties ファイルを使用してロールマッピングを実行する RoleMappingsProvider 実装が含まれています。このプロバイダーは id properties-based-role-mapper によって識別され、org.keycloak.adapters.saml.PropertiesBasedRoleMapper クラスによって実装されます。

このプロバイダーは、使用される properties ファイルの場所を指定するために使用できる 2 つの設定プロパティーに依存します。最初に、設定値を使用して、ファイルシステムで properties ファイルを見つけることで、properties.file.location プロパティーが指定されているかどうかを確認します。設定したファイルが見つからない場合、プロバイダーは RuntimeException を出力します。以下のスニペットは、properties.file.configuration オプションを使用して、ファイルシステムの /opt/mappers/ ディレクトリーから roles.properties ファイルを読み込むプロバイダーの例を示しています。

    <RoleMappingsProvider id="properties-based-role-mapper">
        <Property name="properties.file.location" value="/opt/mappers/roles.properties"/>
    </RoleMappingsProvider>

properties.file.location 設定が設定されていない場合、プロバイダーは properties.resource.location プロパティーをチェックし、設定した値を使用して WAR リソースから properties ファイルを読み込みます。この設定プロパティーがない場合、プロバイダーはデフォルトで /WEB-INF/role-mappings.properties からファイルを読み込もうとします。リソースからファイルを読み込めない場合、プロバイダーは RuntimeException を出力します。以下のスニペットは、properties.resource.location を使用してアプリケーションの /WEB-INF/conf/ ディレクトリーから roles.properties ファイルを読み込むプロバイダーの例を示しています。

    <RoleMappingsProvider id="properties-based-role-mapper">
        <Property name="properties.resource.location" value="/WEB-INF/conf/roles.properties"/>
    </RoleMappingsProvider>

properties ファイルには、ロールとプリンシパルの両方をキーとして含めることができ、0 つ以上のロールを値としてコンマで区切ります。呼び出されると、実装はアサーションから抽出したロールのセットを繰り返し処理し、各ロールについて、マッピングが存在するかどうかを確認します。ロールが空ロールにマップする場合、これは破棄されます。1 つ以上の異なるロールのセットにマップすると、これらのロールは結果セットに設定されます。ロールのマッピングが見つからない場合は、結果セットに組み込まれます。

ロールの処理後、アサーションから抽出したプリンシパルにエントリーの properties ファイルが含まれるかどうかを確認します。プリンシパルのマッピングが存在する場合は、値としてリスト表示されるすべてのロールが結果セットに追加されます。これにより、追加のロールをプリンシパルに割り当てることができます。

たとえば、プロバイダーが以下のプロパティーファイルで設定されていると仮定します。

roleA=roleX,roleY
roleB=

kc_user=roleZ

プリンシパル kc_user が、roleA、roleB、および roleC があるアサーションから抽出されると、プリンシパルに割り当てられたロールの最終セットは roleC、roleX、roleY、および roleZ になります。なぜなら roleA が roleX および roleY にマッピングされ、roleB が空のロールにマッピングされて破棄され、roleC がそのまま使用され、追加ロールが kc_user プリンシパル (roleZ) に追加されるためです。

注記: マッピングのロール名にスペースを使用するには、Unicode の空白文字を使用してください。たとえば、受信した 'ロール A' は以下のように表示されます。

role\u0020A=roleX,roleY