#安全加固

本指南涵盖用于加固生产环境 Keycloak 部署的关键安全配置。这些设置可防范常见攻击向量，包括暴力破解、令牌窃取以及重定向配置错误。

#暴力破解检测

Keycloak 可以自动检测并阻止暴力破解登录攻击。

#启用暴力破解检测

1. 在管理控制台中，转到 Realm Settings > Security defenses > Brute force detection 选项卡。
2. 启用 Permanent lockout 或 Temporary lockout。
3. 配置以下参数：

3. 单击 Save。

#管理端点保护

应将 Keycloak 管理控制台和 Admin REST API 限制在授权网络内。

#通过 NetworkPolicy 限制管理访问

创建一个 Kubernetes NetworkPolicy，以限制对管理端点的访问：

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: keycloak-admin-restrict
  namespace: <namespace>
spec:
  podSelector:
    matchLabels:
      app: keycloak
  ingress:
    - from:
        - namespaceSelector:
            matchLabels:
              purpose: admin
        - ipBlock:
            cidr: 10.0.0.0/8
      ports:
        - port: 8443
          protocol: TCP

#分离管理和公共主机名

Keycloak 支持为管理控制台和面向公网的端点配置不同的主机名：

spec:
  hostname:
    hostname: login.example.com
    admin: admin-keycloak.internal.example.com

这使得管理界面可以通过仅限内部访问的主机名提供服务。

#重定向 URI 验证

配置错误的重定向 URI 可能导致开放重定向漏洞和授权码拦截。

#最佳实践

• 在生产环境的重定向 URI 中绝不要使用通配符（*）。请使用精确路径。
• 仅注册应用实际使用的特定回调 URL。
• 在非开发环境中避免注册 localhost URI。

#点击劫持防护

Keycloak 会设置 X-Frame-Options 和 Content-Security-Policy 标头，以防止点击劫持攻击。

#配置标头

1. 转到 Realm Settings > Security defenses > Headers 选项卡。
2. 配置以下内容：

3. 单击 Save。

#令牌安全

#限制令牌范围

使用 Client Scopes 限制包含在令牌中的声明，只保留每个应用所需的内容。避免默认授予所有范围。

#受众限制

在访问令牌中配置 Audience 声明，以限制哪些资源服务器接受该令牌：

1. 在客户端的 Client scopes > 专用范围中，添加一个 Audience 映射器。
2. 将 Included Client Audience 设置为特定的资源服务器客户端。
3. 资源服务器应验证 aud 声明是否与其自身的客户端 ID 匹配。

#令牌生命周期

尽量缩短令牌生命周期，以减少被盗令牌暴露的窗口：

#启用 Refresh Token rotation

启用后，每个 Refresh Token 只能使用一次。每次令牌刷新请求都会签发一个新的 Refresh Token。

1. 转到 Realm Settings > Tokens 选项卡。
2. 启用 Revoke Refresh Token。
3. 将 Refresh Token Max Reuse 设置为 0（一次性使用）。

#强制使用 SSL/HTTPS

1. 转到 Realm Settings > General 选项卡。
2. 将 Require SSL 设置为：
   • external requests — 要求所有外部连接使用 HTTPS（推荐）。
   • all requests — 要求所有连接（包括内部连接）都使用 HTTPS。
   • none — 不要求 SSL（仅限开发环境）。

有关 TLS 配置，请参阅 Configure Ingress and TLS。

#CSRF 防护

Keycloak 为管理控制台和账户控制台内置了 CSRF 防护，无需额外配置。

对于自定义主题或表单，请确保所有表单提交都包含由 Keycloak 模板引擎提供的 ${_csrf.token} 隐藏字段。

#只读用户属性

某些用户属性应禁止最终用户修改：

1. 转到 Realm Settings > User profile 选项卡。
2. 对于敏感属性，将 Who can edit 设置为仅 Admin。
3. 常见的受保护属性包括：email_verified、phone_number_verified、自定义管理标志。

#用于密钥的 Vault 集成

Keycloak 支持从外部 vault 源加载敏感值（例如 LDAP 绑定凭据、SMTP 密码和 IDP 客户端密钥），而不是将它们存储在数据库中。

#Kubernetes Secrets Vault

在 Kubernetes Operator 部署模型中，Keycloak 可以通过 KeycloakRealmImport CR 的 spec.placeholders 字段从 Kubernetes Secrets 中解析密钥。有关用法，请参阅 Manage Realms。

对于通过管理控制台配置的 realm 级密钥，请在密钥字段中使用 vault 语法 ${vault.<key>}。Kubernetes Secrets vault provider 会从挂载到 Pod 中的文件解析键。

#安全检查清单