如何基于OpenID在SpringBoot+Keycloak资源服务器中管理业务角色

一、核心思路 #

Keycloak 负责身份认证与全局通用角色（如 ADMIN、USER），资源服务器数据库存储业务专属角色（如 ORDER_MANAGER、PRODUCT_EDITOR）。通过扩展 Spring Security 的 Authentication 逻辑，将两类角色合并到权限集合中，直接复用 hasRole()、hasAuthority() 等原生方法做权限校验，无需重复造轮子。

二、角色融合的代码实现 #

1. 本地业务角色存储与加载 #

先在资源服务器数据库中创建 user_roles 表，用 Keycloak 返回的用户唯一标识 sub 作为关联键。然后实现 UserDetailsService 加载本地角色：

@Service
public class LocalUserDetailsService implements UserDetailsService {

    @Autowired
    private UserRoleRepository userRoleRepository;

    @Override
    public UserDetails loadUserByUsername(String userId) throws UsernameNotFoundException {
        // userId 对应 Keycloak 的 sub 字段
        List<String> localRoles = userRoleRepository.findByUserId(userId)
                .stream()
                .map(role -> "ROLE_" + role.getRoleName()) // 适配 Spring Security 权限前缀
                .collect(Collectors.toList());

        return User.builder()
                .username(userId)
                .password("") // 密码无需存储，身份认证由 Keycloak 完成
                .authorities(localRoles)
                .accountNonExpired(true)
                .accountNonLocked(true)
                .credentialsNonExpired(true)
                .enabled(true)
                .build();
    }
}

2. 合并 Keycloak 与本地角色 #

自定义 AuthenticationProvider，在 Keycloak 认证完成后，将本地角色合并到权限集合：

@Component
public class MergedRoleAuthProvider extends KeycloakAuthenticationProvider {

    @Autowired
    private LocalUserDetailsService localUserDetailsService;

    @Override
    public Authentication authenticate(Authentication authentication) throws AuthenticationException {
        // 先执行 Keycloak 原生认证逻辑
        KeycloakAuthenticationToken token = (KeycloakAuthenticationToken) super.authenticate(authentication);
        String userId = token.getPrincipal().getName();

        // 加载本地角色
        UserDetails localUser = localUserDetailsService.loadUserByUsername(userId);

        // 合并两类角色的权限
        Set<GrantedAuthority> mergedAuthorities = new HashSet<>(token.getAuthorities());
        mergedAuthorities.addAll(localUser.getAuthorities());

        // 返回合并后的认证对象
        return new KeycloakAuthenticationToken(
                token.getPrincipal(),
                token.isInteractive(),
                mergedAuthorities,
                token.getAccount()
        );
    }

    @Override
    public boolean supports(Class<?> authentication) {
        return KeycloakAuthenticationToken.class.isAssignableFrom(authentication);
    }
}

3. Spring Security 配置 #

在资源服务器的安全配置类中替换默认的 Keycloak 认证提供者，并配置权限规则：

@Configuration
@EnableWebSecurity
@EnableGlobalMethodSecurity(prePostEnabled = true)
public class ResourceServerSecurityConfig extends KeycloakWebSecurityConfigurerAdapter {

    @Autowired
    private MergedRoleAuthProvider mergedRoleAuthProvider;

    @Autowired
    public void configureGlobal(AuthenticationManagerBuilder auth) {
        auth.authenticationProvider(mergedRoleAuthProvider);
    }

    @Bean
    @Override
    protected SessionAuthenticationStrategy sessionAuthenticationStrategy() {
        return new RegisterSessionAuthenticationStrategy(new SessionRegistryImpl());
    }

    @Bean
    public KeycloakConfigResolver keycloakConfigResolver() {
        return new KeycloakSpringBootConfigResolver();
    }

    @Override
    protected void configure(HttpSecurity http) throws Exception {
        super.configure(http);
        http.authorizeRequests()
                .antMatchers("/orders/**").hasAnyRole("ADMIN", "ORDER_MANAGER")
                .antMatchers("/products/edit/**").hasRole("PRODUCT_EDITOR")
                .anyRequest().authenticated();
    }
}

三、安全更新 Keycloak 角色的方案 #

不直接存储 Keycloak Admin API 凭证，推荐两种安全方式：

1. 客户端凭证流调用 Admin API #

• 在 Keycloak 中创建专用客户端，开启客户端凭证流，并赋予 manage-users、manage-realm 等管理权限。
• 资源服务器通过 Spring Security OAuth2 客户端获取 Admin API 令牌，再调用接口更新角色：

@Service
public class KeycloakRoleService {

    @Autowired
    private OAuth2AuthorizedClientService authorizedClientService;

    @Value("${keycloak.server-url}")
    private String serverUrl;
    @Value("${keycloak.realm}")
    private String realm;
    @Value("${keycloak.admin-client-id}")
    private String adminClientId;

    public void assignRealmRoleToUser(String userId, String roleName) {
        // 获取客户端凭证流的授权令牌
        OAuth2AuthorizedClient client = authorizedClientService.loadAuthorizedClient(adminClientId, "client-credentials");
        String accessToken = client.getAccessToken().getTokenValue();

        // 构造请求头与角色参数
        HttpHeaders headers = new HttpHeaders();
        headers.setBearerAuth(accessToken);
        headers.setContentType(MediaType.APPLICATION_JSON);

        Map<String, String> roleRef = new HashMap<>();
        roleRef.put("id", getRoleId(roleName)); // 先通过API查询角色ID
        roleRef.put("name", roleName);

        // 调用Admin API添加角色
        String url = String.format("%s/admin/realms/%s/users/%s/role-mappings/realm", serverUrl, realm, userId);
        new RestTemplate().postForObject(url, new Object[]{roleRef}, Void.class, headers);
    }

    private String getRoleId(String roleName) {
        OAuth2AuthorizedClient client = authorizedClientService.loadAuthorizedClient(adminClientId, "client-credentials");
        String accessToken = client.getAccessToken().getTokenValue();

        HttpHeaders headers = new HttpHeaders();
        headers.setBearerAuth(accessToken);
        String url = String.format("%s/admin/realms/%s/roles/%s", serverUrl, realm, roleName);
        ResponseEntity<Map> response = new RestTemplate().getForEntity(url, Map.class, headers);
        return (String) response.getBody().get("id");
    }
}

2. Keycloak 事件监听触发角色更新 #

在 Keycloak 中配置自定义事件监听器，资源服务器完成业务操作后发送事件（如用户完成订单权限申请），由 Keycloak 侧的处理器自动更新角色。这种方式资源服务器无需直接调用 Admin API，耦合度更低。

四、自动创建业务角色逻辑 #

监听用户首次登录事件，根据业务规则自动分配本地角色：

@Component
public class FirstLoginRoleAssigner implements ApplicationListener<AuthenticationSuccessEvent> {

    @Autowired
    private UserRoleRepository userRoleRepository;

    @Override
    public void onApplicationEvent(AuthenticationSuccessEvent event) {
        KeycloakAuthenticationToken token = (KeycloakAuthenticationToken) event.getAuthentication();
        String userId = token.getPrincipal().getName();

        // 首次登录且无本地角色时自动分配
        if (!userRoleRepository.existsByUserId(userId)) {
            String userEmail = token.getAccount().getKeycloakSecurityContext().getToken().getEmail();
            List<UserRole> roles = new ArrayList<>();
            
            // 示例：根据邮箱域名分配角色
            if (userEmail.endsWith("@company.com")) {
                roles.add(new UserRole(userId, "ORDER_MANAGER"));
            } else {
                roles.add(new UserRole(userId, "PRODUCT_VIEWER"));
            }
            userRoleRepository.saveAll(roles);
        }
    }
}

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