Keycloak SAML Galleon 機能パックの詳細設定

`keycloak-saml.xml` 設定ファイルの要素詳細リスト

このガイドでは、Keycloak SAML Galleon 機能パックで使用される keycloak-saml.xml 設定ファイルの要素詳細リストを示します。

SP 要素

SP 要素の属性の説明を以下に示します。

<SP entityID="sp"
    sslPolicy="ssl"
    nameIDPolicyFormat="format"
    forceAuthentication="true"
    isPassive="false"
    keepDOMAssertion="true"
    autodetectBearerOnly="false">
...
</SP>

entityID: これは、このクライアントの識別子です。IdP は、通信しているクライアントが誰であるかを判断するためにこの値を必要とします。この設定は必須です。
sslPolicy: これは、アダプターが適用する SSL ポリシーです。有効な値は、ALL、EXTERNAL、および NONE です。ALL の場合、すべてのリクエストは HTTPS 経由で送信される必要があります。EXTERNAL の場合、非プライベート IP アドレスのみが HTTPS 経由で送信される必要があります。NONE の場合、HTTPS 経由で送信されるリクエストは不要です。この設定はオプションです。デフォルト値は EXTERNAL です。
nameIDPolicyFormat: SAML クライアントは、特定の NameID Subject 形式をリクエストできます。特定の形式が必要な場合は、この値を入力します。これは、標準の SAML 形式識別子である必要があります: urn:oasis:names:tc:SAML:2.0:nameid-format:transient。この設定はオプションです。デフォルトでは、特別な形式はリクエストされません。
forceAuthentication: SAML クライアントは、ユーザーが IdP に既にログインしている場合でも、再認証されるようにリクエストできます。有効にするには、これを true に設定します。この設定はオプションです。デフォルト値は false です。
isPassive: SAML クライアントは、ユーザーが IdP にログインしていない場合でも、認証を求められないようにリクエストできます。これが必要な場合は、true に設定します。forceAuthentication とは反対であるため、一緒に使用しないでください。この設定はオプションです。デフォルト値は false です。
turnOffChangeSessionIdOnLogin: セッション ID は、セキュリティ攻撃ベクトルをプラグインするために、一部のプラットフォームでのログイン成功時にデフォルトで変更されます。これを無効にするには、true に変更します。オフにしないことをお勧めします。デフォルト値は false です。
autodetectBearerOnly: アプリケーションが Web アプリケーションと Web サービス (SOAP や REST など) の両方を提供する場合は、これを true に設定する必要があります。これにより、Web アプリケーションの認証されていないユーザーを Keycloak ログインページにリダイレクトできますが、ログインページへのリダイレクトを理解できない SOAP または REST クライアントには HTTP 401 ステータスコードを送信できます。Keycloak は、X-Requested-With、SOAPAction、または Accept などの一般的なヘッダーに基づいて SOAP または REST クライアントを自動検出します。デフォルト値は false です。
logoutPage: これは、ログアウト後に表示するページを設定します。ページが http://web.example.com/logout.html などの完全な URL の場合、ユーザーはログアウト後、HTTP 302 ステータスコードを使用してそのページにリダイレクトされます。スキーム部分のないリンク (/logout.jsp など) が指定されている場合、web.xml の security-constraint 宣言に従って保護された領域にあるかどうかに関係なく、ログアウト後にページが表示され、ページはデプロイメントコンテキストルートを基準に解決されます。
keepDOMAssertion: この属性は、リクエストに関連付けられた SamlPrincipal 内にアサーションの DOM 表現を元の形式でアダプターに保存させるために、true に設定する必要があります。アサーションドキュメントは、プリンシパル内の getAssertionDocument メソッドを使用して取得できます。これは、署名付きアサーションを再生する場合に特に役立ちます。返されるドキュメントは、Keycloak サーバーによって受信された SAML レスポンスを解析して生成されたものです。この設定はオプションであり、デフォルト値はfalse です (ドキュメントはプリンシパル内に保存されません)。

サービスプロバイダーのキーとキー要素

IdP がクライアントアプリケーション (または SP) にすべてのリクエストに署名することを要求する場合、または IdP がアサーションを暗号化する場合、これを行うために使用するキーを定義する必要があります。クライアント署名付きドキュメントの場合は、ドキュメントの署名に使用されるプライベートキーとパブリックキーまたは証明書の両方を定義する必要があります。暗号化の場合、復号化に使用されるプライベートキーのみを定義する必要があります。

キーを記述する方法は 2 つあります。Java KeyStore 内に格納するか、PEM 形式で keycloak-saml.xml 内にキーを直接コピー/ペーストできます。

        <Keys>
            <Key signing="true" >
               ...
            </Key>
        </Keys>

Key 要素には、オプションの属性 signing と encryption が 2 つあります。true に設定すると、これらの属性はキーが何に使用されるかをアダプターに伝えます。両方の属性が true に設定されている場合、キーはドキュメントの署名と暗号化されたアサーションの復号化の両方に使用されます。これらの属性の少なくとも 1 つを true に設定する必要があります。

KeyStore 要素

Key 要素内で、Java キーストアからキーと証明書をロードできます。これは、KeyStore 要素内で宣言されます。

        <Keys>
            <Key signing="true" >
                <KeyStore resource="/WEB-INF/keystore.jks" password="store123">
                    <PrivateKey alias="myPrivate" password="test123"/>
                    <Certificate alias="myCertAlias"/>
                </KeyStore>
            </Key>
        </Keys>

KeyStore 要素で定義されている XML 設定属性を以下に示します。

file: キーストアへのファイルパス。このオプションはオプションです。file または resource 属性を設定する必要があります。
resource: KeyStore への WAR リソースパス。これは、ServletContext.getResourceAsStream() へのメソッド呼び出しで使用されるパスです。このオプションはオプションです。file または resource 属性を設定する必要があります。
password: KeyStore のパスワード。このオプションは必須です。

SP がドキュメントに署名するために使用するキーを定義する場合は、Java KeyStore 内のプライベートキーと証明書への参照も指定する必要があります。上記の例の PrivateKey 要素と Certificate 要素は、キーストア内のキーまたは証明書を指す alias を定義します。キーストアは、プライベートキーにアクセスするために追加のパスワードが必要です。PrivateKey 要素では、password 属性内にこのパスワードを定義する必要があります。

Key PEMS

Key 要素内で、サブ要素 PrivateKeyPem、PublicKeyPem、および CertificatePem を使用して、キーと証明書を直接宣言します。これらの要素に含まれる値は、PEM キー形式に準拠している必要があります。通常、openssl や同様のコマンドラインツールを使用してキーを生成する場合にこのオプションを使用します。

<Keys>
   <Key signing="true">
      <PrivateKeyPem>
         2341251234AB31234==231BB998311222423522334
      </PrivateKeyPem>
      <CertificatePem>
         211111341251234AB31234==231BB998311222423522334
      </CertificatePem>
   </Key>
</Keys>

SP PrincipalNameMapping 要素

この要素はオプションです。HttpServletRequest.getUserPrincipal() などのメソッドから取得する Java Principal オブジェクトを作成する場合、Principal.getName() メソッドによって返される名前を定義できます。

<SP ...>
  <PrincipalNameMapping policy="FROM_NAME_ID"/>
</SP>

<SP ...>
  <PrincipalNameMapping policy="FROM_ATTRIBUTE" attribute="email" />
</SP>

policy 属性は、この値を設定するために使用されるポリシーを定義します。この属性に使用できる値は次のとおりです。

FROM_NAME_ID: このポリシーは、SAML サブジェクト値をそのまま使用します。これはデフォルト設定です。
FROM_ATTRIBUTE: これは、サーバーから受信した SAML アサーションで宣言された属性の 1 つから値を取得します。attribute XML 属性内で使用する SAML アサーション属性の名前を指定する必要があります。

RoleIdentifiers 要素

RoleIdentifiers 要素は、ユーザーから受信したアサーション内のどの SAML 属性をユーザーの Jakarta EE セキュリティコンテキスト内のロール識別子として使用する必要があるかを定義します。

<RoleIdentifiers>
     <Attribute name="Role"/>
     <Attribute name="member"/>
     <Attribute name="memberOf"/>
</RoleIdentifiers>

デフォルトでは、Role 属性値は Jakarta EE ロールに変換されます。一部の IdP は、member または memberOf 属性アサーションを使用してロールを送信します。1 つ以上の Attribute 要素を定義して、ロールに変換する必要がある SAML 属性を指定できます。

RoleMappingsProvider 要素

RoleMappingsProvider はオプションの要素であり、SAML アダプターで使用される org.keycloak.adapters.saml.RoleMappingsProvider SPI 実装の ID と設定の指定を可能にします。

Keycloak が IDP として使用されている場合、組み込みのロールマッパーを使用して、SAML アサーションに追加する前にロールをマッピングすることができます。ただし、SAML アダプターを使用してサードパーティ IDP に SAML リクエストを送信することができ、この場合、アサーションから抽出されたロールを SP で必要な別のロールセットにマッピングする必要がある場合があります。RoleMappingsProvider SPI を使用すると、必要なマッピングを実行するために使用できるプラグ可能なロールマッパーの設定が可能になります。

プロバイダーの設定は次のようになります。

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

id 属性は、インストールされているプロバイダーのどれを使用するかを識別します。Property サブ要素は、プロバイダーの設定プロパティを指定するために複数回使用できます。

プロパティベースのロールマッピングプロバイダー

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

このプロバイダーは、使用される properties ファイルの場所を指定するために使用できる 2 つの設定プロパティに依存しています。まず、properties.file.location プロパティが指定されているかどうかを確認し、構成された値を使用してファイルシステム内の properties ファイルを検索します。構成されたファイルが見つからない場合、プロバイダーは 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 置換を使用します。たとえば、受信 'role A' は次のように表示されます。

role\u0020A=roleX,roleY

独自のロールマッピングプロバイダーの追加

カスタムロールマッピングプロバイダーを追加するには、org.keycloak.adapters.saml.RoleMappingsProvider SPI を実装するだけです。詳細については、サーバー開発者ガイドの「SAML ロールマッピング SPI」セクションを参照してください。

IDP 要素

IDP 要素のすべての内容は、SP が通信しているアイデンティティプロバイダー (認証サーバー) の設定について説明しています。

<IDP entityID="idp"
     signaturesRequired="true"
     signatureAlgorithm="RSA_SHA1"
     signatureCanonicalizationMethod="http://www.w3.org/2001/10/xml-exc-c14n#">
...
</IDP>

IDP 要素宣言内で指定できる属性設定オプションを以下に示します。

entityID: これは、IDP の発行者 ID です。この設定は必須です。
signaturesRequired: true に設定すると、クライアントアダプターは IDP に送信するすべてのドキュメントに署名します。また、クライアントは、IDP が送信するすべてのドキュメントに署名することを期待します。このスイッチは、すべてのリクエストタイプとレスポンスタイプのデフォルトを設定しますが、後でこれに対する細かい制御があることがわかります。この設定はオプションであり、デフォルトは false になります。
signatureAlgorithm: これは、IDP が署名付きドキュメントで使用することを期待する署名アルゴリズムです。使用できる値は、RSA_SHA1、RSA_SHA256、RSA_SHA512、および DSA_SHA1 です。この設定はオプションであり、デフォルトは RSA_SHA256 です。SHA1 ベースのアルゴリズムは非推奨であり、将来削除される可能性があることに注意してください。*_SHA1 の代わりに、より安全なアルゴリズムを使用することをお勧めします。また、*_SHA1 アルゴリズムでは、SAML サーバー (通常は Keycloak) が Java 17 以降で実行されている場合、署名の検証は機能しません。
signatureCanonicalizationMethod: これは、IDP が署名付きドキュメントで使用することを期待する署名正規化メソッドです。この設定はオプションです。デフォルト値は http://www.w3.org/2001/10/xml-exc-c14n# であり、ほとんどの IDP に適しています。
metadataUrl: IDP メタデータを取得するために使用される URL。現在、これは署名キーと暗号化キーを定期的に取得するためにのみ使用され、SP 側で手動で変更することなく IDP でこれらのキーをローテーションできます。

IDP AllowedClockSkew サブ要素

AllowedClockSkew オプションのサブ要素は、IDP と SP 間の許容クロックスキューを定義します。デフォルト値は 0 です。

<AllowedClockSkew unit="MILLISECONDS">3500</AllowedClockSkew>

unit: この要素の値に添付する時間単位を定義できます。使用できる値は、MICROSECONDS、MILLISECONDS、MINUTES、NANOSECONDS、および SECONDS です。これはオプションです。デフォルト値は SECONDS です。

IDP SingleSignOnService サブ要素

SingleSignOnService サブ要素は、IDP のログイン SAML エンドポイントを定義します。クライアントアダプターは、ログインしたい場合、この要素内の設定を介してフォーマットされたリクエストを IDP に送信します。

<SingleSignOnService signRequest="true"
                     validateResponseSignature="true"
                     requestBinding="post"
                     bindingUrl="url"/>

この要素で定義できる設定属性を以下に示します。

signRequest: クライアントは認証リクエストに署名する必要がありますか? この設定はオプションです。IDP signaturesRequired 要素値がデフォルトになります。
validateResponseSignature: クライアントは、認証リクエストから返送されたアサーションレスポンスドキュメントに IDP が署名することを期待する必要がありますか? この設定はオプションです。IDP signaturesRequired 要素値がデフォルトになります。
requestBinding: これは、IDP との通信に使用される SAML バインディングタイプです。この設定はオプションです。デフォルト値は POST ですが、REDIRECT に設定することもできます。
responseBinding: SAML を使用すると、クライアントは認証レスポンスで使用するバインディングタイプをリクエストできます。これの値は POST または REDIRECT にすることができます。この設定はオプションです。デフォルトでは、クライアントはレスポンスに特定のバインディングタイプをリクエストしません。
assertionConsumerServiceUrl: IDP ログインサービスがレスポンスを送信する必要があるアサーションコンシューマーサービス (ACS) の URL。この設定はオプションです。デフォルトでは設定されておらず、IdP の構成に依存しています。設定する場合は、/saml で終わる必要があります (例: http://sp.domain.com/my/endpoint/for/saml)。このプロパティの値は、SAML AuthnRequest メッセージの AssertionConsumerServiceURL 属性で送信されます。このプロパティには通常、responseBinding 属性が伴います。
bindingUrl: これは、クライアントがリクエストを送信する IDP ログインサービスの URL です。この設定は必須です。

IDP SingleLogoutService サブ要素

SingleLogoutService サブ要素は、IDP のログアウト SAML エンドポイントを定義します。クライアントアダプターは、ログアウトしたい場合、この要素内の設定を介してフォーマットされたリクエストを IDP に送信します。

<SingleLogoutService validateRequestSignature="true"
                     validateResponseSignature="true"
                     signRequest="true"
                     signResponse="true"
                     requestBinding="redirect"
                     responseBinding="post"
                     postBindingUrl="posturl"
                     redirectBindingUrl="redirecturl">

signRequest: クライアントは IDP へのログアウトリクエストに署名する必要がありますか? この設定はオプションです。IDP signaturesRequired 要素値がデフォルトになります。
signResponse: クライアントは IDP リクエストに送信するログアウトレスポンスに署名する必要がありますか? この設定はオプションです。IDP signaturesRequired 要素値がデフォルトになります。
validateRequestSignature: クライアントは IDP からの署名付きログアウトリクエストドキュメントを期待する必要がありますか? この設定はオプションです。IDP signaturesRequired 要素値がデフォルトになります。
validateResponseSignature: クライアントは IDP からの署名付きログアウトレスポンスドキュメントを期待する必要がありますか? この設定はオプションです。IDP signaturesRequired 要素値がデフォルトになります。
requestBinding: これは、SAML リクエストを IDP に通信するために使用される SAML バインディングタイプです。この設定はオプションです。デフォルト値は POST ですが、REDIRECT に設定することもできます。
responseBinding: これは、SAML レスポンスを IDP に通信するために使用される SAML バインディングタイプです。これの値は POST または REDIRECT にすることができます。この設定はオプションです。デフォルト値は POST ですが、REDIRECT に設定することもできます。
postBindingUrl: これは、POST バインディングを使用する場合の IDP のログアウトサービスの URL です。POST バインディングを使用する場合は、この設定は必須です。
redirectBindingUrl: これは、REDIRECT バインディングを使用する場合の IDP のログアウトサービスの URL です。REDIRECT バインディングを使用する場合は、この設定は必須です。

IDP Keys サブ要素

IDP の Keys サブ要素は、IDP によって署名されたドキュメントを検証するために使用する証明書または公開キーを定義するためにのみ使用されます。SP の Keys 要素と同じ方法で定義されます。ただし、証明書または公開キー参照を 1 つだけ定義する必要があります。IDP と SP の両方がそれぞれ Keycloak サーバーとアダプターによって実現されている場合、署名検証のキーを指定する必要はありません。以下を参照してください。

SP と IDP の両方が Keycloak によって実装されている場合、公開された証明書から IDP 署名検証用の公開キーを自動的に取得するように SP を構成できます。これは、Keys サブ要素の署名検証キーのすべての宣言を削除することで行われます。Keys サブ要素が空のままである場合、完全に省略できます。キーは、IDP SingleSignOnService サブ要素で指定された SAML エンドポイント URL から派生した場所である SAML 記述子から SP によって自動的に取得されます。SAML 記述子の取得に使用される HTTP クライアントの設定は通常、追加の設定を必要としませんが、IDP HttpClient サブ要素で構成できます。

署名検証に複数のキーを指定することもできます。これは、signing 属性が true に設定された複数の Key 要素を Keys サブ要素内で宣言することで行われます。これは、IDP 署名キーがローテーションされる場合に役立ちます。通常、新しい SAML プロトコルメッセージとアサーションが新しいキーで署名されますが、以前のキーで署名されたメッセージとアサーションも引き続き受け入れられる必要がある移行期間があります。

署名検証用のキーを自動的に取得し、追加の静的署名検証キーを定義するように Keycloak を構成することはできません。

       <IDP entityID="idp">
            ...
            <Keys>
                <Key signing="true">
                    <KeyStore resource="/WEB-INF/keystore.jks" password="store123">
                        <Certificate alias="demo"/>
                    </KeyStore>
                </Key>
            </Keys>
        </IDP>

IDP HttpClient サブ要素

HttpClient オプションのサブ要素は、有効になっている場合に IDP の SAML 記述子を介して IDP 署名検証用の公開キーを含む証明書を自動的に取得するために使用される HTTP クライアントのプロパティを定義します。

<HttpClient connectionPoolSize="10"
            disableTrustManager="false"
            allowAnyHostname="false"
            clientKeystore="classpath:keystore.jks"
            clientKeystorePassword="pwd"
            truststore="classpath:truststore.jks"
            truststorePassword="pwd"
            proxyUrl="http://proxy/"
            socketTimeout="5000"
            connectionTimeout="6000"
            connectionTtl="500" />

connectionPoolSize: この設定オプションは、Keycloak サーバーへの接続をいくつプールする必要があるかを定義します。これはオプションです。デフォルト値は 10 です。
disableTrustManager: Keycloak サーバーが HTTPS を必要とし、この設定オプションが true に設定されている場合、トラストストアを指定する必要はありません。この設定は開発中にのみ使用する必要があり、SSL 証明書の検証を無効にするため、本番環境では絶対に使用しないでください。これはオプションです。デフォルト値は false です。
allowAnyHostname: Keycloak サーバーが HTTPS を必要とし、この設定オプションが true に設定されている場合、Keycloak サーバーの証明書はトラストストアを介して検証されますが、ホスト名検証は実行されません。この設定は開発中にのみ使用する必要があり、SSL 証明書の検証を部分的に無効にするため、本番環境では絶対に使用しないでください。この設定はテスト環境で役立つ場合があります。これはオプションです。デフォルト値は false です。
truststore: 値は、トラストストアファイルへのファイルパスです。パスの先頭に classpath: を付けると、トラストストアはデプロイメントのクラスパスから取得されます。Keycloak サーバーへの送信 HTTPS 通信に使用されます。HTTPS リクエストを行うクライアントは、通信しているサーバーのホストを検証する方法が必要です。これがトラストストアの役割です。キーストアには、1 つ以上の信頼できるホスト証明書または認証局が含まれています。Keycloak サーバーの SSL キーストアの公開証明書を抽出することで、このトラストストアを作成できます。disableTrustManager が true でない限り、これは必須です。
truststorePassword: トラストストアのパスワード。truststore が設定されており、トラストストアにパスワードが必要な場合は、これは必須です。
clientKeystore: これは、キーストアファイルへのファイルパスです。このキーストアには、アダプターが Keycloak サーバーに HTTPS リクエストを行う場合の両方向 SSL 用のクライアント証明書が含まれています。これはオプションです。
clientKeystorePassword: クライアントキーストアおよびクライアントのキーのパスワード。clientKeystore が設定されている場合は、これは必須です。
proxyUrl: HTTP 接続に使用する HTTP プロキシへの URL。これはオプションです。
socketTimeout: 接続確立後、データが到着するまでソケットが待機するタイムアウト (ミリ秒単位)。2 つのデータパケット間の最大非アクティブ時間。タイムアウト値 0 は無限タイムアウトとして解釈されます。負の値は未定義 (該当する場合はシステムデフォルト) として解釈されます。デフォルト値は -1 です。これはオプションです。
connectionTimeout: リモートホストとの接続を確立するためのタイムアウト (ミリ秒単位)。タイムアウト値 0 は無限タイムアウトとして解釈されます。負の値は未定義 (該当する場合はシステムデフォルト) として解釈されます。デフォルト値は -1 です。これはオプションです。
connectionTtl: クライアントの接続 Time-To-Live (ミリ秒単位)。0 以下の値は無限値として解釈されます。デフォルト値は -1 です。これはオプションです。

このページの内容

このガイドを編集