Spring Webflux集成Keycloak角色认证访问拒绝问题排查

核心排查方向 #

1. 验证Token中的角色内容 #

先用JWT解析工具（比如本地的JWT解析库或jwt.io）查看生成的Token payload，确认三点：

• 角色是否存在于realm_access.roles字段（Keycloak默认的 Realm 角色存储位置）
• 角色名称和SecurityConfig中配置的完全一致（注意大小写，比如admin vs ADMIN）
• 如果是客户端级角色，是否在resource_access.{你的客户端ID}.roles字段中

2. 修正SecurityConfig的角色映射与权限配置 #

Spring Webflux的Security配置需要正确从Keycloak Token中提取角色，同时配置正确的权限规则。以下是修正后的示例代码：

@Configuration
@EnableWebFluxSecurity
public class SecurityConfig {

    @Bean
    public SecurityWebFilterChain securityWebFilterChain(ServerHttpSecurity http) {
        http
            .authorizeExchange(exchanges -> exchanges
                .pathMatchers("/samp/a").hasAuthority("admin")
                .pathMatchers("/samp/b").hasAuthority("user")
                .anyExchange().authenticated()
            )
            .oauth2ResourceServer(oauth2 -> oauth2
                .jwt(jwt -> jwt
                    .jwtAuthenticationConverter(jwtAuthenticationConverter())
                )
            );
        return http.build();
    }

    private Converter<Jwt, Mono<AbstractAuthenticationToken>> jwtAuthenticationConverter() {
        JwtGrantedAuthoritiesConverter grantedAuthoritiesConverter = new JwtGrantedAuthoritiesConverter();
        // 指定从realm_access.roles字段提取角色
        grantedAuthoritiesConverter.setAuthoritiesClaimName("realm_access.roles");
        // 去掉默认的ROLE_前缀（如果Keycloak角色没有该前缀）
        grantedAuthoritiesConverter.setAuthorityPrefix("");

        JwtAuthenticationConverter jwtAuthenticationConverter = new JwtAuthenticationConverter();
        jwtAuthenticationConverter.setJwtGrantedAuthoritiesConverter(grantedAuthoritiesConverter);
        return new ReactiveJwtAuthenticationConverterAdapter(jwtAuthenticationConverter);
    }
}

关键注意点：

• hasRole()方法默认会自动添加ROLE_前缀，如果你的Keycloak角色没有这个前缀，建议直接用hasAuthority()替代，或者通过setAuthorityPrefix("")去掉前缀
• 如果使用的是客户端角色，需要把authoritiesClaimName改成resource_access.{你的客户端ID}.roles

3. 检查Keycloak客户端与用户角色配置 #

登录Keycloak控制台，做两项检查：

• 进入对应客户端：确保Full Scope Allowed设为On，或者在Scope标签下添加了realm roles中的admin和user角色
• 进入用户详情页的Role Mappings标签：确认已将admin/user角色分配给对应用户（注意区分Realm Roles和Client Roles）

4. 调试日志分析 #

查看应用调试日志，重点关注：

• JWT解析过程中提取到的authorities列表，确认是否包含目标角色
• 接口访问时的权限校验日志，比如：

  Access Denied: Failed to authorize filter invocation [GET /samp/a] with attributes [hasAuthority('admin')]
  对比日志中的权限列表和要求的角色是否匹配

快速验证步骤 #

1. 用admin用户生成Token，解析后确认realm_access.roles包含admin
2. 临时将SecurityConfig中的权限规则改为permitAll()，测试接口是否能正常访问，排除认证环节问题
3. 切换用hasAuthority()替代hasRole()测试权限校验是否生效

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