Search

Chapter 2. Using roles in Directory Server

download PDF

You can group Directory Server entries by using roles. Roles behave as both a static and a dynamic group. Roles are easier to use than groups because they are more flexible in their implementation. For example, an application can get the list of roles to which an entry belongs by querying the entry itself rather than selecting a group and browsing the members list of several groups.

You can manage roles by using the command line or the web console.

2.1. Roles in Directory Server

A role behaves as both a static and a dynamic group, similarly to a hybrid group:

  • With a group, Directory Server adds entries to the group entry as members.
  • With a role, Directory Server adds the role attribute to the entry and then uses this attribute to automatically identify members in the role entry.

Role members are entries that possess the role. You can specify members of the role explicitly or dynamically depending on the role type. Directory Server supports the following types of roles:

  • Managed roles

    Managed roles have an explicit list of members. You can use managed roles to perform the same tasks that you perform with static groups.

  • Filtered roles

    You can filter the role members by using filtered roles, similarly to filtering with dynamic groups. Directory Server assigns entries to a filtered role depending on whether the entry possesses a specific attribute defined in the role.

  • Nested roles

    Nested roles can contain managed and filtered roles.

When you create a role, determine if users can add or remove themselves from the role. For more details, see Section 2.2, “Using roles securely in Directory Server”.

Note

Evaluating roles is more resource-intensive for the Directory Server than evaluating groups because the server does the work for the client application. With roles, the client application can check role membership by searching for the nsRole attribute. The nsRole attribute is a computed attribute that identifies which roles an entry belongs to. Directory Server does not store the nsRole attribute. From the client application point of view, the method for checking membership is uniform and is performed on the server side.

Find considerations for using roles in [Deciding between groups and roles] in the Planning and designing a directory service. documentation.

2.2. Using roles securely in Directory Server

When creating a new role, consider if users can easily add or remove themselves from a role. For example, you can allow users of the Mountain Biking interest group role to add or remove themselves easily. However, you must not allow users who are assigned the Marketing role to add or remove themselves from the role.

One potential security risk is inactivating user accounts by inactivating roles. Inactive roles have special access control instructions (ACIs) defined for their suffix. If an administrator allows users to add and remove themselves from roles freely, these users can remove themselves from an inactive role to unlock their accounts.

For example, a user is assigned a managed role. When Directory Server locks this managed role by using account inactivation, the user can not bind to the server because Directory Server computes the nsAccountLock attribute as true for that user. However, if the user was already bound to Directory Server and now is locked through the managed role, the user can remove the nsRoleDN attribute from his entry and unlock himself if no restricting ACIs are specified.

To prevent users from removing the nsRoleDN attribute, use the following ACIs depending on the type of role:

  • Managed roles. For entries that are members of a managed role, use the following ACI:

    aci: (targetattr="nsRoleDN")
    (targattrfilters= add=nsRoleDN:(!(nsRoleDN=cn=AdministratorRole,dc=example,dc=com)), del=nsRoleDN:(!(nsRoleDN=cn=nsManagedDisabledRole,dc=example,dc=com)))
    (version3.0;acl "allow mod of nsRoleDN by self but not to critical values"; allow(write) userdn=ldap:///self;)
  • Filtered roles. Protect attributes that are part of the filter (nsRoleFilter). Do not allow a user to add, delete, or modify the attribute that the filtered role uses. If Directory Server computes the value of the filter attribute, then you must protect all attributes that can modify this filter attribute value.
  • Nested roles. A nested role can contain filtered and managed roles. Thus, you must restrict modify operations in ACIs for each attribute of the roles that the nested role contains.

2.3. Managing roles in Directory Server by using the command line

You can view, create, and delete roles by using the command line.

2.3.1. Creating a managed role in Directory Server

Managed roles are roles that have an explicit enumerated list of members. You can use the ldapmodify utility to create a managed role. The following example creates a managed role for a marketing team.

Prerequisites

  • The ou=people,dc=example,dc=com parent entry exists in Directory Server.
  • The cn=Bob Jones,ou=people,dc=example,dc=com user entry exists in Directory Server.

Procedure

  1. Create the cn=Marketing managed role entry by using the ldapmodify command with the -a option:

    # ldapmodify -a -D "cn=Directory Manager" -W -H ldap://server.example.com -x << EOF
    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 the marketing team
    EOF

    The managed role entry must contain the following object classes:

    • LDAPsubentry
    • nsRoleDefinition
    • nsSimpleRoleDefinition
    • nsManagedRoleDefinition
  2. Assign the cn=Marketing,ou=people,dc=example,dc=com managed role to the cn=Bob Jones,ou=people,dc=example,dc=com user entry by adding the nsRoleDN attribute to this user entry:

    # ldapmodify -D "cn=Directory Manager" -W -H ldap://server.example.com -x << EOF
    dn: cn=Bob Jones,ou=people,dc=example,dc=com
    changetype: modify
    add: nsRoleDN
    nsRoleDN: cn=Marketing,ou=people,dc=example,dc=com
    EOF
    
    modifying entry "cn=Bob Jones,ou=people,dc=example,dc=com"
  3. Optional: Configure the equality index for the nsRoleDN attribute in the userRoot database to avoid unindexed searches:

    #  dsconf -D "cn=Directory Manager" ldap://server.example.com backend index add --index-type eq --attr nsroleDN --reindex userRoot

Verification

  • List user entries that now belong to the cn=Marketing,ou=people,dc=example,dc=com managed role:

    # ldapsearch -D "cn=Directory Manager" -W -H ldap://server.example.com -x -b "dc=example,dc=com" "(nsRole=cn=Marketing,ou=people,dc=example,dc=com)" dn 
    
    dn: cn=Bob Jones,ou=people,dc=example,dc=com
    
    dn: cn=Tom Devis,ou=people,dc=example,dc=com

2.3.2. Creating a filtered role in Directory Server

Directory Server assigns entries to a filtered role if the entries have a specific attribute defined in the role. The role definition specifies the nsRoleFilter LDAP filter. Entries that match the filter are members of the role.

You can use ldapmodify utility to create a filtered role. The following example creates a filtered role for sales department managers.

Prerequisites

  • The ou=people,dc=example,dc=com parent entry exists in Directory Server.

Procedure

  1. Create the cn=SalesManagerFilter filtered role entry by using the ldapmodify command with the -a option:

    # ldapmodify -a -D "cn=Directory Manager" -W -H ldap://server.example.com -x << EOF
    dn: cn=SalesManagerFilter,ou=people,dc=example,dc=com
    changetype: add
    objectclass: top
    objectclass: LDAPsubentry
    objectclass: nsRoleDefinition
    objectclass: nsComplexRoleDefinition
    objectclass: nsFilteredRoleDefinition
    cn: SalesManagerFilter
    nsRoleFilter: o=sales managers
    Description: filtered role for sales managers
    EOF

    The cn=SalesManagerFilter filtered role entry has the o=sales managers filter for the role. All user entries that have the o attribute with the value of sales managers are members of the filtered role.

    Example of the user entry that is now a member of the filtered role:

    dn: cn=Pat Smith,ou=people,dc=example,dc=com
    objectclass: person
    cn: Pat
    sn: Smith
    userPassword: password
    o: sales managers

    The filtered role entry must have the following object classes:

    • LDAPsubentry
    • nsRoleDefinition
    • nsComplexRoleDefinition
    • nsFilteredRoleDefinition
  2. Optional: Configure the equality index for the attribute that you use in the nsRoleFilter role filter to avoid unindexed searches. In the given example, the role uses o=sales managers as the filter. Therefore, index the o attribute to improve the search performance:

    #  dsconf -D "cn=Directory Manager" ldap://server.example.com backend index add --index-type eq --attr o --reindex userRoot

Verification

  • List user entries that now belong to the cn=SalesManagerFilter,ou=people,dc=example,dc=com filtered role:

    # ldapsearch -D "cn=Directory Manager" -W -H ldap://server.example.com -x -b "dc=example,dc=com" "(nsRole=cn=SalesManagerFilter,ou=people,dc=example,dc=com)" dn 
    
    dn: cn=Jess Mor,ou=people,dc=example,dc=com
    
    dn: cn=Pat Smith,ou=people,dc=example,dc=com

2.3.3. Creating a nested role in Directory Server

Nested roles can contain managed and filtered roles. A nested role entry requires the nsRoleDN attribute to identify the roles to nest.

You can use ldapmodify utility to create a nested role. The following example creates a nested role that contains the managed and the filtered roles you created in Creating a managed role in Directory Server and Creating a filtered role in Directory Server.

Prerequisites

  • The ou=people,dc=example,dc=com parent entry exists in Directory Server.

Procedure

  1. Create the cn=MarketingSales nested role entry that contains the cn=SalesManagerFilter filtered role and the cn=Marketing managed role by using the ldapmodify command with the -a option:

    # ldapmodify -a -D "cn=Directory Manager" -W -H ldap://server.example.com -x << EOF
    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
    EOF

    Optionally, the role can have the description attribute.

    The nested role entry must have the following object classes:

    • LDAPsubentry
    • nsRoleDefinition
    • nsComplexRoleDefinition
    • nsNestedRoleDefinition

Verification

  • List user entries that now belong to the cn=MarketingSales nested role:

    # ldapsearch -D "cn=Directory Manager" -W -H ldap://server.example.com -x -b "dc=example,dc=com" "(nsRole=cn=MarketingSales,ou=people,dc=example,dc=com)" dn 
    
    dn: cn=Bob Jones,ou=people,dc=example,dc=com
    dn: cn=Pat Smith,ou=people,dc=example,dc=com
    dn: cn=Jess Mor,ou=people,dc=example,dc=com
    dn: cn=Tom Devis,ou=people,dc=example,dc=com

2.3.4. Viewing roles for an entry

To view roles for an entry, use the ldapsearch command with explicitly specified nsRole virtual attribute.

Prerequisites

  • Roles entry exists.
  • You assigned roles to the uid=user_name user entry.

Procedure

  • Search for the uid=user_name entry with specified nsRole virtual attribute:

    # ldapsearch -D "cn=Directory Manager" -W -H ldap://server.example.com -b "dc=example,dc=com" -s sub -x "(uid=user_name)" nsRole
    
    dn: uid=user_name,ou=people,dc=example,dc=com
    ...
    nsRole: cn=Role for Managers,dc=example,dc=com
    nsRole: cn=Role for Accounting,dc=example,dc=com

    The command retrieves all roles which the uid=user_name user is a member of.

2.3.5. Deleting roles in Directory Server

To delete a role in Directory Server, you can use ldapmodify command.

The following is an example of deleting the cn=Marketing managed role from Directory Server.

Procedure

  • To delete the cn=Marketing managed role entry, enter:

    # ldapmodify -D "cn=Directory Manager" -W -H ldap://server.example.com -x << EOF
    dn: cn=Marketing,ou=People,dc=example,dc=com
    changetype: delete
    EOF
    
    deleting entry "cn=Marketing,ou=People,dc=example,dc=com"
    Note

    When you delete a role, Directory Server deletes only the role entry and 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 this plug-in to manage the nsRoleDN attribute.

    For more information about the Referential Integrity plug-in, see Using Referential Integrity to maintain relationships between entries.

Additional resources

2.4. Managing roles in Directory Server by using the web console

You can view, create, and delete roles by using LDAP browser in the web console.

2.4.1. Creating a role in the LDAP Browser

You can create a role for a Red Hat Directory Server entry by using the LDAP Browser wizard in the web console.

Prerequisites

  • Access to the web console.
  • A parent entry exists in Directory Server.

Procedure

  1. Log in to the web console and click Red Hat Directory Server.
  2. After the web console loads the Red Hat Directory Server interface, open the LDAP Browser.
  3. Select an LDAP entry and open the Options menu.
  4. From the drop-down menu select New and click Create a new role.
  5. Follow the steps in the wizard and click the Next button after you complete each step.
  6. To create the role, review the role settings in the Create Role step and click the Create button. You can click the Back button to modify the role settings or click the Cancel button to cancel the role creation.
  7. To close the wizard window, click the Finish button.

Verification

  • Expand the LDAP entry and verify the new role appears among the entry parameters.

2.4.2. Deleting a role in the LDAP browser

You can delete the role from the Red Hat Directory Server entry by using the LDAP Browser in the web console.

Prerequisites

  • Access to the web console.
  • A parent entry exists in Directory Server.

Procedure

  1. Log in to the web console and click Red Hat Directory Server.
  2. After the web console loads the Red Hat Directory Server interface, click LDAP browser.
  3. Expand the LDAP entry select the role which you want to delete.
  4. Open the Options menu and select Delete.
  5. Verify the data about the role you want to delete and click the Next button until you reach the Deletion step.
  6. Toggle the switch to the Yes, I’m sure position and click the Delete button.
  7. To close the wizard window, click the Finish button.

Verification

  • Expand the LDAP entry and verify the role is no longer a part of the entry parameters.

2.4.3. Modifying a role in the LDAP browser

You can modify the role parameters for a Red Hat Directory Server entry by using the LDAP Browser in the web console.

Prerequisites

  • Access to the web console.
  • A parent entry exists in the Red Hat Directory Server.

Procedure

  1. Log in to the web console and click Red Hat Directory Server.
  2. After the web console loads the Red Hat Directory Server interface, click LDAP Browser.
  3. Expand the LDAP entry and select the role you are modifying.
  4. Click the Options menu and select Edit to modify the parameters of the role or Rename to rename the role.
  5. In the wizard window modify the necessary parameters and click Next after each step until you observe the LDIF Statements step.
  6. Check the updated parameters and click Modify Entry or Change Entry Name.
  7. To close the wizard window, click the Finish button.

Verification

  • Expand the LDAP entry and verify the updated parameters are listed for the role.
Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.