Keycloak反向代理子路径下路径重复问题排查求助

问题背景 #

因核心功能故障将Keycloak从11版本升级至26版本后，反向代理配置始终无法正常工作。全栈使用X-Forwarded系列请求头，已为Keycloak配置相关头信息，但所有请求最终指向https://https//subdomain.domain.com/org-auth/auth/org-auth/auth/realms/DOMAIN.COM/protocol/openid-connect/auth，出现协议（https//）和路径（/org-auth/auth重复）的异常。

HAProxy配置 #

backend haproxy
mode http
option forwardfor
    http-request set-header X-Real-IP %[src]
    http-request set-header X-Forwarded-Host %[req.hdr(Host)]
    http-request set-header Host %[req.hdr(Host)]
    http-request set-header X-Forwarded-Proto https
    server fastsso1 192.168.62.6:9012 check

Keycloak配置 #

• 自定义镜像：启用Postgres、修改HTTP相对路径为/org-auth/auth、启用hostname:v2特性
• Portainer环境变量：
  • KC_PROXY_HEADERS: xforwarded
  • KC_HTTP_ENABLED: true
  • KC_HOSTNAME: https://subdomain.domain.com（尝试过去掉https、添加子路径的配置）
  • KC_HOSTNAME_STRICT: true
  • KC_HTTP_RELATIVE_PATH: /org-auth/auth
  • KC_FEATURES: hostname:v2

问题原因分析 #

1. KC_HOSTNAME格式错误：KC_HOSTNAME仅需填写纯主机名（如subdomain.domain.com），无需附加https://前缀。当配置带协议的主机名时，Keycloak会叠加HAProxy传递的X-Forwarded-Proto值，导致协议重复拼接为https://https//。

2. 相对路径与代理转发逻辑叠加：HAProxy的请求转发路径和Keycloak自身配置的KC_HTTP_RELATIVE_PATH重复作用，导致路径被两次拼接，出现/org-auth/auth/org-auth/auth的异常。

3. KC_HOSTNAME_STRICT的放大效应：开启KC_HOSTNAME_STRICT=true后，Keycloak强制使用配置的主机名生成URL，若主机名格式错误（带协议），会直接导致URL拼接逻辑异常。

解决方案 #

1. 修正KC_HOSTNAME配置 #

将KC_HOSTNAME改为纯主机名，去掉协议前缀：

KC_HOSTNAME: subdomain.domain.com

Keycloak会自动通过HAProxy传递的X-Forwarded-Proto获取正确的https协议，无需手动指定。

2. 调整相对路径与代理转发规则 #

如果HAProxy是将https://subdomain.domain.com/org-auth/auth/*转发到Keycloak的/*路径，需删除Keycloak的KC_HTTP_RELATIVE_PATH环境变量，避免路径重复。

同时调整HAProxy配置，添加路径重写规则，将请求前缀去掉后转发：

backend haproxy
mode http
option forwardfor
http-request set-header X-Real-IP %[src]
http-request set-header X-Forwarded-Host %[req.hdr(Host)]
http-request set-header X-Forwarded-Proto https
# 重写路径，去掉/org-auth/auth前缀
http-request replace-path ^/org-auth/auth/(.*) /\1
server fastsso1 192.168.62.6:9012 check

3. 保留正确的代理信任配置 #

确保KC_PROXY_HEADERS=xforwarded配置不变，该选项让Keycloak信任HAProxy传递的X-Forwarded系列头信息，用于生成正确的外部访问URL。

4. 验证hostname:v2特性 #

确认KC_FEATURES=hostname:v2正确启用，该特性优化了反向代理场景下的URL生成逻辑，但需配合正确的主机名和代理头配置才能生效。

验证步骤 #

1. 重启Keycloak和HAProxy服务
2. 访问Keycloak登录页面，检查地址栏URL是否正常
3. 触发授权请求，确认跳转URL的协议和路径无重复

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