or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

aot-native-support.mdauthentication-core.mdauthentication-events.mdauthentication-management.mdauthentication-tokens.mdauthorities.mdauthorization.mdcompromised-password.mdconcurrent-async.mddao-authentication.mdexpression-access-control.mdindex.mdjaas-authentication.mdjackson-serialization.mdmethod-security.mdobservation-metrics.mdone-time-tokens.mdprovisioning.mdsecurity-context.mdsession-management.mduser-details.md
tile.json

authorities.mddocs/

Authorities and Roles

Authority and role management in Spring Security provides the foundation for authorization decisions. This comprehensive system includes granted authority implementations, mapping strategies, and hierarchical role support.

Key Information for Agents

Core Capabilities:

  • GrantedAuthority interface represents an authority (single method: getAuthority())
  • SimpleGrantedAuthority - Basic string-based authority implementation
  • FactorGrantedAuthority - Authority for multi-factor authentication with time-based tracking
  • Authority mapping via GrantedAuthoritiesMapper for transforming authorities
  • Role hierarchy via RoleHierarchy for hierarchical role relationships
  • Authority utilities via AuthorityUtils for creating and managing authorities

Key Interfaces and Classes:

  • GrantedAuthority - Interface: getAuthority() returns String
  • SimpleGrantedAuthority - Basic implementation (constructor takes String)
  • FactorGrantedAuthority - MFA authority with getIssuedAt() timestamp
  • GrantedAuthoritiesMapper - Maps authorities from one set to another
  • RoleHierarchy - Defines hierarchical role relationships
  • RoleHierarchyImpl - Implementation with builder pattern and string-based configuration
  • AuthorityUtils - Utility class: createAuthorityList(), authorityListToSet(), commaSeparatedStringToAuthorityList()

Default Behaviors:

  • SimpleGrantedAuthority stores authority as String (no validation)
  • FactorGrantedAuthority has standard factor constants (PASSWORD, OTT, WEBAUTHN, etc.)
  • AuthorityUtils.createAuthorityList() creates SimpleGrantedAuthority instances
  • Role hierarchy: getReachableGrantedAuthorities() returns input authorities plus implied ones
  • NullAuthoritiesMapper returns authorities unchanged (no-op)
  • NullRoleHierarchy returns authorities unchanged (no hierarchy)

Threading Model:

  • Authorities are immutable (thread-safe)
  • Mappers and hierarchies are stateless (thread-safe)

Lifecycle:

  • Authorities created during authentication (by providers)
  • Stored in Authentication.getAuthorities()
  • Role hierarchy configured once and reused

Exceptions:

  • CycleInRoleHierarchyException - Thrown when cycle detected in role hierarchy configuration

Edge Cases:

  • Null authority: getAuthority() should not return null (but implementations may allow it)
  • Empty authorities: Valid state (user with no authorities)
  • Role prefix: "ROLE_" prefix convention (configurable via setRolePrefix())
  • Factor authority time: getIssuedAt() returns Instant (may be null for some factors)
  • Hierarchy cycles: Detected and throw exception during configuration
  • Authority comparison: Uses equals() / hashCode() (typically based on authority string)

Core Interfaces

GrantedAuthority

Represents an authority granted to an authentication object.

package org.springframework.security.core;

interface GrantedAuthority extends Serializable {
    @Nullable String getAuthority();
}

Key Methods:

String getAuthority()
  • Returns the string representation of the granted authority.

Usage:

GrantedAuthority authority = new SimpleGrantedAuthority("ROLE_ADMIN");
String authString = authority.getAuthority(); // "ROLE_ADMIN"

GrantedAuthoritiesContainer

Container interface for objects that hold granted authorities.

package org.springframework.security.core.authority;

interface GrantedAuthoritiesContainer extends Serializable {
    Collection<? extends GrantedAuthority> getGrantedAuthorities();
}

Key Methods:

Collection<? extends GrantedAuthority> getGrantedAuthorities()
  • Returns the collection of granted authorities held by this container.

Authority Implementations

SimpleGrantedAuthority

Basic implementation of GrantedAuthority using a string representation.

package org.springframework.security.core.authority;

final class SimpleGrantedAuthority implements GrantedAuthority {
    SimpleGrantedAuthority(String role);

    @Nullable String getAuthority();
    boolean equals(Object obj);
    int hashCode();
    String toString();
}

Constructor:

SimpleGrantedAuthority(String role)

Example:

GrantedAuthority adminAuth = new SimpleGrantedAuthority("ROLE_ADMIN");
GrantedAuthority userAuth = new SimpleGrantedAuthority("ROLE_USER");
GrantedAuthority readAuth = new SimpleGrantedAuthority("READ_PRIVILEGE");

FactorGrantedAuthority

A GrantedAuthority specifically used for indicating the factor used at time of authentication. Supports time-based multi-factor authentication with issued-at tracking.

package org.springframework.security.core.authority;

final class FactorGrantedAuthority implements GrantedAuthority {
    // Standard factor authority constants
    public static final String AUTHORIZATION_CODE_AUTHORITY = "FACTOR_AUTHORIZATION_CODE";
    public static final String BEARER_AUTHORITY = "FACTOR_BEARER";
    public static final String CAS_AUTHORITY = "FACTOR_CAS";
    public static final String OTT_AUTHORITY = "FACTOR_OTT";
    public static final String PASSWORD_AUTHORITY = "FACTOR_PASSWORD";
    public static final String SAML_RESPONSE_AUTHORITY = "FACTOR_SAML_RESPONSE";
    public static final String WEBAUTHN_AUTHORITY = "FACTOR_WEBAUTHN";
    public static final String X509_AUTHORITY = "FACTOR_X509";

    // Factory methods
    public static Builder withAuthority(String authority);
    public static Builder withFactor(String factor);
    public static FactorGrantedAuthority fromAuthority(String authority);
    public static FactorGrantedAuthority fromFactor(String factor);

    // Instance methods
    String getAuthority();
    Instant getIssuedAt();

    // Builder
    public static final class Builder {
        Builder issuedAt(Instant issuedAt);
        FactorGrantedAuthority build();
    }
}

Standard Factor Constants:

The class provides 8 standard factor authority constants for common authentication mechanisms:

  • AUTHORIZATION_CODE_AUTHORITY - OAuth2 Authorization Code
  • BEARER_AUTHORITY - Bearer token authentication
  • CAS_AUTHORITY - CAS authentication
  • OTT_AUTHORITY - One-time token
  • PASSWORD_AUTHORITY - Password authentication
  • SAML_RESPONSE_AUTHORITY - SAML authentication
  • WEBAUTHN_AUTHORITY - WebAuthn authentication
  • X509_AUTHORITY - X.509 certificate authentication

Factory Methods:

  • withAuthority(String) - Creates a builder with the specified authority
  • withFactor(String) - Creates a builder with "FACTOR_" prefix automatically added
  • fromAuthority(String) - Shortcut for withAuthority(authority).build()
  • fromFactor(String) - Shortcut for withFactor(factor).build()

Instance Methods:

  • getAuthority() - Returns the authority string (e.g., "FACTOR_PASSWORD")
  • getIssuedAt() - Returns the instant when this authority was issued

Usage Examples:

import org.springframework.security.core.authority.FactorGrantedAuthority;
import java.time.Instant;

// Using standard factor constants
FactorGrantedAuthority passwordAuth =
    FactorGrantedAuthority.fromAuthority(FactorGrantedAuthority.PASSWORD_AUTHORITY);

FactorGrantedAuthority ottAuth =
    FactorGrantedAuthority.fromAuthority(FactorGrantedAuthority.OTT_AUTHORITY);

// Using custom factor with automatic "FACTOR_" prefix
FactorGrantedAuthority smsAuth = FactorGrantedAuthority.fromFactor("SMS");
// Results in authority: "FACTOR_SMS"

// Building with custom issued-at time
FactorGrantedAuthority webauthnAuth = FactorGrantedAuthority
    .withAuthority(FactorGrantedAuthority.WEBAUTHN_AUTHORITY)
    .issuedAt(Instant.now())
    .build();

// Checking for specific factor in authentication
Authentication auth = SecurityContextHolder.getContext().getAuthentication();
boolean hasPasswordFactor = auth.getAuthorities().stream()
    .anyMatch(authority ->
        FactorGrantedAuthority.PASSWORD_AUTHORITY.equals(authority.getAuthority()));

// Getting issued-at time from factor authority
auth.getAuthorities().stream()
    .filter(a -> a instanceof FactorGrantedAuthority)
    .map(a -> (FactorGrantedAuthority) a)
    .forEach(factor -> {
        System.out.println("Factor: " + factor.getAuthority() +
                          ", Issued: " + factor.getIssuedAt());
    });

Authority Utilities

AuthorityUtils

Utility class for creating and managing granted authorities.

package org.springframework.security.core.authority;

class AuthorityUtils {
    static final List<GrantedAuthority> NO_AUTHORITIES;

    static List<GrantedAuthority> createAuthorityList(String... authorities);
    static Set<String> authorityListToSet(
        Collection<? extends GrantedAuthority> authorities);
    static List<GrantedAuthority> commaSeparatedStringToAuthorityList(
        String authorityString);
}

Constants:

static final List<GrantedAuthority> NO_AUTHORITIES
  • An empty, immutable list of granted authorities.

Static Methods:

static List<GrantedAuthority> createAuthorityList(String... authorities)
  • Creates a list of SimpleGrantedAuthority objects from string values.
static Set<String> authorityListToSet(
    Collection<? extends GrantedAuthority> authorities)
  • Converts a collection of authorities to a set of string representations.
static List<GrantedAuthority> commaSeparatedStringToAuthorityList(
    String authorityString)
  • Converts a comma-separated string to a list of authorities.

Examples:

// Create authority list
List<GrantedAuthority> authorities = AuthorityUtils.createAuthorityList(
    "ROLE_ADMIN",
    "ROLE_USER",
    "READ_PRIVILEGE"
);

// Convert to set of strings
Set<String> authorityStrings = AuthorityUtils.authorityListToSet(authorities);
// Returns: ["ROLE_ADMIN", "ROLE_USER", "READ_PRIVILEGE"]

// Parse comma-separated string
List<GrantedAuthority> parsed =
    AuthorityUtils.commaSeparatedStringToAuthorityList("ROLE_ADMIN,ROLE_USER");

// Empty authorities
List<GrantedAuthority> none = AuthorityUtils.NO_AUTHORITIES;

Authority Mapping

GrantedAuthoritiesMapper

Interface for mapping granted authorities from one set to another, useful for transforming authorities from external systems.

package org.springframework.security.core.authority.mapping;

interface GrantedAuthoritiesMapper {
    Collection<? extends GrantedAuthority> mapAuthorities(
        Collection<? extends GrantedAuthority> authorities);
}

Key Methods:

Collection<? extends GrantedAuthority> mapAuthorities(
    Collection<? extends GrantedAuthority> authorities)
  • Maps the input authorities to a new collection of authorities.

NullAuthoritiesMapper

No-operation mapper that returns the input authorities unchanged.

package org.springframework.security.core.authority.mapping;

class NullAuthoritiesMapper implements GrantedAuthoritiesMapper {
    NullAuthoritiesMapper();

    Collection<? extends GrantedAuthority> mapAuthorities(
        Collection<? extends GrantedAuthority> authorities);
}

Usage:

GrantedAuthoritiesMapper mapper = new NullAuthoritiesMapper();
Collection<GrantedAuthority> mapped = mapper.mapAuthorities(originalAuthorities);
// mapped == originalAuthorities

SimpleAuthorityMapper

Maps authorities with configurable prefix and case conversion.

package org.springframework.security.core.authority.mapping;

class SimpleAuthorityMapper implements GrantedAuthoritiesMapper {
    SimpleAuthorityMapper();

    void setPrefix(String prefix);
    void setConvertToUpperCase(boolean convertToUpperCase);
    void setConvertToLowerCase(boolean convertToLowerCase);
    void setDefaultAuthority(String defaultAuthority);

    Collection<? extends GrantedAuthority> mapAuthorities(
        Collection<? extends GrantedAuthority> authorities);
}

Key Methods:

void setPrefix(String prefix)
  • Sets the prefix to add to all mapped authorities (e.g., "ROLE_").
void setConvertToUpperCase(boolean convertToUpperCase)
  • Converts authority strings to uppercase if true.
void setConvertToLowerCase(boolean convertToLowerCase)
  • Converts authority strings to lowercase if true.
void setDefaultAuthority(String defaultAuthority)
  • Sets a default authority to add if no authorities are present.

Example:

SimpleAuthorityMapper mapper = new SimpleAuthorityMapper();
mapper.setPrefix("ROLE_");
mapper.setConvertToUpperCase(true);
mapper.setDefaultAuthority("ROLE_USER");

// Input: ["admin", "user"]
Collection<GrantedAuthority> input = AuthorityUtils.createAuthorityList("admin", "user");
Collection<? extends GrantedAuthority> output = mapper.mapAuthorities(input);
// Output: ["ROLE_ADMIN", "ROLE_USER"]

// With empty input
Collection<? extends GrantedAuthority> defaulted =
    mapper.mapAuthorities(Collections.emptyList());
// Output: ["ROLE_USER"]

Attributes2GrantedAuthoritiesMapper

Interface for mapping attribute strings to granted authorities.

package org.springframework.security.core.authority.mapping;

interface Attributes2GrantedAuthoritiesMapper {
    List<GrantedAuthority> getGrantedAuthorities(Collection<String> attributes);
}

Key Methods:

List<GrantedAuthority> getGrantedAuthorities(Collection<String> attributes)
  • Converts a collection of attribute strings to granted authorities.

SimpleAttributes2GrantedAuthoritiesMapper

Simple implementation with prefix and case conversion support.

package org.springframework.security.core.authority.mapping;

class SimpleAttributes2GrantedAuthoritiesMapper
    implements Attributes2GrantedAuthoritiesMapper {

    SimpleAttributes2GrantedAuthoritiesMapper();

    void setAttributePrefix(String attributePrefix);
    void setConvertAttributeToUpperCase(boolean convertAttributeToUpperCase);
    void setConvertAttributeToLowerCase(boolean convertAttributeToLowerCase);
    void setAddPrefixIfAlreadyExisting(boolean addPrefixIfAlreadyExisting);

    List<GrantedAuthority> getGrantedAuthorities(Collection<String> attributes);
}

Key Methods:

void setAttributePrefix(String attributePrefix)
  • Sets prefix to add to attribute strings (default: "ROLE_").
void setConvertAttributeToUpperCase(boolean convertAttributeToUpperCase)
  • Converts attributes to uppercase before mapping.
void setConvertAttributeToLowerCase(boolean convertAttributeToLowerCase)
  • Converts attributes to lowercase before mapping.
void setAddPrefixIfAlreadyExisting(boolean addPrefixIfAlreadyExisting)
  • Adds prefix even if attribute already starts with it.

Example:

SimpleAttributes2GrantedAuthoritiesMapper mapper =
    new SimpleAttributes2GrantedAuthoritiesMapper();
mapper.setAttributePrefix("ROLE_");
mapper.setConvertAttributeToUpperCase(true);
mapper.setAddPrefixIfAlreadyExisting(false);

List<String> attributes = Arrays.asList("admin", "user", "ROLE_guest");
List<GrantedAuthority> authorities = mapper.getGrantedAuthorities(attributes);
// Result: [ROLE_ADMIN, ROLE_USER, ROLE_GUEST]

MapBasedAttributes2GrantedAuthoritiesMapper

Maps attributes to authorities using a predefined map configuration.

package org.springframework.security.core.authority.mapping;

class MapBasedAttributes2GrantedAuthoritiesMapper
    implements Attributes2GrantedAuthoritiesMapper {

    MapBasedAttributes2GrantedAuthoritiesMapper();

    void setAttributesToRoles(Map<String, Collection<String>> attributesToRoles);

    List<GrantedAuthority> getGrantedAuthorities(Collection<String> attributes);
}

Key Methods:

void setAttributesToRoles(Map<String, Collection<String>> attributesToRoles)
  • Sets the mapping from attribute names to collections of role names.

Example:

MapBasedAttributes2GrantedAuthoritiesMapper mapper =
    new MapBasedAttributes2GrantedAuthoritiesMapper();

Map<String, Collection<String>> mappings = new HashMap<>();
mappings.put("administrators", Arrays.asList("ROLE_ADMIN", "ROLE_USER"));
mappings.put("users", Collections.singletonList("ROLE_USER"));
mappings.put("guests", Collections.singletonList("ROLE_GUEST"));

mapper.setAttributesToRoles(mappings);

List<String> userAttributes = Arrays.asList("administrators");
List<GrantedAuthority> authorities = mapper.getGrantedAuthorities(userAttributes);
// Result: [ROLE_ADMIN, ROLE_USER]

MappableAttributesRetriever

Interface for retrieving mappable attributes from a system.

package org.springframework.security.core.authority.mapping;

interface MappableAttributesRetriever {
    Set<String> getMappableAttributes();
}

Key Methods:

Set<String> getMappableAttributes()
  • Returns the set of all mappable attribute names.

SimpleMappableAttributesRetriever

Simple implementation of mappable attributes retrieval.

package org.springframework.security.core.authority.mapping;

class SimpleMappableAttributesRetriever
    implements MappableAttributesRetriever {

    SimpleMappableAttributesRetriever();

    void setMappableAttributes(Set<String> mappableAttributes);

    Set<String> getMappableAttributes();
}

Example:

SimpleMappableAttributesRetriever retriever =
    new SimpleMappableAttributesRetriever();
retriever.setMappableAttributes(Set.of("admin", "user", "guest"));

Set<String> attributes = retriever.getMappableAttributes();
// Returns: ["admin", "user", "guest"]

Role Hierarchy

RoleHierarchy

Defines hierarchical relationships between roles, where higher roles implicitly include permissions of lower roles.

package org.springframework.security.access.hierarchicalroles;

interface RoleHierarchy {
    Collection<? extends GrantedAuthority> getReachableGrantedAuthorities(
        Collection<? extends GrantedAuthority> authorities);
}

Key Methods:

Collection<? extends GrantedAuthority> getReachableGrantedAuthorities(
    Collection<? extends GrantedAuthority> authorities)
  • Returns all reachable authorities including the input authorities and any implied by the hierarchy.

RoleHierarchyImpl

Standard implementation of role hierarchy.

package org.springframework.security.access.hierarchicalroles;

class RoleHierarchyImpl implements RoleHierarchy {
    RoleHierarchyImpl();

    static RoleHierarchyImpl fromHierarchy(String hierarchyRepresentation);
    static RoleHierarchyImpl withDefaultRolePrefix();
    static RoleHierarchyImpl withRolePrefix(String rolePrefix);

    void setHierarchy(String roleHierarchyStringRepresentation);

    Collection<? extends GrantedAuthority> getReachableGrantedAuthorities(
        Collection<? extends GrantedAuthority> authorities);
}

Static Factory Methods:

static RoleHierarchyImpl fromHierarchy(String hierarchyRepresentation)
  • Creates a role hierarchy from a string representation where each line contains "role > implied_role".
static RoleHierarchyImpl withDefaultRolePrefix()
  • Creates a builder with the default "ROLE_" prefix.
static RoleHierarchyImpl withRolePrefix(String rolePrefix)
  • Creates a builder with a custom role prefix.

Key Methods:

void setHierarchy(String roleHierarchyStringRepresentation)
  • Sets the role hierarchy from a string representation.

String Format Examples:

// Format: ROLE_A > ROLE_B means ROLE_A includes ROLE_B
String hierarchy = """
    ROLE_ADMIN > ROLE_STAFF
    ROLE_STAFF > ROLE_USER
    ROLE_USER > ROLE_GUEST
    """;

RoleHierarchyImpl roleHierarchy = RoleHierarchyImpl.fromHierarchy(hierarchy);

Builder Example:

RoleHierarchyImpl hierarchy = RoleHierarchyImpl.withDefaultRolePrefix()
    .role("ADMIN").implies("STAFF")
    .role("STAFF").implies("USER")
    .role("USER").implies("GUEST")
    .build();

// Test the hierarchy
Collection<GrantedAuthority> adminAuth =
    AuthorityUtils.createAuthorityList("ROLE_ADMIN");
Collection<? extends GrantedAuthority> reachable =
    hierarchy.getReachableGrantedAuthorities(adminAuth);
// Returns: [ROLE_ADMIN, ROLE_STAFF, ROLE_USER, ROLE_GUEST]

Advanced Configuration:

// Multiple inheritance
String complexHierarchy = """
    ROLE_ADMIN > ROLE_USER
    ROLE_ADMIN > ROLE_STAFF
    ROLE_STAFF > ROLE_EMPLOYEE
    ROLE_USER > ROLE_GUEST
    """;

RoleHierarchyImpl hierarchy = RoleHierarchyImpl.fromHierarchy(complexHierarchy);

Collection<GrantedAuthority> adminRole =
    AuthorityUtils.createAuthorityList("ROLE_ADMIN");
Collection<? extends GrantedAuthority> all =
    hierarchy.getReachableGrantedAuthorities(adminRole);
// Returns: [ROLE_ADMIN, ROLE_USER, ROLE_STAFF, ROLE_EMPLOYEE, ROLE_GUEST]

NullRoleHierarchy

No-operation role hierarchy that returns authorities unchanged.

package org.springframework.security.access.hierarchicalroles;

class NullRoleHierarchy implements RoleHierarchy {
    NullRoleHierarchy();

    Collection<? extends GrantedAuthority> getReachableGrantedAuthorities(
        Collection<? extends GrantedAuthority> authorities);
}

Usage:

RoleHierarchy noHierarchy = new NullRoleHierarchy();
Collection<? extends GrantedAuthority> same =
    noHierarchy.getReachableGrantedAuthorities(authorities);
// Returns the input authorities unchanged

RoleHierarchyAuthoritiesMapper

Granted authorities mapper that applies role hierarchy during mapping.

package org.springframework.security.access.hierarchicalroles;

class RoleHierarchyAuthoritiesMapper implements GrantedAuthoritiesMapper {
    RoleHierarchyAuthoritiesMapper(RoleHierarchy roleHierarchy);

    Collection<? extends GrantedAuthority> mapAuthorities(
        Collection<? extends GrantedAuthority> authorities);
}

Constructor:

RoleHierarchyAuthoritiesMapper(RoleHierarchy roleHierarchy)

Example:

RoleHierarchyImpl hierarchy = RoleHierarchyImpl.withDefaultRolePrefix()
    .role("ADMIN").implies("USER")
    .build();

RoleHierarchyAuthoritiesMapper mapper =
    new RoleHierarchyAuthoritiesMapper(hierarchy);

Collection<GrantedAuthority> authorities =
    AuthorityUtils.createAuthorityList("ROLE_ADMIN");
Collection<? extends GrantedAuthority> expanded =
    mapper.mapAuthorities(authorities);
// Returns: [ROLE_ADMIN, ROLE_USER]

RoleHierarchyUtils

Utility methods for working with role hierarchies.

package org.springframework.security.access.hierarchicalroles;

class RoleHierarchyUtils {
    static String roleHierarchyFromMap(Map<String, List<String>> roleHierarchyMap);
}

Static Methods:

static String roleHierarchyFromMap(Map<String, List<String>> roleHierarchyMap)
  • Converts a map representation to a hierarchy string format.

Example:

Map<String, List<String>> hierarchyMap = new HashMap<>();
hierarchyMap.put("ROLE_ADMIN", Arrays.asList("ROLE_STAFF", "ROLE_USER"));
hierarchyMap.put("ROLE_STAFF", Collections.singletonList("ROLE_USER"));
hierarchyMap.put("ROLE_USER", Collections.singletonList("ROLE_GUEST"));

String hierarchyString = RoleHierarchyUtils.roleHierarchyFromMap(hierarchyMap);
// Result:
// ROLE_ADMIN > ROLE_STAFF
// ROLE_ADMIN > ROLE_USER
// ROLE_STAFF > ROLE_USER
// ROLE_USER > ROLE_GUEST

RoleHierarchyImpl hierarchy = RoleHierarchyImpl.fromHierarchy(hierarchyString);

CycleInRoleHierarchyException

Exception thrown when a cycle is detected in the role hierarchy configuration.

package org.springframework.security.access.hierarchicalroles;

class CycleInRoleHierarchyException extends RuntimeException {
    CycleInRoleHierarchyException(String message);
    CycleInRoleHierarchyException(String message, Throwable cause);
}

Example:

try {
    // This creates a cycle: ADMIN > USER > STAFF > ADMIN
    String cyclicHierarchy = """
        ROLE_ADMIN > ROLE_USER
        ROLE_USER > ROLE_STAFF
        ROLE_STAFF > ROLE_ADMIN
        """;
    RoleHierarchyImpl hierarchy = RoleHierarchyImpl.fromHierarchy(cyclicHierarchy);
} catch (CycleInRoleHierarchyException e) {
    // Handle cyclic hierarchy error
}

Complete Configuration Example

@Configuration
public class AuthorityConfiguration {

    @Bean
    public RoleHierarchy roleHierarchy() {
        return RoleHierarchyImpl.withDefaultRolePrefix()
            .role("ADMIN").implies("STAFF")
            .role("ADMIN").implies("USER")
            .role("STAFF").implies("USER")
            .role("USER").implies("GUEST")
            .build();
    }

    @Bean
    public GrantedAuthoritiesMapper authoritiesMapper() {
        SimpleAuthorityMapper mapper = new SimpleAuthorityMapper();
        mapper.setPrefix("ROLE_");
        mapper.setConvertToUpperCase(true);
        mapper.setDefaultAuthority("ROLE_USER");
        return mapper;
    }

    @Bean
    public Attributes2GrantedAuthoritiesMapper attributeMapper() {
        MapBasedAttributes2GrantedAuthoritiesMapper mapper =
            new MapBasedAttributes2GrantedAuthoritiesMapper();

        Map<String, Collection<String>> mappings = new HashMap<>();
        mappings.put("admin", Arrays.asList("ROLE_ADMIN"));
        mappings.put("staff", Arrays.asList("ROLE_STAFF"));
        mappings.put("user", Arrays.asList("ROLE_USER"));

        mapper.setAttributesToRoles(mappings);
        return mapper;
    }
}

// Usage in custom authentication provider
public class CustomAuthenticationProvider implements AuthenticationProvider {

    private final GrantedAuthoritiesMapper authoritiesMapper;
    private final RoleHierarchy roleHierarchy;

    @Override
    public Authentication authenticate(Authentication authentication) {
        // Authenticate user and get base authorities
        Collection<GrantedAuthority> baseAuthorities =
            loadUserAuthorities(authentication.getName());

        // Map authorities
        Collection<? extends GrantedAuthority> mappedAuthorities =
            authoritiesMapper.mapAuthorities(baseAuthorities);

        // Apply role hierarchy
        Collection<? extends GrantedAuthority> finalAuthorities =
            roleHierarchy.getReachableGrantedAuthorities(mappedAuthorities);

        return new UsernamePasswordAuthenticationToken(
            authentication.getPrincipal(),
            authentication.getCredentials(),
            finalAuthorities
        );
    }
}

Package

  • org.springframework.security.core.authority
  • org.springframework.security.core.authority.mapping
  • org.springframework.security.access.hierarchicalroles