FastApi集成Keycloak时Swagger Token URL显示容器名问题求助

核心原因 #

FastAPIKeycloak会自动从Keycloak的/.well-known/openid-configuration端点读取认证相关URL（包括token_endpoint）。你的Keycloak容器内部未正确配置外部访问的域名和协议，导致它生成的well-known文档里的token_endpoint是容器内部的HTTP地址（容器名+端口），而非预期的外部HTTPS域名地址。

解决步骤 #

1. 修正Keycloak容器的外部访问配置 #

根据Keycloak版本调整启动参数：

• 旧版Keycloak（16及以下，WildFly版本）：
  启动容器时添加环境变量：

  -e KEYCLOAK_FRONTEND_URL=https://keycloakdomain.com/auth
  

  该参数会强制Keycloak生成的所有公开端点URL使用指定的外部地址。

• 新版Keycloak（17+，Quarkus版本）：
  启动容器时添加以下环境变量：

  -e KC_HOSTNAME=keycloakdomain.com
  -e KC_HTTPS_ENABLED=true
  -e KC_HOSTNAME_PATH=/auth  # 若Keycloak挂载在/auth路径下需添加
  

  这些参数会配置Keycloak的主机名、启用HTTPS并设置路径，确保生成的well-known文档里的端点都是正确的外部HTTPS地址。

2. 验证Keycloak的well-known配置 #

重启Keycloak容器后，访问：

https://keycloakdomain.com/auth/realms/[你的Realm名称]/.well-known/openid-configuration

检查返回JSON中的token_endpoint字段是否为：

https://keycloakdomain.com/auth/realms/[你的Realm名称]/protocol/openid-connect/token

若是，则配置生效。

3. 确认FastAPIKeycloak的初始化配置 #

确保FastAPIKeycloak初始化代码中server_url正确设置：

from fastapi_keycloak import FastAPIKeycloak

idp = FastAPIKeycloak(
    server_url="https://keycloakdomain.com/auth",
    client_id="你的客户端ID",
    client_secret="你的客户端密钥",
    realm="你的Realm名称",
    callback_uri="https://fastapidomain.com/docs"
)

无需额外设置baseUrl，修正Keycloak配置后，FastAPIKeycloak会自动读取正确的token_endpoint，Swagger的「Authorize」按钮里的TOKEN URL就会显示预期的HTTPS地址。

可选：手动指定token_endpoint（不推荐） #

若暂时无法修改Keycloak配置，可在初始化FastAPIKeycloak时手动指定token_endpoint：

idp = FastAPIKeycloak(
    # 其他参数...
    token_endpoint="https://keycloakdomain.com/auth/realms/[你的Realm名称]/protocol/openid-connect/token"
)

但该方式仅修正token端点，其他认证相关端点（如授权、刷新令牌）可能仍使用内部地址，因此优先推荐修正Keycloak的外部访问配置。

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