Understanding role-based access

Role-based access control provides an alternative to managing access to objects through Access Permissions.
Draft comment:
This topic is shared by ICS, Filenet 5.5.10. As of: 2023-05-10
The role-based access model has the following elements:
  • Role Types
  • Role Instances
  • Role Permissions
Role Types
The Role Type element is defined by subclasses of either CmStaticRole or CmDynamicRole. As part of the role class definition you specify the access that is granted by a role of that type through a list of role access definitions each of which specifies:
  • A class to which access is granted, for example Document or a subclass thereof, or Folder likewise. The class specified is called the controlled class.
  • The access rights granted to an object of the controlled class. This takes the form of an access mask similar to the one in an access permission.

You use the Data Design tool in the Administration Console for Content Platform Engine to create the classes. When you expand Role under Data Design > Classes > Other Classes, you can choose from Static Role or Dynamic Role.

Role Instances
Role Instances are instances of one of the role subclasses CmStaticRole or CmDynamicRole. Each role instance grants access to a specific set of users termed the members of the role. How the membership is determined depends on whether the role subclass is derived from CmStaticRole or CmDynamicRole class.
For static role instances:
The membership is explicitly defined by means of a list of users and/or groups stored in the role instance. A user is considered a member if either specified in that list individually or if the user is a member of a group specified in the list.
For dynamic role instances:
A call to a custom code determines whether a given user is a member of the role. For example, this might consult an external service to determine the membership. The custom code is defined by a Role Membership Action object referenced by the role class definition and specifying either a Java class implementing the RoleMembershipHandler interface or JavaScript code implementing the isUserInRole method per that interface.
Role permissions
Each role permission references a role instance. Role permissions are added to the Permissions list of an object, granting the object access for the members of that role according to the role access definitions of the class of the role. Role permissions can be used in exactly the same way as access permissions – they can be applied directly to an object, they can be defined in the default instance permissions for a class or in a security template, and they can be marked as inheritable so they are propagated through a security proxy. A mixture of multiple access and role permissions can be present in the Permissions list of an object, with the effective access granted being the combination of the access granted by each permission. The access determined by a role permission is logically equivalent to an Allow type of access permission.
Note: Role permissions can only be applied to objects within an object store. They cannot be applied to GCD objects such as the Domain or Object Store object themselves.

Benefits

You can choose whether or not to secure objects with roles. Role-based access provides the following benefits:
Easy to change the access rights granted by a role type
For example, to change the access rights granted to a Document class by a particular type of role, you can simply edit the appropriate role access definition in the class definition for the role class. That change will then take effect automatically for all objects whose access is controlled by instances of the role class.
Changes in role membership are applied automatically
If the membership list of a static role instance is edited, adding or removing users or groups, the change to who is granted access by that role applies automatically to every object controlled by that role instance. Similarly for a dynamic role, if the custom code reaches a different conclusion about a given user being a member of the role, that change is noted for every object controlled by the role.
Note: Caching effects mean that the effect of change in access rights or change in role membership will not necessarily take place instantaneously.
A single role can define different access to different types of objects
For example, a role can define one set of permissions for Documents and another set of permissions for Folders.
Access changes can be handled by the Content Platform Engine administrator
Changing LDAP group membership requires LDAP administration permission and tools. With role-based access, a P8 administrator can use the Administration Console for Content Platform Engine to change the membership of a static role. These access updates take effect more quickly than LDAP updates.
Custom logic
A Dynamic Role offers the opportunity to incorporate custom logic into access control decisions.
Note: Custom logic acts in the context of a role instance and a user only. It is not dependent on the specific object for which access is being evaluated.
Entry template usage
Using role-based access can simplify entry template usage. You can designate a role for the entry template, and the role can be updated with user and group changes without having to update each entry template or existing document added by a template.

When to choose role-based access

Role-based access control works best in an environment where there is a high ratio of controlled objects to role instances. Caching is also most effective in this scenario. A model in which there are only a few objects controlled by each role will generally perform less well and is not recommended.

Access evaluation for roles

Role-based access depends on role permissions that are assigned to objects. The following sequence explains the process of evaluating access with roles:
  1. Fetch the role object that is referenced by the permission and determine its exact class.
  2. Retrieve the effective role access definitions list for that role class.
  3. Look for an entry in that list which is applicable to the class of the object whose access is being evaluated, based on a “nearest superclass” rule. For example, if the access definitions list contains entries for class A and superclass B and the actual object is of class C which is a subclass of B, then the access definition for B would apply.
  4. If no match is found by this rule, the system concludes that the role does not grant any access to objects of that class and returns zeroes as the access granted.
  5. Otherwise, the system remembers the access mask from the access definition and checks whether the specified user is a member of the role:
    • For static roles, that check is accomplished by matching the user members of the role against the evaluation user, and for group members testing if the evaluation user is a member of the group. The user is considered a member of the role if any one of those tests finds a match.
    • For a dynamic role, the same result is achieved by calling the role membership handler isUserInRole method.

    Either way, if the answer is that the user is a member of the role, the system returns the access mask remembered from step 5. Otherwise, an access mask of all zeroes is returned.

The above sequence is performed for each role permission defined for an object. The access masks so obtained are combined with those from any access permissions in the normal precedence order.

Consider an example where there are two types of users having access to documents - Editors who can create and have full control over documents, and Reviewers, who have read-only access to documents and their content along with the ability to link comments in the form of annotations to those documents. Assume that the two role classes are static roles.

  • Role Access Definitions for Editors role class:
    • You require a role access definition where the controlled class is DocumentClassDefinition and the access granted is Read plus Create Instance.
    • Full control of instances is expressed through a role access definition in which the controlled class is Document and the access granted is Full Control.
  • Role Access Definitions for Reviewers role class:
    • You require a role access definition where the controlled class is Document and the access granted is View Properties, View Content and Link.

There can be different sets of editors and/or reviewers for different document classes. Consider a class Claims having its own set of both Editors and Reviewers role class instances. For the Claims class, the role instances are named Claims Editors and Claims Reviewers. You can apply role permissions referencing these instances as:

  • In the Permissions of the class definition for the Claims class, a role permission referencing the Claims Editors role. This establishes the right for those editors to create new Claims documents. To understand how this works, review the access evaluation section to check for Create Instance permission on the class definition.
  • In the Default Instance Permissions of the class definition, a role permission referencing the Claims Editors role and a second one referencing the Claims Reviewers role. This establishes the rights needed by editors and reviewers respectively on new instance (through Permission defaulting).