Keycloak作为SAML服务器出现empty host name错误求助

1. 修正Docker启动的hostname参数配置 #

Keycloak v21+的hostname配置需保证参数统一、无冲突，建议改用环境变量替代命令行参数，避免解析异常：

docker run --name keycloak_dev2 -p 8089:8080 \
       -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=admin \
       -e KC_HOSTNAME=localhost \
       -e KC_HOSTNAME_PORT=8089 \
       -e KC_HOSTNAME_URL=http://localhost:8089 \
       quay.io/keycloak/keycloak:21.1.2 start-dev

注意：指定具体版本21.1.2而非latest，避免版本差异引发的配置不兼容问题。

2. 检查SAML客户端的重定向URI配置 #

进入Keycloak管理控制台，找到对应SAML客户端：

• 切换至Settings标签页
• 在Valid Redirect URIs中精确填写Python应用的回调地址（如http://your-app-domain/callback，开发环境可临时用*但生产环境必须精确）
• 确认Base URL已正确设置为Python应用的根地址（如http://your-app-domain）

3. 校验RelayState参数格式 #

触发错误的请求中RelayState为应用URL，需满足：

• 必须是完整的绝对路径（包含http://或https://），不能使用相对路径
• 确保URL特殊字符已完成编码（浏览器通常会自动处理，但建议在Python应用中手动编码）

4. 验证Realm的SAML端点配置 #

进入Realm的Settings -> Endpoints -> SAML 2.0 Identity Provider Metadata，检查生成的元数据中：

• AssertionConsumerServiceLocation
• SingleLogoutServiceLocation
  两个字段的域名、端口与Keycloak实例完全一致，无空host值。

5. 开发环境禁用反向代理配置 #

若之前尝试过反向代理相关设置，确保启动命令中未添加KC_PROXY参数，开发环境无需代理，避免干扰hostname解析：

# 移除类似以下的参数
-e KC_PROXY=edge

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