# hostname-strict 参数详解

## 功能说明

默认情况下，Keycloak 要求配置 hostname 选项并且不会动态解析 URL。这是一个安全措施。

## 安全原理

Keycloak 会自由地披露自己的 URL，例如通过 OIDC Discovery 端点，或作为电子邮件中密码重置链接的一部分。如果主机名是从主机名头动态解释的，它可能为潜在攻击者提供操作电子邮件中 URL 的机会，将用户重定向到攻击者的虚假域，并窃取敏感数据，如操作令牌、密码等。

## 配置选项

**生产环境（默认 `hostname-strict = true`）**

```bash
# 必须显式配置 hostname 或设置 hostname-strict=false
bin/kc.sh start --hostname my.keycloak.org
```

**开发环境（默认 `hostname-strict = false`）**

```bash
# 开发模式下默认允许动态解析
bin/kc.sh start-dev
```

## Docker 配置示例

**启用严格模式（生产推荐）**

```yaml
keycloak:
  environment:
    KC_HOSTNAME: https://my.keycloak.org
    KC_HOSTNAME_STRICT: "true"  # 生产环境默认值
  command:
    - start
    - --hostname=https://my.keycloak.org
```

**禁用严格模式（开发/测试）**

```yaml
keycloak:
  environment:
    KC_HOSTNAME_STRICT: "false"
  command:
    - start-dev
    - --hostname-strict=false
```

## 代理配置场景

**使用反向代理时**

```yaml
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

## 调试工具

要排查主机名配置问题，可以使用专用的调试工具：

```bash
bin/kc.sh start --hostname=mykeycloak --hostname-debug=true
```

然后访问：`http://mykeycloak:8080/realms/<your-realm>/hostname-debug`

## 实际应用建议

**开发环境**

```yaml
environment:
  KC_HOSTNAME_STRICT: "false"
  KC_HTTP_ENABLED: "true"
command:
  - start-dev
  - --hostname-strict=false
```

**生产环境**

```yaml
environment:
  KC_HOSTNAME: "https://keycloak.example.com"
  KC_HOSTNAME_STRICT: "true"
command:
  - start
  - --hostname=https://keycloak.example.com
```

这个参数对于 Keycloak 的安全性非常重要，特别是在生产环境中防止主机名劫持攻击。


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://tuonioooo-notebook.gitbook.io/docker/advanced/docker-keycloak-hostname-strict.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.