2.4. 使用 SAML 保护应用程序

流程

1. 导航到红帽构建的 Keycloak Admin 控制台。

2. 创建客户端。

   1. 单击 Clients，然后单击 Create client。
   2. 选择 SAML 作为客户端 类型。

   3. 输入您要保护为客户端 ID 的应用程序的 URL。例如： 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. 输入以下信息：

      • 根 URL ：应用程序的 URL，例如 http://localhost:8080/simple-webapp-example/。

      • 主页 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 的值来解决错误。

      • 有效的 Redirect URI：用户登录后允许的 URI，例如 http://localhost:8080/simple-webapp-example/secured/*。

      • Master SAML 处理 URL ：应用程序的 URL 后跟 saml。例如： http://localhost:8080/simple-webapp-example/saml。

        重要

        如果您没有将 saml 附加到 URL，您会收到重定向错误。

        如需更多信息，请参阅创建 SAML 客户端。

流程

1. 使用 jboss-eap-installation-manager 将所需的 Keycloak SAML 适配器层添加到服务器。以下是可用层的详情：

   • feature pack: org.keycloak:keycloak-saml-adapter-galleon-pack.

   • 层 ：

     • keycloak-client-saml ：使用此层来保护 servlet。

     • keycloak-client-saml-ejb ：使用此层将身份从 servlet 传播到 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. 在应用程序的 web.xml 中添加登录配置，并将身份验证方法指定为 SAML。

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

        1

        使用 SAML 保护应用程序。

     2. 从红帽构建的 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. 从红帽构建的 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. 使用应用程序 WAR 的名称（如 simple-webapp-example.war ）更新客户端配置文件中出现的每个 WAR.war。

        注意

        生成的 CLI 脚本在第二个语句的末尾缺少 ） ：

        /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。

   您将被重定向到红帽构建的 Keycloak 登录页面。

2. 您可以使用您在红帽构建的 Keycloak 中定义的用户凭证登录。