Package org.springframework.security.access.hierarchicalroles

Class RoleHierarchyImpl

java.lang.Object
org.springframework.security.access.hierarchicalroles.RoleHierarchyImpl
All Implemented Interfaces:
RoleHierarchy
public class RoleHierarchyImpl extends Object implements RoleHierarchy

This class defines a role hierarchy for use with various access checking components.

Here is an example configuration of a role hierarchy (hint: read the ">" sign as "includes"): 

     <property name="hierarchy">
         <value>
             ROLE_A > ROLE_B
             ROLE_B > ROLE_AUTHENTICATED
             ROLE_AUTHENTICATED > ROLE_UNAUTHENTICATED
         </value>
     </property>

Explanation of the above:

  • In effect every user with ROLE_A also has ROLE_B, ROLE_AUTHENTICATED and ROLE_UNAUTHENTICATED;
  • every user with ROLE_B also has ROLE_AUTHENTICATED and ROLE_UNAUTHENTICATED;
  • every user with ROLE_AUTHENTICATED also has ROLE_UNAUTHENTICATED.

Hierarchical Roles will dramatically shorten your access rules (and also make the access rules much more elegant).

Consider this access rule for Spring Security's RoleVoter (background: every user that is authenticated should be able to log out): 

/logout.html=ROLE_A,ROLE_B,ROLE_AUTHENTICATED
With hierarchical roles this can now be shortened to: 
/logout.html=ROLE_AUTHENTICATED
In addition to shorter rules this will also make your access rules more readable and your intentions clearer.

  • Constructor Details

  • Method Details

    • fromHierarchy

      public static RoleHierarchyImpl fromHierarchy(String hierarchy)
      Create a role hierarchy instance with the given definition, similar to the following: 
           ROLE_A > ROLE_B
     ROLE_B > ROLE_AUTHENTICATED
     ROLE_AUTHENTICATED > ROLE_UNAUTHENTICATED
      Parameters:
      hierarchy - the role hierarchy to use
      Returns:
      a RoleHierarchyImpl that uses the given hierarchy

    • withDefaultRolePrefix

      public static RoleHierarchyImpl.Builder withDefaultRolePrefix()
      Factory method that creates a RoleHierarchyImpl.Builder instance with the default role prefix "ROLE_"
      Returns:
      a RoleHierarchyImpl.Builder instance with the default role prefix "ROLE_"
      Since:
      6.3

    • withRolePrefix

      public static RoleHierarchyImpl.Builder withRolePrefix(String rolePrefix)
      Factory method that creates a RoleHierarchyImpl.Builder instance with the specified role prefix.
      Parameters:
      rolePrefix - the prefix to be used for the roles in the hierarchy.
      Returns:
      a new RoleHierarchyImpl.Builder instance with the specified role prefix
      Throws:
      IllegalArgumentException - if the provided role prefix is null
      Since:
      6.3

    • setHierarchy

      @Deprecated public void setHierarchy(String roleHierarchyStringRepresentation)
      Deprecated.
      Use fromHierarchy(java.lang.String) instead
      Set the role hierarchy and pre-calculate for every role the set of all reachable roles, i.e. all roles lower in the hierarchy of every given role. Pre-calculation is done for performance reasons (reachable roles can then be calculated in O(1) time). During pre-calculation, cycles in role hierarchy are detected and will cause a CycleInRoleHierarchyException to be thrown.
      Parameters:
      roleHierarchyStringRepresentation - - String definition of the role hierarchy.

    • getReachableGrantedAuthorities

      public Collection<GrantedAuthority> getReachableGrantedAuthorities(Collection<? extends GrantedAuthority> authorities)
      Description copied from interface: RoleHierarchy
      Returns an array of all reachable authorities.

      Reachable authorities are the directly assigned authorities plus all authorities that are (transitively) reachable from them in the role hierarchy.

      Example:
      Role hierarchy: ROLE_A > ROLE_B > ROLE_C.
      Directly assigned authority: ROLE_A.
      Reachable authorities: ROLE_A, ROLE_B, ROLE_C.

      Specified by:
      getReachableGrantedAuthorities in interface RoleHierarchy
      Parameters:
      authorities - - List of the directly assigned authorities.
      Returns:
      List of all reachable authorities given the assigned authorities.