Keycloak 与 Spring Boot 3 集成时，hasAnyRole("admin") 失效的根本原因在于：OAuth2 登录默认不解析 ID Token 中的角色声明，需手动配置 GrantedAuthoritiesMapper 或自定义 OAuth2UserService 将 Keycloak realm/client roles 映射为 Spring Security 的 ROLE_* 权限。
keycloak 与 spring boot 3 集成时，`hasanyrole("admin")` 失效的根本原因在于：oauth2 登录默认不解析 id token 中的角色声明，需手动配置 `grantedauthoritiesmapper` 或自定义 `oauth2userservice` 将 keycloak realm/client roles 映射为 spring security 的 `role_*` 权限。
在 Spring Boot 3（搭配 Spring Security 6）中，Keycloak 不再通过官方适配器集成，而是作为标准 OIDC 提供商使用 oauth2Login()。此时，*角色授权失败的典型表现是：用户已正确分配 realm role（如 admin），JWT 中也包含 "realm_access": {"roles": ["admin"]}，但 Spring Security 的 Authentication.getAuthorities() 仅返回 `SCOPE_和OIDC_USER，完全缺失角色权限**——这正是你日志中Granted Authorities: [OIDC_USER, SCOPE_email, ...]` 所揭示的核心问题。
✅ 正确配置步骤（三步到位）
1. Keycloak 后台：启用角色映射到 ID Token
⚠️ 关键前提：确保角色信息实际存在于登录流程中使用的 ID Token（
oauth2Login默认解析 ID Token，而非 Access Token）。
进入 Keycloak 控制台 → 进入对应 Realm → Client Scopes → roles → Mappers → realm roles（或 client roles）→ 编辑：
- ✅ 勾选 Add to ID token
- ✅ 勾选 Add to userinfo
- Token Claim Name:
realm_access（默认） - Claim JSON Type:
JSON - *（可选）若使用 client roles，同理配置 client roles mapper 并启用 Add to ID token**
? 验证方式：登录后解码浏览器中的
ID Token（非 Access Token），确认其realm_access.roles字段存在且含"admin"。
2. Spring Boot：注入自定义 GrantedAuthoritiesMapper
在 SecurityConfig 中添加 Bean，将 Keycloak 的角色声明转换为 Spring Security 可识别的 ROLE_* 权限：
@Bean
public GrantedAuthoritiesMapper userAuthoritiesMapper() {
return authorities -> {
Set<grantedauthority> mappedAuthorities = new HashSet();
authorities.forEach(authority -> {
if (OidcUserAuthority.class.isInstance(authority)) {
OidcUserAuthority oidcUserAuthority = (OidcUserAuthority) authority;
// 从 ID Token 的 realm_access.roles 提取角色
Object realmAccess = oidcUserAuthority.getUserInfo().get("realm_access");
if (realmAccess instanceof Map && ((Map, ?>) realmAccess).containsKey("roles")) {
List<string> roles = (List<string>) ((Map, ?>) realmAccess).get("roles");
roles.forEach(role ->
mappedAuthorities.add(new SimpleGrantedAuthority("ROLE_" + role.toUpperCase()))
);
}
// 同理可处理 client_access.roles（若启用 client roles）
Object clientAccess = oidcUserAuthority.getUserInfo().get("resource_access");
if (clientAccess instanceof Map) {
((Map, ?>) clientAccess).forEach((client, rolesObj) -> {
if (rolesObj instanceof Map && ((Map, ?>) rolesObj).containsKey("roles")) {
List<string> clientRoles = (List<string>) ((Map, ?>) rolesObj).get("roles");
clientRoles.forEach(role ->
mappedAuthorities.add(new SimpleGrantedAuthority("ROLE_" + role.toUpperCase()))
);
}
});
}
}
});
return mappedAuthorities;
};
}</string></string></string></string></grantedauthority>
3. 更新安全配置：绑定 mapper 并修正角色匹配逻辑
修改 clientFilterChain，显式注册 OAuth2UserService 并注入上述 mapper：
@Bean
public SecurityFilterChain clientFilterChain(HttpSecurity http) throws Exception {
// 构建自定义 OAuth2UserService
OAuth2UserService<oidcuserrequest oidcuser> oidcUserService = new OidcUserService();
oidcUserService.setAuthoritiesMapper(userAuthoritiesMapper());
return http
.authorizeHttpRequests(auth -> auth
.requestMatchers("/debug/public").permitAll()
.requestMatchers("/debug/authenticated").authenticated()
.requestMatchers("/debug/admin").hasRole("ADMIN") // 注意：hasRole("ADMIN") 对应 ROLE_ADMIN
.anyRequest().authenticated()
)
.oauth2Login(oauth2 -> oauth2
.userInfoEndpoint(userInfo -> userInfo
.oidcUserService(oidcUserService) // 注入自定义服务
)
)
.logout(conf -> conf
.addLogoutHandler(keycloakLogoutHandler)
.logoutSuccessUrl("/index")
)
.build();
}</oidcuserrequest>
? 注意事项：
hasRole("ADMIN")自动匹配ROLE_ADMIN，无需写hasAnyRole("admin")（后者会尝试匹配ROLE_admin，大小写敏感且不符合 Keycloak 默认映射习惯）；- 若 Keycloak 角色为小写（如
admin），代码中已统一转为大写："ROLE_" + role.toUpperCase()；- 确保
application.yml中spring.security.oauth2.client.provider.keycloak.user-name-attribute: preferred_username正确，避免 Principal 解析异常。
? 总结：为什么原配置失败？
- ❌ 错误假设：
hasAnyRole("admin")能自动读取 Keycloak 角色 → 实际未配置任何角色解析逻辑； - ❌ 忽略协议差异：
oauth2Login()默认只提取 OIDC 标准 scope 权限（SCOPE_*），不解析自定义 token 声明（如realm_access）； - ❌ 混淆 Token 类型：浏览器 Cookie 存储的是短 ID Token（不含角色），而调试时查看的可能是长 Access Token（含角色）→ 必须确保角色注入到 ID Token；
- ✅ 正确路径：*Keycloak 配置（导出角色） + Spring 自定义映射（解析并转换） + 安全规则（匹配 ROLE_）** 三者缺一不可。
完成以上配置后重启应用，以 dev_admin 登录访问 /debug/admin，403 将消失，授权生效。
