Keycloak从10.0.2升级到24.0.3后无法访问Master Realm管理控制台

核心原因 #

Keycloak从10.x升级到24.x后，Master领域（内置管理领域）的前端URL配置逻辑发生了变化：业务领域可通过领域设置直接配置前端URL，但Master领域的管理控制台路由依赖启动参数/环境变量配合反向代理头部，仅靠领域设置无法完全生效。

具体解决方案 #

1. 添加Master领域管理URL的环境变量/启动参数 #

在Rancher的Pod环境变量中添加：
KC_ADMIN_URL=https://passporttest.example.com/auth/admin

或者修改你的Dockerfile，在启动命令中加入--admin-url参数：

FROM quay.io/keycloak/keycloak:24.0.3
ENTRYPOINT ["/opt/keycloak/bin/kc.sh", "start-dev", "--admin-url", "https://passporttest.example.com/auth/admin"]

这个参数会直接指定Master控制台的基础URL，弥补领域设置的不足。

2. 修正Nginx反向代理配置 #

确保Nginx正确转发请求并设置必要的反向代理头部，Keycloak需要这些头部生成正确的控制台URL：

location /auth {
    proxy_pass http://your-keycloak-pod-ip:8080;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-Host $host;
    proxy_set_header X-Forwarded-Port $server_port;
    proxy_set_header X-Forwarded-For $remote_addr;
}

重点是X-Forwarded-Proto（确保识别HTTPS）和Host头部，这两个是Keycloak生成正确URL的关键。

3. 清理缓存并重启服务 #

• 清除浏览器中与passporttest.example.com相关的Cookie和缓存，避免旧路由缓存干扰。
• 在Rancher中重启Keycloak Pod，确保新的环境变量/启动参数生效，同时清除容器内的残留配置缓存。

4. 验证Master领域配置（可选） #

通过Keycloak Admin API确认Master领域的前端URL是否正确配置：

1. 先获取管理员令牌：

curl -X POST "http://passporttest.example.com/auth/realms/master/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=admin&password=YOUR_ADMIN_PWD&grant_type=password&client_id=admin-cli"

2. 用令牌查询Master领域配置：

curl -X GET "http://passporttest.example.com/auth/admin/realms/master" \
  -H "Authorization: Bearer YOUR_ADMIN_TOKEN"

查看返回结果中的frontEndUrl字段是否为https://passporttest.example.com/auth，如果不是，重新进入Master领域设置保存配置。

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