Hierarchy Management Overview

Two hierarchy resolution strategies are supported for authorization decisions:

  • Hierarchy resolution by Generalization: This is the default hierarchy resolution in Jetspeed. If a hierarchy uses a generalization strategy, each role is more general than the previous one. For instance, if a user has the role [roleA.roleB.roleC] then user.getSubject().getPrincipals() returns:
    • /role/roleA
    • /role/roleA/roleB
    • /role/roleA/roleB/roleC
  • Hierarchy resolution by Aggregation: If a hierarchy uses a aggregation strategy, the higher role is responsible for a superset of the activities of the lower role. For instance, if the following roles are available:
    • roleA
    • roleA.roleB
    • roleA.roleB.roleC
    If a user has the role [roleA] then, user.getSubject().getPrincipals() returns:
    • /role/roleA
    • /role/roleA/roleB
    • /role/roleA/roleB/roleC

As described in the authorization SPI section , the SecurityMappingHandler is configured with a specific hierarchy strategy for group and role hierarchy management. See the authorization SPI configuration for a configuration example.

Leveraging Preferences to Manage Hierarchies

The default hierarchy management implementation resolves the hierarchy strategy by leveraging Jetspeed 2's java.util.prefs.Preferences implementation. The Preferences implementation provides the underlying structure in Jetspeed to store user attributes, and roles and groups definitions. The Preferences model provides a hierarchy model that is leveraged to store the base roles and groups hierarchy upon which various resolving strategies can be applied (resolution by generalization or aggregation).

See Jetspeed 2 Preferences implementation section for more information.

How does this work?

The SecurityMappingHandler implementation resolves the mappings between roles and groups. Let's say that we want to find out the roles mapping to a specific group name. To do so, the SecurityMappingHandler implements a getRolePrincipalsInGroup(String groupFullPathName) method. In this method, the group name is mapped to a specific Preferences node. According to a given hierarchy resolution strategy (see overview section ), being in [group A] may mean belonging to a set of groups; the HierarchyResolver is used to do so as illustrated below: 

                        
public Set getRolePrincipalsInGroup(String groupFullPathName)
{
   ...
   Preferences preferences = Preferences.userRoot().node(
       GroupPrincipalImpl.getFullPathFromPrincipalName(groupFullPathName));
   String[] fullPaths = groupHierarchyResolver.resolve(preferences);
   ...
}
The resulting groups are then used to find all associated roles.

As a result of this implementation, the name of a role principal (Principal getName()) in the security layer should match the full path of that user preferences root in the preferences layer (Preference absolutePath(); e.g: /role/theRolePrincipal ).

Group and roles hierarchy are stored in the Preferences layer as follow (the output of exportNode() for Jetspeed's RBMS Preferences implementation): 

                        
<preferences EXTERNAL_XML_VERSION="1.0">
<root type="user">
<map />
    <node name="group1">
    <map />
        <node name="groupid1.1">
        <map />
	    <node name="groupid1.1.1">
            <map />
            </node>
        </node>
    </node>

    <node name="role1">
    <map />
        <node name="roleid1.1">
        <map />
	    <node name="roleid1.1.1">
            <map />
            </node>
        </node>
    </node>
</root>
This structure would define the following group and role hierarchy:
  • /group1/groupid1.1/groupid1.1.1
  • /role1/roleid1.1/roleid1.1.1
Additionally, in this model, the map element can define groups or roles custom properties. For instance, a role could have a rule custom property (or a pointer to a rule) that allow rule based role definition tied to some rule engine (Drools for instance) and is validated when the isInRole method is invoked. For groups, a portal could use group to describe organization and have custom property such as address, city, etc. associated with the organization/group.