Introduction

Hierarchical roles let you express that one role automatically includes the permissions of another role. In Spring Security, that means a user with ROLE_ADMIN can implicitly satisfy checks for ROLE_MANAGER and ROLE_USER without storing every lower role directly on the account.

Why Role Hierarchies Help

Without a hierarchy, you either assign every user many overlapping authorities or repeat larger authorization rules everywhere in your configuration. Both approaches get messy quickly.

A hierarchy gives you a compact rule set such as:

• 'ROLE_ADMIN includes ROLE_MANAGER'
• 'ROLE_MANAGER includes ROLE_USER'

That means an admin automatically behaves like a manager and a user for authorization checks.

The important limitation is that a hierarchy changes authorization evaluation. It does not change your domain model by magically rewriting what is stored in the database.

Defining the Hierarchy

Spring Security provides RoleHierarchyImpl for this purpose. A modern Spring Boot configuration can define it as a bean.

1import org.springframework.context.annotation.Bean;
2import org.springframework.context.annotation.Configuration;
3import org.springframework.security.access.hierarchicalroles.RoleHierarchy;
4import org.springframework.security.access.hierarchicalroles.RoleHierarchyImpl;
5
6@Configuration
7public class SecurityRolesConfig {
8    @Bean
9    RoleHierarchy roleHierarchy() {
10        return RoleHierarchyImpl.fromHierarchy("""
11            ROLE_ADMIN > ROLE_MANAGER
12            ROLE_MANAGER > ROLE_USER
13        """);
14    }
15}

The arrow means “includes.” So ROLE_ADMIN > ROLE_MANAGER means an admin also has manager-level authority during security checks.

Using the Hierarchy in Authorization Logic

Where developers often get confused is assuming that declaring a RoleHierarchy bean automatically affects every authorization decision everywhere. In practice, you need to ensure the relevant security components use it.

One common place is method security. If you use annotations such as @PreAuthorize, connect the hierarchy through a method-security expression handler.

1import org.springframework.context.annotation.Bean;
2import org.springframework.context.annotation.Configuration;
3import org.springframework.security.access.expression.method.DefaultMethodSecurityExpressionHandler;
4import org.springframework.security.access.hierarchicalroles.RoleHierarchy;
5import org.springframework.security.config.annotation.method.configuration.EnableMethodSecurity;
6
7@Configuration
8@EnableMethodSecurity
9public class MethodSecurityConfig {
10    @Bean
11    DefaultMethodSecurityExpressionHandler methodSecurityExpressionHandler(RoleHierarchy roleHierarchy) {
12        DefaultMethodSecurityExpressionHandler handler = new DefaultMethodSecurityExpressionHandler();
13        handler.setRoleHierarchy(roleHierarchy);
14        return handler;
15    }
16}

Then your service layer can stay clean:

1import org.springframework.security.access.prepost.PreAuthorize;
2import org.springframework.stereotype.Service;
3
4@Service
5public class ReportService {
6    @PreAuthorize("hasRole('USER')")
7    public String userReport() {
8        return "visible to USER, MANAGER, and ADMIN through the hierarchy";
9    }
10}

With the hierarchy configured, ROLE_ADMIN satisfies hasRole('USER') without extra duplication.

Keep Roles Small and Meaningful

A hierarchy is useful when roles actually represent increasing levels of authority. It is less useful when roles are really unrelated capabilities.

For example, these often fit a hierarchy well:

• guest n- user
• manager
• admin

But capabilities such as CAN_EXPORT_REPORTS and CAN_APPROVE_REFUNDS are often better modeled as authorities or permissions, not as steps in a ladder. If you force unrelated privileges into a hierarchy, authorization becomes harder to reason about.

A practical rule is:

• use roles for broad identity categories
• use authorities or permissions for precise business actions

Web Security Versus Method Security

Hierarchical roles can be applied in both web request rules and method security, but many teams get the most value from method security because it protects the business operation directly.

Request rules guard URLs. Method rules guard service methods. If an endpoint changes, internal code paths still remain protected when the method-level rule is correct.

That is why it is often better to treat URL rules as the first gate and method security as the definitive business check.

Common Pitfalls

The most common mistake is assuming a role hierarchy bean automatically rewires all authorization components. You need to verify that the relevant expression handlers or authorization managers actually use it.

Another common problem is building hierarchies out of unrelated permissions. That makes the system harder to audit because the role names stop reflecting clear business meaning.

Developers also often store every implied role directly in the database. That defeats part of the benefit of a hierarchy and makes role management more error-prone.

Finally, do not confuse role hierarchy with authentication. The hierarchy helps answer “what may this authenticated user do,” not “who is this user.”

Summary

• Hierarchical roles let higher roles satisfy checks for lower roles.
• Define the hierarchy with RoleHierarchyImpl and connect it to the security components that evaluate access.
• Use hierarchies for broad role ladders, not for arbitrary unrelated permissions.
• Prefer method security for core business protection, even when URL rules also exist.
• Keep the database model simple and let the hierarchy express implied access.