Spring Boot集成Keycloak后角色未映射为权限的问题咨询

核心原因 #

Keycloak返回的Realm角色默认嵌套在realm_access.roles字段中，而Spring Security的OIDC客户端默认不会自动将这些字段转换为GrantedAuthority，因此无法直接使用hasRole()等权限控制方法。

解决方案 #

方法一：配置属性快速映射（Spring Boot 2.6+支持） #

在你的配置文件中添加以下属性，指定角色提取路径：

spring.security.oauth2.client.provider.spring-client.roles-claim=realm_access.roles

该配置会让Spring自动从realm_access.roles中提取角色，并自动添加ROLE_前缀（适配Spring Security的hasRole()方法规则）。

方法二：自定义OidcUserService（适配复杂场景） #

如果需要自定义角色处理逻辑（比如同时处理Realm角色和Client角色、修改权限前缀），可以实现自定义的OidcUserService：

1. 编写自定义服务类：

import org.springframework.security.core.authority.SimpleGrantedAuthority;
import org.springframework.security.oauth2.client.oidc.userinfo.OidcUserRequest;
import org.springframework.security.oauth2.client.oidc.userinfo.OidcUserService;
import org.springframework.security.oauth2.core.OAuth2AuthenticationException;
import org.springframework.security.oauth2.core.oidc.user.DefaultOidcUser;
import org.springframework.security.oauth2.core.oidc.user.OidcUser;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;

public class CustomOidcUserService extends OidcUserService {
    @Override
    public OidcUser loadUser(OidcUserRequest userRequest) throws OAuth2AuthenticationException {
        OidcUser oidcUser = super.loadUser(userRequest);
        // 提取Realm角色
        Map<String, Object> realmAccess = oidcUser.getClaims().get("realm_access", Map.class);
        List<String> realmRoles = (List<String>) realmAccess.get("roles");
        
        // 提取Client角色（可选）
        Map<String, Object> clientAccess = oidcUser.getClaims().get("resource_access", Map.class);
        List<String> clientRoles = (List<String>) ((Map) clientAccess.get("spring-client")).get("roles");

        List<SimpleGrantedAuthority> authorities = new ArrayList<>(oidcUser.getAuthorities());
        // 为角色添加ROLE_前缀
        realmRoles.forEach(role -> authorities.add(new SimpleGrantedAuthority("ROLE_" + role)));
        clientRoles.forEach(role -> authorities.add(new SimpleGrantedAuthority("ROLE_" + role)));
        
        return new DefaultOidcUser(authorities, oidcUser.getIdToken(), oidcUser.getUserInfo());
    }
}

2. 在Security配置中启用自定义服务：

@Bean
public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
    http.csrf().disable()
            .authorizeHttpRequests(auth -> auth
                    .anyRequest().authenticated()
            )
            .oauth2Login(oauth2 -> oauth2
                    .userInfoEndpoint(userInfo -> userInfo
                            .oidcUserService(new CustomOidcUserService())
                    )
            )
            .logout(logout -> logout
                    .logoutSuccessHandler(oidcLogoutSuccessHandler())
            );
    return http.build();
}

验证方式 #

在控制器中注入Authentication对象，打印权限信息确认映射结果：

@GetMapping("/check-roles")
public void checkRoles(Authentication authentication) {
    authentication.getAuthorities().forEach(auth -> System.out.println("权限：" + auth.getAuthority()));
}

访问该接口后，控制台会输出带ROLE_前缀的角色，此时即可在权限控制中使用hasRole("角色名")（注意此处角色名不需要加ROLE_前缀，Spring会自动匹配）。

内容的提问来源于stack exchange，提问作者M. Lee