2.4. SAML によるアプリケーションの保護

手順

1. Red Hat build of Keycloak 管理コンソールに移動します。

2. クライアントを作成します。

   1. Clients をクリックし、Create client をクリックします。
   2. Client type として SAML を選択します。

   3. 保護するアプリケーションの URL を Client ID として入力します。たとえば、http://localhost:8080/simple-webapp-example/secured/ です。

      重要

      クライアント ID はアプリケーションの URL と正確に一致する必要があります。クライアント ID が一致しない場合は、次のようなエラーが表示されます。

      2023-05-17 19:54:31,586 WARN  [org.keycloak.events] (executor-thread-0) type=LOGIN_ERROR, realmId=eba0f106-389f-4216-a676-05fcd0c0c72e, clientId=null, userId=null, ipAddress=127.0.0.1, error=client_not_found, reason=Cannot_match_source_hash

   4. クライアント名を入力します。たとえば、jbeap-saml です。
   5. Next をクリックします。

   6. 以下の情報を入力します。

      • Root URL: アプリケーションの URL (例: http://localhost:8080/simple-webapp-example/)。

      • Home URL: アプリケーションの URL (例: http://localhost:8080/simple-webapp-example/)。

        重要

        Home URL を設定しないと、クライアント設定の SP entityID が空白のままになり、エラーが発生します。

        • 管理 CLI コマンドを使用すると、次のエラーが発生します。

          Can't reset to root in the middle of the path @72

        それぞれの設定ファイルで SP entityID の値を定義することで、エラーを解決できます。

      • Valid Redirect URI: ユーザーのログイン後に利用可能な URI (例: http://localhost:8080/simple-webapp-example/secured/*)。

      • Master SAML Processing URL: アプリケーションの URL の後に saml を付けます。たとえば、http://localhost:8080/simple-webapp-example/saml です。

        重要

        URL に saml を追加しないと、リダイレクトエラーが発生します。

        詳細は、SAML クライアントの作成 を参照してください。

手順

1. jboss-eap-installation-manager を使用して、必要な Keycloak SAML アダプターレイヤーをサーバーに追加します。利用可能なレイヤーの詳細は次のとおりです。

   • 機能パック: org.keycloak:keycloak-saml-adapter-galleon-pack

   • レイヤー:

     • keycloak-client-saml: このレイヤーを使用してサーブレットを保護します。

     • keycloak-client-saml-ejb: このレイヤーを使用して、サーブレットから Jakarta Enterprise Beans にアイデンティティーを伝播します。

       JBoss EAP での機能パックとレイヤーの追加については、Red Hat JBoss Enterprise Application Platform のインストール方法 ガイドの jboss-eap-installation-manager を使用した既存の JBoss EAP サーバーへの機能パックの追加 を参照してください。

2. アプリケーションの web.xml を設定して、アプリケーションリソースを保護します。

   <?xml version="1.0" encoding="UTF-8"?>
   
   <web-app version="2.5" xmlns="http://java.sun.com/xml/ns/javaee"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
       metadata-complete="false">
   
       <security-constraint>
           <web-resource-collection>
               <web-resource-name>secured</web-resource-name>
               <url-pattern>/secured</url-pattern>
           </web-resource-collection>
   
           <auth-constraint>
               <role-name>Admin</role-name>    1
           </auth-constraint>
       </security-constraint>
   
       <security-role>
           <role-name>*</role-name>
       </security-role>
   </web-app>

   1

   Admin ロールを持つユーザーのみがアプリケーションにアクセスできるようにします。任意のロールを持つユーザーがアプリケーションにアクセスできるようにするには、role-name の値としてワイルドカード ** を使用します。

3. 管理 CLI を使用するか、アプリケーションのデプロイメントを更新することにより、SAML でアプリケーションを保護します。

   • アプリケーションのデプロイメントを更新する場合

     1. 認証方法として SAML を指定するログイン設定を、アプリケーションの web.xml に追加します。

        <web-app>
        ...
            <login-config>
                <auth-method>SAML</auth-method>     1
            </login-config>
        ...
        </web-app>

        1

        SAML を使用してアプリケーションを保護します。

     2. Red Hat build of Keycloak から keycloak-saml.xml 設定ファイルをダウンロードし、アプリケーションの WEB-INF/ ディレクトリーに保存します。

        詳細は、クライアントアダプター設定の生成 を参照してください。

        keycloak-saml.xml の例

        <keycloak-saml-adapter>
            <SP entityID=""
                sslPolicy="EXTERNAL"
                logoutPage="SPECIFY YOUR LOGOUT PAGE!">
                <Keys>
                    <Key signing="true">
                        <PrivateKeyPem>PRIVATE KEY NOT SET UP OR KNOWN</PrivateKeyPem>
                        <CertificatePem>...</CertificatePem>
                    </Key>
                </Keys>
                <IDP entityID="idp"
                     signatureAlgorithm="RSA_SHA256"
                     signatureCanonicalizationMethod="http://www.w3.org/2001/10/xml-exc-c14n#">
                    <SingleSignOnService signRequest="true"
                                         validateResponseSignature="true"
                                         validateAssertionSignature="false"
                                         requestBinding="POST"
                                         bindingUrl="http://localhost:8180/realms/example_saml_realm/protocol/saml"/>
                    <SingleLogoutService signRequest="true"
                                         signResponse="true"
                                         validateRequestSignature="true"
                                         validateResponseSignature="true"
                                         requestBinding="POST"
                                         responseBinding="POST"
                                         postBindingUrl="http://localhost:8180/realms/example_saml_realm/protocol/saml"
                                         redirectBindingUrl="http://localhost:8180/realms/example_saml_realm/protocol/saml"/>
                </IDP>
            </SP>
        </keycloak-saml-adapter>

        PrivateKeyPem および CertificatePem の値は、クライアントごとに一意です。

   • 管理 CLI を使用する場合

     1. Red Hat build of Keycloak からクライアント設定ファイル keycloak-saml-subsystem.cli をダウンロードします。

        詳細は、クライアントアダプター設定の生成 を参照してください。

        keycloak-saml-subsystem.cli の例

        /subsystem=keycloak-saml/secure-deployment=YOUR-WAR.war/:add
        
        /subsystem=keycloak-saml/secure-deployment=YOUR-WAR.war/SP="http://localhost:8080/simple-webapp-example/"/:add(sslPolicy=EXTERNAL,logoutPage="SPECIFY YOUR LOGOUT PAGE!"
        
        /subsystem=keycloak-saml/secure-deployment=YOUR-WAR.war/SP="http://localhost:8080/simple-webapp-example/"/Key=KEY1:add(signing=true, \
        PrivateKeyPem="...", CertificatePem="...")
        
        /subsystem=keycloak-saml/secure-deployment=YOUR-WAR.war/SP="http://localhost:8080/simple-webapp-example/"/IDP=idp/:add( \
            SingleSignOnService={ \
                signRequest=true, \
                validateResponseSignature=true, \
                validateAssertionSignature=false, \
                requestBinding=POST, \
                bindingUrl=http://localhost:8180/realms/example-saml-realm/protocol/saml}, \
            SingleLogoutService={ \
                signRequest=true, \
                signResponse=true, \
                validateRequestSignature=true, \
                validateResponseSignature=true, \
                requestBinding=POST, \
                responseBinding=POST, \
                postBindingUrl=http://localhost:8180/realms/example-saml-realm/protocol/saml, \
                redirectBindingUrl=http://localhost:8180/realms/example-saml-realm/protocol/saml} \
        )
        
        /subsystem=keycloak-saml/secure-deployment=YOUR-WAR.war/SP="http://localhost:8080/simple-webapp-example/"/IDP=idp/:write-attribute(name=signatureAlgorithm,value=RSA_SHA256)
        
        /subsystem=keycloak-saml/secure-deployment=YOUR-WAR.war/SP="http://localhost:8080/simple-webapp-example/"/IDP=idp/:write-attribute(name=signatureCanonicalizationMethod,value=http://www.w3.org/2001/10/xml-exc-c14n#)

        PrivateKeyPem および CertificatePem の値は、クライアントごとに一意です。

     2. クライアント設定ファイル内のすべての YOUR-WAR.war を、実際のアプリケーション WAR の名前 (例: simple-webapp-example.war) で更新します。

        注記

        生成される CLI スクリプトの 2 番目のステートメントの末尾には、) がありません。

        /subsystem=keycloak-saml/secure-deployment=YOUR-WAR.war/SP=""/:add(sslPolicy=EXTERNAL,logoutPage="SPECIFY YOUR LOGOUT PAGE!"

        不足している ) を追加する必要があります。

     3. 管理 CLI を使用して keycloak-saml-subsystem.cli スクリプトを実行して、JBoss EAP を設定します。

        $ <EAP_HOME>/bin/jboss-cli.sh -c --file=<path_to_the_file>/keycloak-saml-subsystem.cli

4. アプリケーションをデプロイします。

   $ mvn wildfly:deploy

検証

1. ブラウザーで、アプリケーションの URL に移動します。たとえば、http://localhost:8080/simple-webapp-example/secured です。

   Red Hat build of Keycloak のログインページにリダイレクトされます。

2. Red Hat build of Keycloak で定義したユーザーの認証情報を使用してログインできます。