Spring Cloud Gateway集成Auth0：代理微服务时ID Token无Payload问题求助

我们基于Spring Cloud Gateway 3.1.4搭建API网关，通过Auth0实现用户认证后将请求路由到微服务，需要从ID Token的Payload中获取用户邮箱并传递给微服务。

登录流程：访问oauth2/authorization/auth0端点跳转至Auth0登录页，输入凭证后返回应用。

当前遇到的问题：在网关内直接通过@AuthenticationPrincipal OidcUser user可以完整获取用户信息和ID Token，但通过TokenRelay过滤器代理请求到微服务时，Authorization头里的Token仅包含头部与签名部分，缺失Payload，导致无法提取用户邮箱。

我们尝试过Auth0的Rules和Actions但未解决，相关配置如下：

Security配置 #

@Bean
public SecurityWebFilterChain filterChain(ServerHttpSecurity http) throws Exception {
    return http
        .csrf().disable()
        .authorizeExchange()
        .pathMatchers("/test").authenticated()
        .anyExchange().authenticated()
        .and().oauth2Login()
        .and().logout().logoutSuccessHandler(logoutSuccessHandler())
        .and().build();
}

网关路由配置 #

RouteLocator中已配置TokenRelay过滤器。

Auth0 PostLogin Action #

exports.onExecutePostLogin = async (event, api) => {
  const namespace = 'http://test.{our_local_development_route}:8888';
  if (event.authorization) {
    api.idToken.setCustomClaim(`${namespace}/claims/email`, event.user.email);
    api.accessToken.setCustomClaim(`${namespace}/email`, event.user.email);
  }
};

Auth0 Rule #

function addEmailToAccessToken(user, context, callback) {
// This rule adds the authenticated user's email address to the access token.

  const namespace = 'http://test.{our_local_development_route}:8888';
  context.idToken[namespace + 'email'] = user.upn;
  context.accessToken[namespace + 'email'] = user.email;
  return callback(null, user, context);
}

核心原因 #

Spring Cloud Gateway的TokenRelay过滤器默认转发的是OAuth2 Access Token，而非ID Token。如果你的Auth0 Access Token是opaque类型（非JWT格式），就会出现“只有头部/签名、无Payload”的表现——本质上它不是JWT，只是一串引用令牌，无法解析出Payload信息。

具体解决步骤 #

1. 确保Auth0 Access Token为JWT格式 #

登录Auth0控制台，进入你的API应用配置：

• 切换到Settings标签页
• 找到Token Format选项，选择JSON Web Token (JWT)
• 确保Allow Offline Access已勾选（按需）
• 保存配置后重新发起认证，此时Access Token会是包含Payload的JWT。

2. 调整Auth0 Action，规范写入邮箱字段 #

自定义Claim的命名空间需使用合法域名（Auth0禁止使用未注册或官方域名），修改PostLogin Action如下：

exports.onExecutePostLogin = async (event, api) => {
  const namespace = 'https://your-custom-domain.com/claims'; // 替换为你的合法域名
  if (event.authorization) {
    api.accessToken.setCustomClaim(`${namespace}/email`, event.user.email);
  }
};

修改后，Access Token的Payload中会包含邮箱字段，微服务解析JWT后即可直接获取。

3. 完善Spring Cloud Gateway Security配置 #

在原有配置中添加资源服务器配置，确保网关能正确识别并转发Access Token：

@Bean
public SecurityWebFilterChain filterChain(ServerHttpSecurity http) throws Exception {
    return http
        .csrf().disable()
        .authorizeExchange()
        .pathMatchers("/test").authenticated()
        .anyExchange().authenticated()
        .and().oauth2Login()
        .and().oauth2ResourceServer().jwt() // 添加资源服务器JWT配置
        .and().logout().logoutSuccessHandler(logoutSuccessHandler())
        .and().build();
}

同时确认RouteLocator中的TokenRelay过滤器配置正确：

@Bean
public RouteLocator customRouteLocator(RouteLocatorBuilder builder) {
    return builder.routes()
        .route("service-route", r -> r.path("/service/**")
            .filters(f -> f.tokenRelay())
            .uri("http://your-microservice-url"))
        .build();
}

4. 备选方案：转发ID Token到微服务（不推荐） #

若特殊场景下必须转发ID Token，可自定义网关过滤器，从SecurityContext中提取ID Token并放入请求头：

@Component
public class IdTokenRelayGatewayFilterFactory extends AbstractGatewayFilterFactory<IdTokenRelayGatewayFilterFactory.Config> {

    public IdTokenRelayGatewayFilterFactory() {
        super(Config.class);
    }

    @Override
    public GatewayFilter apply(Config config) {
        return (exchange, chain) -> {
            return exchange.getPrincipal()
                .filter(principal -> principal instanceof OidcUser)
                .map(principal -> (OidcUser) principal)
                .map(oidcUser -> {
                    String idToken = oidcUser.getIdToken().getTokenValue();
                    exchange.getRequest().mutate()
                        .header("Authorization", "Bearer " + idToken)
                        .build();
                    return exchange;
                })
                .defaultIfEmpty(exchange)
                .flatMap(chain::filter);
        };
    }

    public static class Config {
        // 可添加自定义配置参数
    }
}

在RouteLocator中替换默认TokenRelay为该自定义过滤器：

.route("service-route", r -> r.path("/service/**")
    .filters(f -> f.filter(new IdTokenRelayGatewayFilterFactory().apply(new IdTokenRelayGatewayFilterFactory.Config())))
    .uri("http://your-microservice-url"))

注意：ID Token设计用于客户端认证，而非服务间授权，优先使用Access Token作为服务间调用凭证。

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