Keycloak部署在Kong反向代理后出现重定向URL端口异常问题

问题背景 #

• 部署架构：Keycloak 作为用户管理服务，部署在 Kong 反向代理后端，Kong 负责 TLS 终止，与后端微服务统一走 HTTP 通信
• 本地测试环境地址：
  • Kong 监听地址：https://localhost
  • Keycloak 直接监听地址：http://localhost:8082/auth
• 初始容器环境变量配置如下：

ENV KC_HOSTNAME=localhost
ENV KC_HOSTNAME_PORT=8082
ENV KC_HOSTNAME_STRICT_HTTPS=false
ENV KC_PROXY=edge
ENV PROXY_ADDRESS_FORWARDING=true
ENV KC_HTTP_ENABLED=true
ENV KC_HTTP_PORT=8082
KC_HTTP_RELATIVE_PATH=/auth

• 已完成配置：
  • Kong 已正确暴露 Keycloak 公开端点：/realms、/js、/resources、/robots.txt
  • 未通过 Kong 暴露 /admin 端点，计划直接在部署机本地通过 localhost:8082 访问管理控制台
• 异常现象：
  1. 初始状态下访问 https://localhost/auth/realms/master/.well-known/openid-configuration 可正常返回配置，但所有端点地址均带 localhost:8082，符合初始配置预期
  2. 新建 realm 并将其 Frontend URL 设置为 https://myapp.com 后，OpenID 配置中所有端点自动拼接 8082 端口，变为 https://myapp.com:8082/... 格式，导致认证流程无法正常运行
• 约束条件：
  • 不能删除现有配置中的 8082 端口参数，否则本地管理控制台无法访问
  • 尝试使用 KC_HOSTNAME_ADMIN 调整管理端地址时，未找到对应的 KC_HOSTNAME_ADMIN_PORT 配置项

问题根因 #

Keycloak Quarkus 发行版的主机名配置逻辑中，KC_HOSTNAME_PORT 为全局默认端口参数，会同时作用于前端公开端点、管理端点的URL拼接流程。在realm级别单独设置Frontend URL时，Keycloak会默认继承全局KC_HOSTNAME_PORT的值拼接到自定义域名后，最终出现自定义域名后携带8082端口的异常。
不存在独立KC_HOSTNAME_ADMIN_PORT配置项的认知是错误的，该参数在Keycloak 19及以上版本正式提供，专门用于分离管理端与前端端口配置。

可行配置方案 #

方案1：分离前后端/管理端主机名配置（推荐，完全匹配部署需求） #

调整环境变量配置，将公开前端端点的主机名、端口与本地管理端点的配置完全拆分，不需要删除本地访问的端口配置：

# 公开前端端点基础配置（对应Kong代理的对外地址）
ENV KC_HOSTNAME=myapp.com
ENV KC_HOSTNAME_STRICT_HTTPS=true
ENV KC_HOSTNAME_PORT=443
# 本地管理端独立配置
ENV KC_HOSTNAME_ADMIN=localhost
ENV KC_HOSTNAME_ADMIN_PORT=8082
# 保留原有代理和HTTP配置
ENV KC_PROXY=edge
ENV PROXY_ADDRESS_FORWARDING=true
ENV KC_HTTP_ENABLED=true
ENV KC_HTTP_PORT=8082
ENV KC_HTTP_RELATIVE_PATH=/auth

配置说明：

• KC_HOSTNAME 相关参数只作用于对外公开的前端端点（即通过Kong访问的OIDC、用户认证相关接口），端口设置为443后，所有对外返回的URL不会再携带多余端口，设置realm级Frontend URL时也不会再拼接8082端口
• KC_HOSTNAME_ADMIN 相关参数专门作用于本地管理控制台接口，指定端口为8082后，本地直接访问 http://localhost:8082/auth/admin 完全不受影响
• 如果使用的是Keycloak 18及更早的旧版本，需要先升级到19以上稳定版才能使用KC_HOSTNAME_ADMIN_PORT参数

方案2：不修改全局主机名，通过realm配置覆盖端口 #

如果不想调整全局的KC_HOSTNAME配置，可以在设置realm的Frontend URL时，直接显式带上443端口：https://myapp.com:443，Keycloak识别到显式指定的端口，就不会再拼接全局的8082端口。
该方案的缺点是每个新建realm都需要手动配置，且master realm的公开端点还是会返回带8082端口的地址，不推荐生产环境使用。

配置验证方式 #

配置完成后分别验证两个访问路径：

1. 访问公开端点 https://myapp.com/auth/realms/<对应realm名>/.well-known/openid-configuration，检查返回的所有端点地址是否为https://myapp.com/auth/...格式，无多余端口
2. 本地访问 http://localhost:8082/auth/admin，确认可以正常进入管理控制台登录页面

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