使用Keycloak SAML保护Java应用登录后出现循环重定向问题

问题描述 #

使用Keycloak SAML保护Java应用，通过SamlFilter实现认证，登录成功后出现持续循环重定向：Keycloak重定向回应用后，应用立即再次跳转回Keycloak，无法正常进入应用页面。

相关配置 #

1. web.xml过滤器配置片段 #

<filter>
   <filter-name>APP</filter-name>
   <filter-class>org.keycloak.adapters.saml.servlet.SamlFilter</filter-class>
</filter>
<filter-mapping>
   <filter-name>APP</filter-name>
   <url-pattern>/*</url-pattern>
</filter-mapping> 

2. WEB-INF/keycloak-saml.xml配置 #

<keycloak-saml-adapter>
<SP entityID="Sample"
    sslPolicy="EXTERNAL"
    logoutPage="logout">
    <Keys>
        <Key signing="true">
            <PrivateKeyPem>
                <!-- Private Key -->
            </PrivateKeyPem>
            <CertificatePem>
              <!-- Certi Key -->
            </CertificatePem>
        </Key>
    </Keys>
    <IDP entityID="idp"
         signatureAlgorithm="RSA_SHA256"
         signatureCanonicalizationMethod="http://www.w3.org/2001/10/xml-exc-c14n#"
         metadataUrl="http://localhost:8280/realms/IDP_REALM/protocol/saml/descriptor">
        <SingleSignOnService signRequest="true"
                             validateResponseSignature="true"
                             validateAssertionSignature="false"
                             requestBinding="POST"
                             bindingUrl="http://localhost:8280/realms/IDP_REALM/protocol/saml"/>
        <SingleLogoutService signRequest="true"
                             signResponse="true"
                             validateRequestSignature="true"
                             validateResponseSignature="true"
                             requestBinding="POST"
                             responseBinding="POST"
                             postBindingUrl="http://localhost:8280/realms/IDP_REALM/protocol/saml"
                             redirectBindingUrl="http://localhost:8280/realms/IDP_REALM/protocol/saml"/>
         <Keys>
            <Key signing="true">
                <KeyStore resource="/WEB-INF/keystore.jks" password="store123">
                    <Certificate alias="Sample"/>
                </KeyStore>
            </Key>
        </Keys>
    </IDP>
</SP>
</keycloak-saml-adapter>

排查方向与解决方案 #

循环重定向通常是应用无法识别已完成的SAML认证会话，或配置不匹配导致认证状态无法正确校验，以下是关键修复点：

1. 补充SP的断言消费者服务（ACS）配置 #

当前keycloak-saml.xml的<SP>节点缺少Assertion Consumer Service配置，这是SAML协议中SP接收IDP认证断言的核心端点，未配置的话应用无法正确处理IDP返回的认证响应，会重复发起认证请求。

需在<SP>节点内添加ACS配置，示例：

<SP entityID="Sample"
    sslPolicy="EXTERNAL"
    logoutPage="logout">
    <!-- 原有Keys配置 -->
    <AssertionConsumerService index="0"
                               isDefault="true"
                               bindingUrl="http://你的应用域名/应用上下文路径/saml/acs"
                               binding="POST"/>
    <!-- 原有IDP配置 -->
</SP>

注意：bindingUrl必须与Keycloak客户端配置中的Valid Redirect URIs完全一致（包含协议、域名、端口、路径）。

2. 校验Keycloak客户端配置 #

• 确认Keycloak客户端的Valid Redirect URIs包含上述ACS的bindingUrl，格式正确（可精确匹配或用通配符，如http://localhost:8080/your-app/saml/acs/*）。
• 确认客户端的Base URL设置正确，指向应用根路径。
• 检查客户端的SAML Signature Algorithm与keycloak-saml.xml中signatureAlgorithm="RSA_SHA256"一致。

3. 调整过滤器拦截规则（可选） #

当前过滤器拦截/*所有请求，虽SamlFilter本身可处理回调，但若存在其他过滤器冲突，可能导致会话无法正确建立。可尝试明确指定回调路径的调度类型：

<filter-mapping>
   <filter-name>APP</filter-name>
   <url-pattern>/*</url-pattern>
   <dispatcher>REQUEST</dispatcher>
</filter-mapping>
<filter-mapping>
   <filter-name>APP</filter-name>
   <url-pattern>/saml/acs</url-pattern>
   <dispatcher>REQUEST</dispatcher>
   <dispatcher>FORWARD</dispatcher>
</filter-mapping>

4. 修正IDP密钥配置 #

当前IDP的<Keys>节点引用了SP自身的keystore，这会导致签名验证失败，应替换为Keycloak Realm的签名证书，或直接删除IDP下的<Keys>节点，让适配器通过metadataUrl自动加载IDP密钥：

<IDP entityID="idp"
     signatureAlgorithm="RSA_SHA256"
     signatureCanonicalizationMethod="http://www.w3.org/2001/10/xml-exc-c14n#"
     metadataUrl="http://localhost:8280/realms/IDP_REALM/protocol/saml/descriptor">
    <!-- 原有SSO、SLO配置 -->
    <!-- 删除原有IDP下的Keys节点，或替换为Keycloak证书 -->
    <Keys>
        <Key signing="true">
            <CertificatePem>
                <!-- Keycloak Realm的签名证书内容 -->
            </CertificatePem>
        </Key>
    </Keys>
</IDP>

5. 检查会话与Cookie配置 #

• 确保应用服务器的会话Cookie配置正确，若Keycloak与应用在不同域名下，SameSite属性需设置为合适值（如Lax或None）。
• 若启用sslPolicy="EXTERNAL"（外部终止SSL），需确保应用接收的请求头包含X-Forwarded-Proto等信息，避免URL协议不匹配导致会话失效。

总结 #

最核心问题是缺少ACS端点配置，导致应用无法处理Keycloak返回的认证断言，进而重复发起认证请求。优先补充ACS配置并校验Keycloak客户端的重定向URI匹配，再逐步排查密钥、会话等其他因素。

内容的提问来源于stack exchange，提问作者user3458271