Spring Cloud Gateway与Keycloak Docker部署下登录提示无效凭据排查

问题场景 #

搭建了Spring Cloud Gateway服务用于转发前端请求到后端，搭配Keycloak做认证，两者都部署在Docker且共享同一Docker网络。本地运行Gateway时登录流程正常，但部署到Docker后，使用正确凭据登录却出现无效凭据提示（登录页面显示WSL的IP，该IP已作为keycloak-host配置）。

现有配置文件 #

server:
  port: 8080
spring:
  cloud:
    gateway:
      default-filters:
        - DedupeResponseHeader=Access-Control-Allow-Credentials Access-Control-Allow-Origin Access-Control-Request-Headers
        - SaveSession
        - TokenRelay=
      routes:
        - id: resource
          uri: ${postman-mock}
          predicates:
            - Path=/resource

  security:
    oauth2:
      client:
        provider:
          keycloak:
            issuer-uri: ${keycloak-host}/realms/${realm}
            user-name-attribute: preferred_username # 也曾尝试用email
        registration:
          keycloak:
            provider: keycloak
            client-id: ${client-id}
            client-secret: ${client-secret}
            authorization-grant-type: authorization_code
            scope:
              - openid
              - profile
              - email
              - roles
      resourceserver:
        jwt:
          issuer-uri: ${keycloak-host}/realms/${realm}

Keycloak配置中，Valid redirect URIs和Valid post logout redirect URIs均已设置为*。

可能的问题及解决办法 #

1. Keycloak前端URL未配置外部可访问地址 #

当Gateway在Docker内部时，Keycloak默认会用容器内部的hostname生成回调地址，而不是外部的WSL IP，导致认证流程中地址不匹配。

• 解决：进入Keycloak后台，找到对应Realm的Realm Settings -> Frontend URL，设置为外部可访问的完整地址（例如http://192.168.xxx.xxx:8081，替换为你的WSL IP和Keycloak端口）。

2. Gateway回调地址未指定外部可访问路径 #

Gateway在Docker中运行时，会默认向Keycloak传递容器内部地址作为回调URL（比如http://gateway:8080/login/oauth2/code/keycloak），浏览器无法访问该内部地址，导致认证流程中断。

• 解决：在Gateway的application.yml中显式配置回调地址：

spring:
  security:
    oauth2:
      client:
        registration:
          keycloak:
            redirect-uri: "http://${your-wsl-ip}:8080/login/oauth2/code/keycloak"

也可以用通配符适配动态地址：redirect-uri: "{baseUrl}/login/oauth2/code/keycloak"，但需确保baseUrl是外部可访问的IP/域名，而非Docker内部地址。

3. Docker容器间的Session/Cookie传递问题 #

Gateway部署在Docker中时，登录生成的Session Cookie可能被标记为Docker内部域名，导致浏览器无法正确携带Cookie到外部访问地址。

• 解决：在Gateway配置中添加服务器转发头策略：

server:
  forward-headers-strategy: framework
  tomcat:
    remoteip:
      remote-ip-header: X-Forwarded-For
      protocol-header: X-Forwarded-Proto

同时运行Gateway容器时，确保端口映射正确，并允许传递X-Forwarded相关请求头。

4. 容器时间不同步 #

Gateway和Keycloak容器的系统时间不一致，会导致令牌的有效期校验失败，间接表现为无效凭据错误。

• 解决：运行容器时挂载宿主机时间文件同步时间：

docker run -v /etc/localtime:/etc/localtime:ro ...

或者在容器内配置NTP服务同步时间。

5. SSL配置不匹配（若启用HTTPS） #

如果Keycloak启用了HTTPS，但Gateway配置的issuer-uri用的是HTTP协议，或者Gateway未信任Keycloak的SSL证书，会导致令牌验证失败。

• 解决：确认issuer-uri的协议与Keycloak一致；若用HTTPS，将Keycloak的证书添加到Gateway容器的信任存储中。

内容的提问来源于stack exchange，提问作者jorge-plaza