Spring Cloud Gateway集成Keycloak遇401 Unauthorized问题求助

环境信息 #

• Spring Boot 2.7.11
• Keycloak 18.0.0（负责安全与角色管理）
• Spring Cloud 2021.0.1
• keycloak-adapter-bom 21.1.1
• 架构：EurekaServer → Spring Cloud Gateway → 微服务

问题现象 #

1. 成功从Keycloak获取Token（请求地址：http://localhost/realms/EcommerceRealm/protocol/openid-connect/token）
2. 携带该Token通过Gateway调用微服务接口（地址：http://localhost:8765/api/articles/prot/search/listArticles），始终返回401 Unauthorized

排查方向与解决方案 #

1. Token传递与有效性校验 #

• 确认请求头格式：必须以Authorization: Bearer <token>格式携带Token，注意Bearer后需加空格，避免拼写错误。
• 验证Token有效性：调用Keycloak的自省接口检查Token状态：

  POST http://localhost/realms/EcommerceRealm/protocol/openid-connect/token/introspect
  Headers: Content-Type: application/x-www-form-urlencoded
  Body: token=<你的Token>&client_id=<客户端ID>&client_secret=<客户端密钥>
  

  重点查看返回结果的active字段是否为true，同时确认realm_access.roles包含接口所需权限。
• Gateway Token转发配置：确保Gateway配置了Token转发过滤器，示例yaml配置：

  spring:
    cloud:
      gateway:
        routes:
        - id: article-service
          uri: lb://article-service
          predicates:
          - Path=/api/articles/**
          filters:
          - TokenRelay=
          - RemoveRequestHeader=Cookie
  

2. 版本兼容性修复 #

当前使用的keycloak-adapter-bom 21.1.1与Keycloak服务器18.0.0版本差异过大，适配器版本需与服务器版本保持一致（18.0.0），避免解析逻辑不兼容：

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.keycloak.bom</groupId>
      <artifactId>keycloak-adapter-bom</artifactId>
      <version>18.0.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

3. 微服务端安全配置检查 #

• 确认微服务的Keycloak配置正确指向目标Realm：

  keycloak:
    auth-server-url: http://localhost/auth
    realm: EcommerceRealm
    resource: <客户端ID>
    bearer-only: true
    credentials:
      secret: <客户端密钥>
  

• 检查接口权限注解（如@RolesAllowed、@PreAuthorize）是否配置了正确的角色，且Token中包含对应角色。

4. 链路隔离测试 #

• 直接调用微服务接口（绕过Gateway），携带Token验证是否能正常访问，以此定位问题出在Gateway还是微服务端。
• 通过Eureka控制台确认Gateway已正确发现目标微服务。

5. 错误日志分析 #

重点提取Gateway和微服务的关键日志：

• Token解析失败异常（如InvalidTokenException）
• 权限校验失败提示（如AccessDeniedException）
• 请求头丢失相关日志（确认Token是否被正确转发）

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