hostname-strict 参数详解
功能说明
默认情况下,Keycloak 要求配置 hostname 选项并且不会动态解析 URL。这是一个安全措施。
安全原理
Keycloak 会自由地披露自己的 URL,例如通过 OIDC Discovery 端点,或作为电子邮件中密码重置链接的一部分。如果主机名是从主机名头动态解释的,它可能为潜在攻击者提供操作电子邮件中 URL 的机会,将用户重定向到攻击者的虚假域,并窃取敏感数据,如操作令牌、密码等。
配置选项
生产环境(默认 hostname-strict = true
)
# 必须显式配置 hostname 或设置 hostname-strict=false
bin/kc.sh start --hostname my.keycloak.org
开发环境(默认 hostname-strict = false
)
# 开发模式下默认允许动态解析
bin/kc.sh start-dev
Docker 配置示例
启用严格模式(生产推荐)
keycloak:
environment:
KC_HOSTNAME: https://my.keycloak.org
KC_HOSTNAME_STRICT: "true" # 生产环境默认值
command:
- start
- --hostname=https://my.keycloak.org
禁用严格模式(开发/测试)
keycloak:
environment:
KC_HOSTNAME_STRICT: "false"
command:
- start-dev
- --hostname-strict=false
代理配置场景
使用反向代理时
keycloak:
environment:
KC_HOSTNAME_STRICT: "false"
KC_PROXY_HEADERS: "forwarded" # 或 "xforwarded"
command:
- start
- --hostname-strict=false
- --proxy-headers=forwarded
验证规则
根据官方文档,以下验证规则适用:
生产模式下:必须显式配置
--hostname
或--hostname-strict=false
开发模式下:
--hostname-strict=false
是默认值如果未配置 hostname
:
hostname-backchannel-dynamic
必须设置为 falsehostname-strict
必须设置为 false
调试工具
要排查主机名配置问题,可以使用专用的调试工具:
bin/kc.sh start --hostname=mykeycloak --hostname-debug=true
然后访问:http://mykeycloak:8080/realms/<your-realm>/hostname-debug
实际应用建议
开发环境
environment:
KC_HOSTNAME_STRICT: "false"
KC_HTTP_ENABLED: "true"
command:
- start-dev
- --hostname-strict=false
生产环境
environment:
KC_HOSTNAME: "https://keycloak.example.com"
KC_HOSTNAME_STRICT: "true"
command:
- start
- --hostname=https://keycloak.example.com
这个参数对于 Keycloak 的安全性非常重要,特别是在生产环境中防止主机名劫持攻击。
Last updated
Was this helpful?