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

验证规则

根据官方文档,以下验证规则适用:

  1. 生产模式下:必须显式配置 --hostname--hostname-strict=false

  2. 开发模式下--hostname-strict=false 是默认值

  3. 如果未配置 hostname

    • hostname-backchannel-dynamic 必须设置为 false

    • hostname-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?