Keycloak作为SP时外部IdP发起SAML 2.0 SSO故障解决问询

场景说明 #

原本Keycloak是Resource1的身份提供商（IdP），用户通过Keycloak用户名密码登录访问该服务。现需实现联邦登录，让Keycloak作为服务提供商（SP），通过SAML 2.0协议对接外部遗留IdP，作为Resource1的认证中间件。

重要提示：仅解决SAML SSO外部IdP发起的登录问题，不接受OpenId Connect或其他SSO协议方案！

测试环境配置 #

• 已将外部IdP元数据导入Keycloak realm的SAML身份提供商配置
• 已将Keycloak（SP）元数据导入外部IdP
• Keycloak realm的SP身份提供商映射器已配置注入realm-management:realm-admin角色，用于访问security-admin-console客户端

Docker Compose配置 #

version: '3'
volumes:
  postgres_data:
      driver: local
services:
  postgres:
      image: postgres
      volumes:
        - postgres_data:/var/lib/postgresql/data
        - "/etc/timezone:/etc/timezone:ro"
        - "/etc/localtime:/etc/localtime:ro"
      environment:
        POSTGRES_DB: keycloak
        POSTGRES_USER: keycloak
        POSTGRES_PASSWORD: password
  keycloak:
      image: quay.io/keycloak/keycloak:legacy
      environment:
        KEYCLOAK_LOGLEVEL: DEBUG
        ROOT_LOGLEVEL: DEBUG
        DB_VENDOR: POSTGRES
        DB_ADDR: postgres
        DB_DATABASE: keycloak
        DB_USER: keycloak
        DB_SCHEMA: public
        DB_PASSWORD: password
        KEYCLOAK_USER: admin
        KEYCLOAK_PASSWORD: BigB4!!s
      ports:
        - 8080:8080
      depends_on:
        - postgres
      volumes:
        - "/etc/timezone:/etc/timezone:ro"
        - "/etc/localtime:/etc/localtime:ro"

问题描述 #

• 本人并非Java开发者
• Keycloak的SAML ACS处理器要求必须填充RelayState参数
• RelayState必须符合格式：{session_code}.{tab_id}.{client_id}，示例：DxcIxIfrTyrYVH-Z6VnY0FrC7I-C5yJcvqHWiN3ZS5k.pT8rTpU6OLA.security-admin-console
• 未指定RelayState时，日志会报client_id为空的错误
• 使用..security-admin-console格式的RelayState时，UI显示"您的登录尝试已超时。登录将从头开始。"，同时日志提示代码未找到

问题解答 #

1. 是否可以修改Keycloak中这种类OpenID的默认行为？ #

可以修改，无需自己编写Java代码的话，有两种可行路径：

• 使用第三方SPI扩展：寻找现成的SAML ACS处理器扩展，替换默认的RelayState校验逻辑；若找不到现成资源，可联系Java开发人员定制简单扩展，跳过session_code和tab_id的校验，仅保留client_id验证。
• 检查配置参数：部分较新的Keycloak版本（如17+的Quarkus版本）可能存在隐藏配置项，可放宽RelayState格式要求，但你当前使用的legacy版本大概率无此配置，需查阅对应版本官方文档确认。

2. 若无法修改，除了可硬编码的client_id外，RelayState中的session_code和tab_id是Keycloak（SP）生成的会话/ Cookie值，外部IdP无法获取，如何生成这些值？或者能否不发送这些值？ #

若无法修改默认行为，可尝试以下两种方案：

• 预生成合法RelayState：先触发Keycloak发起的SSO流程，从请求中捕获合法的RelayState值，将其存储到外部IdP配置中（或通过接口动态获取），后续外部IdP发起登录时直接复用该值。注意此值有有效期，需定期刷新。
• 反向代理修改参数：通过Nginx等反向代理，在请求到达Keycloak前修改ACS请求的RelayState参数，将外部IdP发送的简单值（如仅client_id）替换为符合格式的有效值。例如用Nginx的sub_filter模块，把RelayState: security-admin-console替换为RelayState: {合法session_code}.{合法tab_id}.security-admin-console，前提是能获取到有效的session_code和tab_id。

另外，不能不发送这些值，Keycloak默认ACS处理器会严格校验格式，缺失会直接报错。

3. 外部IdP发起的SAML SSO是否可用？若可用，支持哪些Keycloak版本？ #

外部IdP发起的SAML SSO完全可用，Keycloak从早期版本（如4.x）就支持该模式，包括你当前使用的legacy版本（11-16.x左右的Wildfly版本）以及最新的Quarkus版本（17+）均兼容。

你当前遇到问题，是因为Keycloak默认RelayState校验逻辑为SP发起的SSO设计，针对外部IdP发起的场景，需调整RelayState处理方式或预生成合法值。

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