Spring Boot整合Keycloak出现insufficient_scope错误的解决咨询

错误信息 #

Bearer error="insufficient_scope", error_description="The request requires higher privileges than provided by the access token.", error_uri="https://tools.ietf.org/html/rfc6750#section-3.1"

相关配置代码 #

public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
    
    System.out.println("Entro a seguridad");
    http.authorizeHttpRequests()
        .requestMatchers("/all/**")
        .hasAnyRole("user_roles")
        .anyRequest()
        .permitAll();
    http.oauth2Login()
        .and()
        .logout()
        .addLogoutHandler((LogoutHandler) keycloakLogoutHandler)
        .logoutSuccessUrl("/");
    http.oauth2ResourceServer(OAuth2ResourceServerConfigurer::jwt);
    return http.build();
}

JWT详情 #

问题原因及修复方案 #

1. 处理Spring Security角色前缀问题

Spring Security的hasAnyRole()方法会自动给角色名添加ROLE_前缀，也就是说你配置的hasAnyRole("user_roles")实际会检查token中是否存在ROLE_user_roles权限，但Keycloak默认返回的角色不带该前缀，这是核心矛盾点。

修复方式二选一：

• 替换hasAnyRole()为hasAnyAuthority()，后者不会自动添加前缀：

  .requestMatchers("/all/**")
  .hasAnyAuthority("user_roles")
  

• 保留hasAnyRole()，通过配置去掉Spring Security的默认前缀：

  @Bean
  public GrantedAuthoritiesMapper grantedAuthoritiesMapper() {
      SimpleAuthorityMapper mapper = new SimpleAuthorityMapper();
      mapper.setPrefix(""); // 移除ROLE_前缀
      return mapper;
  }
  

2. 确认Keycloak角色映射正确

检查JWT内容，确保：

• user_roles角色存在于realm_access.roles或resource_access.{你的客户端ID}.roles字段中
• Keycloak客户端配置中已开启"Full Scope Allowed"，或手动将user_roles添加到客户端作用域
• 目标用户已被分配user_roles角色

3. 自定义JWT权限解析器（若角色在resource_access下）

如果角色存储在resource_access的客户端专属字段中，需要配置解析器提取权限：

@Bean
public JwtAuthenticationConverter jwtAuthenticationConverter() {
    JwtGrantedAuthoritiesConverter grantedAuthoritiesConverter = new JwtGrantedAuthoritiesConverter();
    // 替换为你的Keycloak客户端ID
    grantedAuthoritiesConverter.setAuthoritiesClaimName("resource_access.your-client-id.roles");

    JwtAuthenticationConverter converter = new JwtAuthenticationConverter();
    converter.setJwtGrantedAuthoritiesConverter(grantedAuthoritiesConverter);
    return converter;
}

然后在资源服务器配置中应用该转换器：

http.oauth2ResourceServer(oauth2 -> oauth2
    .jwt(jwt -> jwt.jwtAuthenticationConverter(jwtAuthenticationConverter()))
);

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