5.1. Using Roles
Roles are a new entry grouping mechanism that unify the static and dynamic groups described in the previous sections. Roles are designed to be more efficient and easier to use for applications. For example, an application can get the list of roles of which an entry is a member by querying the entry itself, rather than selecting a group and browsing the members list of several groups.
This section contains the following topics:
Roles unify the static and dynamic group concept supported by previous versions of Directory Server.
Roles can be used to organize users in number of different ways:
To enumerate the members of a role.
Having an enumerated list of role members can be useful for resolving queries for role members quickly.
To determine whether a given entry possesses a particular role.
Knowing the roles possessed by an entry can help determine whether the entry possesses the target role.
To enumerate all the roles possessed by a given entry.
To assign a particular role to a given entry.
To remove a particular role from a given entry.
Managed roles can do everything that can normally be done with static groups. The role members can be filtered using filtered roles, similarly to the filtering with dynamic groups. Roles are easier to use than groups, more flexible in their implementation, and reduce client complexity.
However, evaluating roles is more resource-intensive because the server does the work for the client application. With roles, the client application can check role membership by searching the nsRole attribute. The nsRole attribute is a computed attribute, which identifies to which roles an entry belongs; the nsRole attribute is not stored with the entry itself. From the client application point of view, the method for checking membership is uniform and is performed on the server side.
The nsRole attribute is an operational attribute. In LDAP, operational attributes must be requested explicitly in the search attributes list; they are not returned by default with the regular attributes in the schema of the entry. For example, this ldapsearch command returns the list of roles of which uid=scarter is a member, in addition to the regular attributes for the entry:
ldapsearch ... args ... “(uid=scarter)” \* nsRole
Be sure to use the nsRole attribute, not the nsRoleDN attribute, to evaluate role membership.
The Console will automatically show the roles.
Each role has members, or entries that possess the role. Members can be specified either explicitly or dynamically. How role membership is specified depends upon the type of role. Directory Server supports three types of roles:
Managed roles have an explicit enumerated list of members.
Filtered roles are assigned entries to the role depending upon the attribute contained by each entry, specified in an LDAP filter. Entries that match the filter are said to possess the role.
Nested roles are roles that contain other roles.
The concept of activating/inactivating roles allows entire groups of entries to be activated or inactivated in just one operation. That is, he members of a role can be temporarily disabled by inactivating the role to which they belong.
When a role is inactivated, it does not mean that the user cannot bind to the server using that role entry. The meaning of an inactivated role is that the user cannot bind to the server using any of the entries that belong to that role; the entries that belong to an inactivated role will have the nsAccountLock attribute set to true.
In the case of the nested role, an inactivated nested role means that a user cannot bind to the server using an entry that belongs to a role that is a member of the nested role. All the entries that belong to a role that directly or indirectly are members of the nested role (one may have several levels of nested roles) will have nsAccountLock set to true.
The nsAccountLock attribute is an operational attribute and must be explicitly requested in the search command in the list of search attributes. For example:
ldapsearch ... args ... “(uid=scarter)” \* nsAccountLock
The Console will automatically show the active/inactive status of entries.
This section contains the following procedures for creating and modifying roles:
When a role is created, determine whether a user can add themselves or remove themselves from the role. See Section 5.1.4, “Using Roles Securely” for more information about roles and access control.
Managed roles have an explicit enumerated list of members. Managed roles are added to entries by adding the nsRoleDN attribute to the entry.
To create and add members to a managed role, do the following:
In the Directory Server Console, select the Directory tab.
Browse the tree in the left navigation pane, and select the parent entry for the new role.
Go to the Object menu, and select New > Role.
Alternatively, right-click the entry and select New > Role.
The Create New Role dialog box is displayed.
Click General in the left pane. Type a name for the new role in the Role Name field.
The role name is required.
Enter a description of the new role in the Description field.
Click Members in the left pane.
A search dialog box appears briefly.
In the right pane, select Managed Role. Click Add to add new entries to the list of members.
The standard Search users and groups dialog box appears.
In the Search drop-down list, select Users from the Search drop-down list, then click Search. Select one of the entries returned, and click OK.
After adding all of the entries, click OK.
The new role appears in the right pane.
The nsRoleDN attribute is an operational attribute and must be explicitly requested in the search command in the list of search attributes. For example:
ldapsearch ... args ... “(uid=scarter)” \* nsRole nsRoleDN
The Console will automatically show the nsRoleDN attribute.
Entries are assigned to a filtered role depending upon a particular attribute contained by each entry. The role definition specifies an LDAP filter for the target attributes. Entries that match the filter possess (are members of) the role.
To create and add members to a filtered role, do the following:
Follow the steps of Section 5.1.2.1, “Creating a Managed Role”.
Click Members in the left pane.
A search dialog box appears briefly.
In the right pane, select Filtered Role.
Enter an LDAP filter in the text field, or click Construct to be guided through the construction of an LDAP filter.
The Construct opens the standard LDAP URL construction dialog. Ignore the fields for LDAP Server Host, Port, Base DN, and Search (since the search scope cannot be set filtered role definitions).
Select the types of entries to filter from the For drop-down list.
The entries can be users, groups, or both.
Select an attribute from the Where drop-down list. The two fields following it refine the search by selecting one of the qualifiers from the drop-down list, such as contains, does not contain, is, or is not. Enter an attribute value in the text box. To add additional filters, click More. To remove unnecessary filters, click Fewer.
Click OK.
Click Test to try the filter.
A Filter Test Result dialog box displays the entries matching the filter.
Click OK.
The new role appears in the right pane.
The nsRoleDN attribute is an operational attribute and must be explicitly requested in the search command in the list of search attributes. For example:
ldapsearch ... args ... “(uid=scarter)” \* nsRole nsRoleDN
The Directory Server Console automatically shows the nsRoleDN attribute.
Nested roles are roles that contain other roles. Before it is possible to create a nested role, another role must exist. When a nested role is created, the Console displays a list of the roles available for nesting. The roles nested within the nested role are specified using the nsRoleDN attribute.
To create and add members to a nested role, do the following:
Create a new role, as in Section 5.1.2.1, “Creating a Managed Role”.
Click Members in the left pane.
A search dialog box appears briefly.
In the right pane, select Nested Role.
Click Add to add roles to the list. The members of the nested role are members of other existing roles.
The Role Selector dialog box opens.
Select a role from the Available roles list, and click OK.
Click OK to save the new role.
The new role appears in the right pane.
The nsRoleDN attribute is an operational attribute and must be explicitly requested in the search command in the list of search attributes. For example:
ldapsearch ... args ... “(uid=scarter)” \* nsRole nsRoleDN
The Console will automatically show the nsRoleDN attribute.
To view or edit a role associated with an entry from the Console, do the following:
In the Directory Server Console, select the Directory tab.
In the left navigation pane, browse the tree, and select the entry for which to view or edit a role.
Select Set Roles from the Object menu.
The Roles dialog box opens.
Select the Managed Roles tab to display the managed roles to which this entry belongs.
To add a new managed role, click Add, and select an available role from the Role Selector window. Click OK.
To remove a managed role, select it, and click Remove.
To edit a managed role associated with an entry, click Edit. The Edit Entry dialog box opens. Make any changes to the general information or members and click OK.
Select the Other Roles tab to view the filtered or nested roles to which this entry belongs.
Click Edit to make changes to any filtered or nested roles associated with the entry. Click OK.
Click OK to save the changes.
To edit an existing role, do the following:
In the Directory Server Console, select the Directory tab.
Browse the navigation tree in the left pane to locate the base DN for the role. Roles are listed in the right pane with other entries.
Double-click the role.
The Edit Entry dialog box appears.
Click General in the left pane to change the role name and description.
Click Members in the left pane to change the members of managed and nested roles or to change the filter of a filtered role.
Click OK to save the changes.
Members of a role can be temporarily disabled by inactivating the role to which they belong. Inactivating a role inactivates the entries possessed by the role, not the role itself.
To temporarily disable the members of a role, do the following:
In the Directory Server Console, select the Directory tab.
Browse the navigation tree in the left pane to locate the base DN for the role. Roles appear in the right pane with other entries.
Select the role. Select Inactivate from the Object menu.
Alternatively, right-click the role and select Inactivate from the menu.
The role is inactivated.
To see the inactivated entries, select Inactivation State from the View menu. A red slash through the role icon indicates that the role has been inactivated.
To reactivate a disabled role:
In the Directory Server Console, select the Directory tab.
Browse the navigation tree in the left pane to locate the base DN for the role. Roles appear in the right pane with other entries.
Select the role. Select Activate from the Object menu.
Alternatively, right-click the role and select Activate from the menu.
The role is reactivated.
To see inactivated entries, select Inactivation State from the View > Display menu. The role icon appears as normal, indicating that the role is active.
Deleting a role deletes the role only, not its members. To delete a role, do the following:
In the Directory Server Console, select the Directory tab.
Browse the navigation tree in the left pane to locate the base DN for the role. Roles appear in the right pane with other entries.
Right-click the role, and select Delete.
A dialog box appears to confirm the deletion. Click Yes.
Deleting a role deletes the role entry but does not delete the nsRoleDN attribute for each role member. To delete the nsRoleDN attribute for each role member, enable the Referential Integrity plug-in, and configure it to manage the nsRoleDN attribute. For more information on the Referential Integrity plug-in, see Section 2.5, “Maintaining Referential Integrity”.
Roles inherit from the ldapsubentry object class, which is defined in the ITU X.509 standard. In addition, each type of role has two specific object classes that inherit from the nsRoleDefinition object class. Once a role is created, members are assigned to it as follows:
Members of a managed role have the nsRoleDN attribute in their entry.
Members of a filtered role are entries that match the filter specified in the nsRoleFilter attribute.
Members of a nested role are members of the roles specified in the nsRoleDN attributes of the nested role definition entry.
Table 5.1, “Object Classes and Attributes for Roles” lists the object classes and attributes associated with each type of role.
| Role Type | Object Classes | Attributes | ||||
|---|---|---|---|---|---|---|
| Managed Role |
|
description (optional) | ||||
| Filtered Role |
|
|
||||
| Nested Role |
|
|
The attributes nsRole and nsRoleDN are operational attributes. This means that they are not present in the schema of the entry and may be added to any entry, regardless of schema. This also means that these attributes must be explicitly requested in the search attributes list in search requests. For example, this ldapsearch command lists all of the roles (values of nsRole), all of the managed roles (values of nsRoleDN), and all of the regular attributes in the entry matched by uid=scarter.
ldapsearch ... args ... “(uid=scarter)” \* nsRole nsRoleDN
Similarly for the role definition entries, they are operational entries and are not returned by default with regular searches. This means that if roles are defined under the ou=People,dc=example,dc=com subtree, for example, the following ldapsearch command will not return the role definitions for any entry:
ldapsearch -s sub -b ou=People,dc=example,dc=com “(objectclass=*)”
To see the role definitions entries, use the special search filter "(objectclass=ldapSubEntry)"with ldapsearch. The special filter can be added to any other search filter, using OR (|):
ldapsearch -s sub -b ou=People,dc=example,dc=com “(|(objectclass=*)(objectclass=ldapSubEntry))”
This search shows all regular entries in addition to role definition entries in the ou=People,dc=example,dc=com subtree. The Console automatically shows all of the role entries.
In some cases, the value of the nsRoleDNattribute must be protected with an ACI, as the attribute is writable. For more information about security and roles, see Section 5.1.4, “Using Roles Securely”.
Example Corporation's administrator is creating a role to be assigned to all marketing staff by doing the following:
Run ldapmodify:
ldapmodify -D "cn=Directory Manager" -w secret -h host -p 389
Create the managed role entry, containing the nsManagedRoleDefinition object class, which in turn inherits from the LdapSubEntry, nsRoleDefinition, and nsSimpleRoleDefinition object classes.
dn: cn=Marketing,ou=people,dc=example,dc=com objectclass: top objectclass: LdapSubEntry objectclass: nsRoleDefinition objectclass: nsSimpleRoleDefinition objectclass: nsManagedRoleDefinition cn: Marketing description: managed role for marketing staff
Assign the role to a marketing staff member named Bob, using ldapmodify:
ldapmodify -D "cn=Directory Manager" -w secret -h host -p 389 dn: cn=Bob,ou=people,dc=example,dc=com changetype: modify add: nsRoleDN nsRoleDN: cn=Marketing,ou=people,dc=example,dc=com
The nsRoleDN attribute in the entry indicates that the entry is a member of a managed role, cn=Marketing,ou=people,dc=example,dc=com.
Example Corporation's administrator is creating a filtered role for sales managers.
Run ldapmodify:
ldapmodify -D "cn=Directory Manager" -w secret -h host -p 389
Create the filtered role entry.
The role entry has the nsFilteredRoleDefinition object class, which inherits from the LdapSubEntry, nsRoleDefinition, and nsComplexRoleDefinition object classes.
The nsRoleFilter attribute sets a filter for o (organization) attributes that contain a value of sales managers.
dn: cn=SalesManagerFilter,ou=people,dc=example,dc=com objectclass: top objectclass: LDAPsubentry objectclass: nsRoleDefinition objectclass: nsComplexRoleDefinition objectclass: nsFilteredRoleDefinition cn: SalesManagerFilter nsRoleFilter: o=sales managers Description: filtered role for sales managers
The following entry matches the filter (possesses the o attribute with the value sales managers), and, therefore, it is a member of this filtered role automatically:
dn: cn=Pat,ou=people,dc=example,dc=com objectclass: person cn: Pat sn: Pat userPassword: bigsecret o: sales managers
The Example Corporation administrator is creating a nested role that contains both the marketing staff and sales managers who are members of the roles marketing managed role and the sales filtered role.
Run ldapmodify:
ldapmodify -D "cn=Directory Manager" -w secret -h host -p 389
Create the nested role entry. The nested role has the the nsNestedRoleDefinition object class, which inherits from the LDAPsubentry, nsRoleDefinition, and nsComplexRoleDefinition object classes. The nsRoleDN attributes contain the DNs for both the marketing managed role and the sales managers filtered role.
dn: cn=MarketingSales,ou=people,dc=example,dc=com objectclass: top objectclass: LDAPsubentry objectclass: nsRoleDefinition objectclass: nsComplexRoleDefinition objectclass: nsNestedRoleDefinition cn: MarketingSales nsRoleDN: cn=SalesManagerFilter,ou=people,dc=example,dc=com nsRoleDN: cn=Marketing,ou=people,dc=example,dc=com
Both of the users in the previous examples, Bob and Pat, would be members of this new nested role.
Not every role is suitable for use in a security context. When creating a new role, consider how easily the role can be assigned to and removed from an entry. Sometimes it is appropriate for users to be able to adder remove themselves easily from a role. For example, if there is an interest group role called Mountain Biking, interested users should be able to add themselves or remove themselves easily.
However, in some security contexts, it is inappropriate to have such open roles. Consider account inactivation roles. By default, account inactivation roles contain ACIs defined for their suffix. When creating a role, the server administrator decides whether a user can assign themselves to or remove themselves from the role.
For example, user A possesses the managed role, MR. The MR role has been locked using account inactivation. This means that user A cannot bind to the server because the nsAccountLock attribute is computed as true for that user. However, suppose the user was already bound and noticed that he is now locked through the MR role. If there are no ACIs preventing him, the user can remove the nsRoleDN attribute from his entry and unlock himself.
To prevent users from removing the nsRoleDN attribute, use the following ACIs depending upon the type of role being used.
Managed roles. For entries that are members of a managed role, use the following ACI to prevent users from unlocking themselves by removing the appropriate nsRoleDN:
aci: (targetattr="nsRoleDN") (targattrfilters= add=nsRoleDN:(!(nsRoleDN=cn=AdministratorRole,
dc=example,dc=com)), del=nsRoleDN:(!(nsRoleDN=cn=nsManagedDisabledRole,dc=example,dc=com)))
(version3.0;aci allow mod of nsRoleDN by self but not to critical values; allow(write)
userdn=ldap:///self;)
Filtered roles. The attributes that are part of the filter should be protected so that the user cannot relinquish the filtered role by modifying an attribute. The user should not be allowed to add, delete, or modify the attribute used by the filtered role. If the value of the filter attribute is computed, then all attributes that can modify the value of the filter attribute should be protected in the same way.
Nested roles. A nested role is comprised of filtered and managed roles, so the above points should be considered for each of the roles that comprise the nested role.
For more information about account inactivation, see Section 7.2, “Inactivating Users and Roles”.