Spring Security Hierarchical Roles: Stop Writing Spaghetti Role Checks

If you've ever maintained a Spring Security application with more than a handful of roles, you know the pain: every controller method has a @PreAuthorize("hasRole('ADMIN') or hasRole('MANAGER') or hasRole('SUPERVISOR')") check. And when a new role is added, you have to hunt down every single annotation. It's brittle, error-prone, and screams for refactoring.

Hierarchical roles solve this. Instead of checking multiple roles, you define a hierarchy: ADMIN > MANAGER > SUPERVISOR > USER. Then you just check hasRole('MANAGER') and it automatically includes SUPERVISOR and USER. Spring Security's RoleHierarchy interface makes this possible, but the official docs gloss over the pitfalls.

I've seen teams waste days debugging authorization failures because their hierarchy was configured incorrectly, or worse, accidentally granted everyone admin access. In this guide, I'll show you how to implement hierarchical roles the right way, what the docs don't tell you, and how to debug when things go wrong.

What Are Hierarchical Roles and Why You Need Them

Hierarchical roles let you define a parent-child relationship between roles. For example, an ADMIN role automatically inherits all permissions of a MANAGER role, which in turn inherits from USER. This eliminates the need to write hasRole('ADMIN') or hasRole('MANAGER') or hasRole('USER') — you just check hasRole('MANAGER') and it includes USER automatically.

Without hierarchies, every time you add a new role, you have to update every authorization check. With hierarchies, you just add the role to the hierarchy and you're done. This is especially valuable in applications with complex role structures like SaaS platforms where customers can define custom roles.

Spring Security provides the RoleHierarchy interface with a default implementation RoleHierarchyImpl. You define the hierarchy as a string like:

ROLE_ADMIN > ROLE_MANAGER ROLE_MANAGER > ROLE_USER

Then configure it in your security configuration. That's it. But as you'll see, the devil is in the details.

@Configuration
@EnableGlobalMethodSecurity(prePostEnabled = true)
public class SecurityConfig extends GlobalMethodSecurityConfiguration {

    @Override
    protected MethodSecurityExpressionHandler createExpressionHandler() {
        DefaultMethodSecurityExpressionHandler expressionHandler =
                new DefaultMethodSecurityExpressionHandler();
        expressionHandler.setRoleHierarchy(roleHierarchy());
        return expressionHandler;
    }

    @Bean
    public RoleHierarchy roleHierarchy() {
        RoleHierarchyImpl roleHierarchy = new RoleHierarchyImpl();
        roleHierarchy.setHierarchy(
            "ROLE_ADMIN > ROLE_MANAGER \n ROLE_MANAGER > ROLE_USER"
        );
        return roleHierarchy;
    }
}

Configuring RoleHierarchy with Web Security

To use hierarchical roles with HttpSecurity (for URL-based security), you need to wire the RoleHierarchy into the AccessDecisionManager. Spring Security's default voter-based access control doesn't automatically use the RoleHierarchy; you have to explicitly configure it.

Here's how to do it with Spring Security 6.x:

```java @Bean public SecurityFilterChain filterChain(HttpSecurity http) throws Exception { http .authorizeHttpRequests(authz -> authz .requestMatchers("/admin/").hasRole("ADMIN") .requestMatchers("/manager/").hasRole("MANAGER") .anyRequest().authenticated() ) .oauth2ResourceServer(OAuth2ResourceServerConfigurer::jwt); return http.build(); }

@Bean public AccessDecisionManager accessDecisionManager() { List<AccessDecisionVoter<?>> voters = List.of( new RoleHierarchyVoter(roleHierarchy()) ); return new UnanimousBased(voters); } ```

If you're using method security (e.g., @PreAuthorize), you also need to configure the MethodSecurityExpressionHandler as shown earlier. Without this, your @PreAuthorize annotations will ignore the hierarchy entirely.

I've seen teams spend days wondering why their @PreAuthorize checks weren't working with hierarchies, only to realize they forgot to set the expression handler.

@Configuration
@EnableWebSecurity
public class WebSecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .authorizeHttpRequests(authz -> authz
                .requestMatchers("/admin/**").hasRole("ADMIN")
                .requestMatchers("/manager/**").hasRole("MANAGER")
                .anyRequest().authenticated()
            )
            .oauth2ResourceServer(OAuth2ResourceServerConfigurer::jwt);
        return http.build();
    }

    @Bean
    public RoleHierarchy roleHierarchy() {
        RoleHierarchyImpl roleHierarchy = new RoleHierarchyImpl();
        roleHierarchy.setHierarchy(
            "ROLE_ADMIN > ROLE_MANAGER \n ROLE_MANAGER > ROLE_USER"
        );
        return roleHierarchy;
    }

    @Bean
    public AccessDecisionManager accessDecisionManager() {
        List<AccessDecisionVoter<?>> voters = List.of(
            new RoleHierarchyVoter(roleHierarchy())
        );
        return new UnanimousBased(voters);
    }
}

What the Official Docs Won't Tell You

The official Spring Security documentation covers the basics of RoleHierarchy, but it leaves out several critical details that will bite you in production.

1. Role Prefix Consistency: The hierarchy string uses the full role name with the ROLE_ prefix (e.g., ROLE_ADMIN). But when you use hasRole('ADMIN'), Spring Security automatically prepends ROLE_. This mismatch is a common source of bugs. Always use the ROLE_ prefix in the hierarchy string.
2. Hierarchy String Parsing: The hierarchy string is parsed by a simple line-based parser. Trailing spaces or missing newlines can cause the hierarchy to be ignored silently. I recommend building the hierarchy programmatically using a list of relationships to avoid typos.
3. GlobalMethodSecurityConfiguration Override: If you extend GlobalMethodSecurityConfiguration, you must override createExpressionHandler() and set the RoleHierarchy. Many developers forget this step and wonder why their @PreAuthorize annotations don't respect the hierarchy.
4. RoleHierarchyVoter for Web Security: The default AccessDecisionManager uses RoleVoter, not RoleHierarchyVoter. You must explicitly replace it. The docs mention this but don't emphasize it enough.
5. Testing the Hierarchy: The docs don't show how to test hierarchical roles. You should write unit tests that verify the hierarchy resolves correctly, and integration tests that verify endpoints are properly secured.

public class RoleHierarchyBuilder {
    private final List<String> lines = new ArrayList<>();

    public RoleHierarchyBuilder addRelation(String parent, String child) {
        lines.add(parent + " > " + child);
        return this;
    }

    public String build() {
        return String.join("\n", lines);
    }
}

// Usage
RoleHierarchyImpl hierarchy = new RoleHierarchyImpl();
hierarchy.setHierarchy(new RoleHierarchyBuilder()
    .addRelation("ROLE_ADMIN", "ROLE_MANAGER")
    .addRelation("ROLE_MANAGER", "ROLE_USER")
    .build());

Testing Hierarchical Roles

Testing hierarchical roles is essential to ensure your security configuration works as expected. You should write both unit tests for the RoleHierarchy itself and integration tests for your endpoints.

For unit tests, you can directly test the RoleHierarchyImpl:

``java @Test void testHierarchy() { RoleHierarchyImpl hierarchy = new RoleHierarchyImpl(); hierarchy.setHierarchy("ROLE_ADMIN > ROLE_MANAGER ROLE_MANAGER > ROLE_USER"); Set<String> reachable = hierarchy.getReachableGrantedAuthorities( List.of(new SimpleGrantedAuthority("ROLE_ADMIN"))); assertTrue(reachable.contains(new SimpleGrantedAuthority("ROLE_ADMIN"))); assertTrue(reachable.contains(new SimpleGrantedAuthority("ROLE_MANAGER"))); assertTrue(reachable.contains(new SimpleGrantedAuthority("ROLE_USER"))); } ``

For integration tests, use Spring Security's test support to simulate authenticated requests:

```java @SpringBootTest @AutoConfigureMockMvc class SecurityTest {

@Autowired private MockMvc mockMvc;

@Test @WithMockUser(roles = "MANAGER") void managerCanAccessManagerEndpoint() throws Exception { mockMvc.perform(get("/manager/dashboard")) .andExpect(status().isOk()); }

@Test @WithMockUser(roles = "USER") void userCannotAccessManagerEndpoint() throws Exception { mockMvc.perform(get("/manager/dashboard")) .andExpect(status().isForbidden()); } } ```

These tests catch regressions when you modify the hierarchy. I've seen teams skip this and then accidentally break authorization when adding a new role.

@Test
void testAdminGetsAllRoles() {
    RoleHierarchyImpl hierarchy = new RoleHierarchyImpl();
    hierarchy.setHierarchy("ROLE_ADMIN > ROLE_MANAGER\nROLE_MANAGER > ROLE_USER");
    
    Set<GrantedAuthority> authorities = hierarchy.getReachableGrantedAuthorities(
        List.of(new SimpleGrantedAuthority("ROLE_ADMIN")));
    
    assertEquals(3, authorities.size());
    assertTrue(authorities.contains(new SimpleGrantedAuthority("ROLE_USER")));
}

@Test
void testUserGetsOnlyUser() {
    RoleHierarchyImpl hierarchy = new RoleHierarchyImpl();
    hierarchy.setHierarchy("ROLE_ADMIN > ROLE_MANAGER\nROLE_MANAGER > ROLE_USER");
    
    Set<GrantedAuthority> authorities = hierarchy.getReachableGrantedAuthorities(
        List.of(new SimpleGrantedAuthority("ROLE_USER")));
    
    assertEquals(1, authorities.size());
    assertTrue(authorities.contains(new SimpleGrantedAuthority("ROLE_USER")));
}

Common Pitfalls and How to Avoid Them

Here are the most common mistakes I've seen with hierarchical roles in production:

1. Forgetting the ROLE_ prefix: The hierarchy string must use ROLE_ADMIN, not ADMIN. But hasRole('ADMIN') automatically adds the prefix. This inconsistency confuses many developers.
2. Not configuring the AccessDecisionManager: If you use web security (HttpSecurity), you must configure an AccessDecisionManager that uses RoleHierarchyVoter. Otherwise, the hierarchy is ignored.
3. Not overriding createExpressionHandler() for method security: If you use @PreAuthorize, you must override this method and set the role hierarchy. This is a silent failure — the annotation will work, but without hierarchy.
4. Incorrect hierarchy string format: The string must have each relationship on a new line, with spaces around '>'. Missing a newline or extra spaces can cause the hierarchy to be parsed incorrectly.
5. Not testing the hierarchy: Without tests, a misconfiguration can go unnoticed until a user complains they can't access something they should, or worse, they can access something they shouldn't.

To avoid these pitfalls, use a builder for the hierarchy string, always test both positive and negative cases, and log the hierarchy at startup.

@Bean
public RoleHierarchy roleHierarchy() {
    RoleHierarchyImpl roleHierarchy = new RoleHierarchyImpl();
    String hierarchy = "ROLE_ADMIN > ROLE_MANAGER\nROLE_MANAGER > ROLE_USER";
    roleHierarchy.setHierarchy(hierarchy);
    log.info("Configured RoleHierarchy: {}", hierarchy);
    return roleHierarchy;
}

Advanced: Dynamic Hierarchies with a Database

In some applications, the role hierarchy needs to be dynamic — for example, a multi-tenant SaaS where each customer can define their own role hierarchy. Spring Security's RoleHierarchyImpl is designed for static hierarchies, but you can implement your own RoleHierarchy that reads from a database.

Create a custom implementation:

``java @Component public class DatabaseRoleHierarchy implements RoleHierarchy { private final RoleHierarchyRepo repo; @Override public Collection<? extends GrantedAuthority> getReachableGrantedAuthorities( Collection<? extends GrantedAuthority> authorities) { // For each authority, fetch its reachable roles from the database // Cache the results to avoid repeated DB calls } } ``

Then use this bean instead of RoleHierarchyImpl. This gives you full control over the hierarchy resolution. However, be careful with caching and performance — a naive implementation can cause a database query for every authorization check.

I recommend using a cache like Caffeine with a short TTL to avoid stale hierarchies while keeping performance acceptable.

@Component
public class DatabaseRoleHierarchy implements RoleHierarchy {
    private final RoleHierarchyRepo repo;
    private final Cache<String, Set<GrantedAuthority>> cache;

    public DatabaseRoleHierarchy(RoleHierarchyRepo repo) {
        this.repo = repo;
        this.cache = Caffeine.newBuilder()
            .expireAfterWrite(5, TimeUnit.MINUTES)
            .build();
    }

    @Override
    public Collection<? extends GrantedAuthority> getReachableGrantedAuthorities(
            Collection<? extends GrantedAuthority> authorities) {
        Set<GrantedAuthority> reachable = new HashSet<>();
        for (GrantedAuthority authority : authorities) {
            String role = authority.getAuthority();
            Set<GrantedAuthority> cached = cache.get(role, k -> {
                List<String> roles = repo.findReachableRoles(k);
                return roles.stream()
                    .map(SimpleGrantedAuthority::new)
                    .collect(Collectors.toSet());
            });
            reachable.addAll(cached);
        }
        return reachable;
    }
}