Previous     Contents     Index     Next     
iPlanet Directory Server 5.1 Administrator's Guide



Chapter 5   Advanced Entry Management


Beyond the hierarchical structure of data in a directory, managing entries such as users often requires creating groups and sharing common attribute values. iPlanet Directory Server provides this advanced entry management functionality through groups, roles and class of service (CoS).

Groups are entries that name other entries, either as a list of members or as a filter for members. Roles provide the same functionality, and more, through a mechanism that generates the nsrole attribute on each member of a role. CoS also generates a virtual attribute, allowing entries to share a common attribute value without having to store it in each entry.

This chapter describes these grouping mechanisms and their procedures:

To take full advantage of the features offered by roles and class of service, it is best to determine your directory topology in the planning phase of your directory deployment. Refer to the iPlanet Directory Server Deployment Guide for more information.



Managing Groups


Groups are a mechanism for associating entries for ease of administration, such as for defining ACIs. This mechanism was provided with previous versions of Directory Server and should be used primarily for compatibility with older versions of the server. See "Assigning Roles" for procedures that create equivalent role definitions.

The following sections describe how to manage static and dynamic groups. For a conceptual overview of groups, refer to the iPlanet Directory Server Deployment Guide. For more information about administering groups, refer to Managing Servers with Directory Console.

Groups definitions are special entries that either name their members in a static list or give a filter which defines a dynamic set of entries. The scope of possible members of a group is the entire directory, regardless of where the group definition entries are located. To simplify administration, all group definition entries are usually stored in a single location, usually ou=Groups under the root suffix.

The entry that defines a static group inherits from the groupOfUniqueNames object class. The group members are listed by their DN as multiple values of the uniqueMember attribute.

The entry that defines a dynamic group inherits from the groupOfUniqueNames and groupOfURLs object classes. Group membership is defined by the filter given in the memberURL attribute. The members in a dynamic group are the entries that match the filter whenever it is evaluated.

The Entry Editor manages both types of group entries. This dialog allows you to name the group and then create or modify the list or filter of members. This section includes the following procedures for creating and modifying groups:


Adding a New Static Group

  1. In the Directory Server Console, select the Directory tab.

  2. Right-click the entry in the directory tree where you want to add the new group. Select New > Group.

    You can also go to the Object menu and select New > Group.

  3. Click General in the left pane. Type a name for your new group in the "Group Name" field.

    The group name is required.

  4. Enter a description of the new group in the "Description" field.

  5. Click Members in the left pane. In the right pane, select the Static Group tab. Click Add to add new members to the group.

    The standard "Search users and groups" dialog box appears.

  6. In the Search drop-down list, select what sort of entries to search for (users, groups, or both) then click Search. Select one or more of the entries in the results and click OK.


    Note Static group members may be remote due to chaining. You can use the referential integrity plug-in to ensure that deleted member entries are automatically deleted from the static group entry. For more information about using referential integrity with chaining, refer to "Configuring the Chaining Policy," on page 92.


  7. Click Languages in the left pane to add language-specific information for your group.

  8. Click OK to create your new group. It appears as one of the children of the location where it was created.


Adding a New Dynamic Group

  1. Follow steps 1-4 of "Adding a New Static Group".

  2. Click Members in the left pane. In the right pane, select the Dynamic Group tab. Click Add to create a LDAP URL for querying the database.

    The standard "Construct and Test LDAP URL" dialog box is displayed.

  3. Enter an LDAP URL in the text field or select Construct to be guided through the construction of an LDAP URL containing the filter for your group. Click OK when you have constructed the URL.

  4. Click Languages in the left pane to add language-specific information for your group.

  5. Click OK to create your new group.

    Your new group appears in the directory tree.


Modifying a Group Definition

  1. On the Directory Server Console, select the Directory tab.

  2. In the directory tree, double-click the entry representing the group you want to modify or select Open from the Object menu.

    The Edit Entry dialog box appears for the group definition entry.

  3. Make your changes to the group information in the General, Members, or Languages categories. Click OK.

    To view your changes, go to the View menu and select Refresh.


Removing a Group Definition

To remove either type of group, simply delete the entry that defines it.



Assigning Roles


Roles are a new grouping mechanism that are designed to be more efficient and easier to use for applications. Roles are defined and administered like groups, but in addition, member entries also have a generated attribute that indicates the roles in which they participate. For example, an application can simply read the roles of an entry, rather than select a group and browse the members list.

This section contains the following topics:


About Roles

Each role has members, or entries that possess the role. As with groups, you can specify role members either explicitly or dynamically. The roles mechanism automatically generates the nsRole attribute containing the DN of all role definitions in which the entry is a member.

How you specify role membership depends upon the type of role you are using. iPlanet Directory Server supports three types of roles:

  • Managed roles - Explicitly assigns a role to member entries.

  • Filtered roles - Entries are members if they match a specified LDAP filter. In this way, the role depends upon the attributes contained in each entry.

  • Nested roles - Allows you to create roles that contain other roles.

With managed roles, the administrator assigns a given role by adding the nsRoleDN attribute to the participating entries. The value of this attribute is the DN of the role definition entry. A managed role is equivalent to a static group except that membership is defined in each entry and not in the role definition entry.

Filtered roles are equivalent to dynamic groups: they define a filter string in their nsRoleFilter attribute. However, the scope of a filtered role is the subtree in which it is located, rooted at the parent of its definition entry. Whenever the server returns an entry in the scope of a filtered role that matches its filter string, that entry will contain the generated nsRole attribute identifying the role.

The nsRole attribute is a computed attributed that is not stored with the entry itself but which is returned to the client application as a normal attribute in operation results. Evaluating roles is more resource intensive than evaluating groups because the server does the work for the client application. However, the checking role membership is uniform and is performed transparently on the server side.


Note 1. The nsRole attribute may only be used by the roles mechanism and is protected against all modifications. However, it can be read and you may define access controls to protect it against reading.

2. You cannot use the nsRole attribute in a search filter. If you want an application to read the nsRole attribute, you must first perform a search using another filter, then read the value of the nsRole attribute in the entries returned by the search operation.


For more information about how to use roles in your directory, refer to iPlanet Directory Server Deployment Guide.


Role Limitations

When creating roles to support your directory service, you need to be aware of the following limitations:

Roles and chaining. If your directory tree is distributed over several servers using the chaining feature, entries that define roles must be located on the same server as the entries possessing those roles. If one server, A, receives entries from another server, B, through chaining, those entries will contain the roles defined on B, but will not be assigned any of the roles defined on A.

Filtered Roles cannot use CoS generated attributes. The filter string of a filtered role cannot be based on the values of a CoS virtual attribute (see "About CoS"). However, the specifier attribute in a Cos definition may reference the nsRole attribute generated by a role definition (see "Creating Role-Based Attributes").


Managing Roles Using the Console

This section contains the following procedures for creating and modifying roles:

When you create a role, you need to decide whether a user can add themselves or remove themselves from the role. Refer to "Using Roles Securely" for more information about roles and access control.


Creating a Managed Role

Managed roles allow you to create 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:

  1. On the Directory Server Console, select the Directory tab.

  2. Browse the directory tree and select the parent entry for your new role.

  3. Go to the Object menu and select New > Role. You can also right click the entry and select New > Role.

    The Create New Role dialog box is displayed.

  4. Click General in the left pane. Type a name for your new role in the "Role Name" field.

    The role name is required.

  5. Enter a description of the new role in the "Description" field.

  6. Click Members in the left pane.

  7. 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.

  8. 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.

  9. When you have finished adding entries to the role, click OK.

    The new role appears in the directory with the icon for a managed role.


Creating a Filtered Role

You assign entries to a filtered role depending upon a particular attribute contained by each entry. You do this by specifying an LDAP filter. Entries that match the filter are said to possess the role.

To create and add members to a filtered role:

  1. Follow steps 1-5 of "Creating a Managed Role".

  2. Click Members in the left pane.

  3. In the right pane, select Filtered Role.

  4. Enter an LDAP filter in the text field, or click Construct to be guided through the construction of an LDAP filter.

  5. If you click Construct, the standard LDAP URL construction dialog appears. Disregard the LDAP Server Host, Port, Base DN, and Search (as you cannot specify a search scope for filtered role definitions) fields.

    1. Select the types of entries you want to filter from the "For" drop-down list.

      You can choose between users, groups, or both.

    2. Select an attribute from the "Where" drop-down list. The two fields following it allow you to refine your search by selecting one of the qualifiers from the drop-down list (such as contains, does not contain, is, is not) and enter an attribute value in the text box. To add additional filters, click More. To remove unnecessary filters, click Fewer.

    3. Click OK to save your filter.

  6. Click Test to try your filter.

    A Filter Test Result dialog box displays the entries matching your filter.

  7. Click OK.

    The new role appears in the directory with the icon for a filtered role.


Creating a Nested Role

Nested roles allow you to create roles that contain other roles. Before you create a nested role, another role must exist. When you create a nested role, 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:

  1. Follow steps 1-5 of "Creating a Managed Role".

  2. Click Members in the left pane.

  3. In the right pane, select Nested Role.

  4. 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 appears.

  5. Select a role from the "Available roles" list and click OK.

  6. Click OK.

    The new role appears in the directory with the icon for a nested role.


Viewing and Editing an Entry's Roles

  1. In the Directory Server Console, select the Directory tab.

  2. Browse the directory tree and select the entry for which you want to view or edit a role. Select Set Roles from the Object menu.

    The Roles dialog box displays.

  3. Select the Managed Roles tab to display the managed roles to which this entry belongs.

  4. 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 displays. Make any changes to the general information or members and click OK.

  5. Select the Other Roles tab to view what filtered or nested roles this entry belongs to.

  6. Click Edit to make changes to any filtered or nested roles associated with the entry. Click OK to save your changes.

  7. Click OK once you have finished modifying the roles to save your changes.


Modifying a Role Entry

  1. On the Directory Server Console, select the Directory tab.

  2. Browse the navigation tree to locate the definition entry of an existing role. Roles are children of the entry where they were created. Double-click the role.

    The Edit Entry dialog box appears.

  3. Click General in the left pane to change the role name and description.

  4. Click Members in the left pane to change the members of managed and nested roles or to change the filter of a filtered role.

  5. Click OK to save your changes.


Making a Role Inactive

You can temporarily disable the members of a role by inactivating the role to which they belong. Inactivating a role inactivates the entries possessed by the role and not the role itself. If the role member entries represent directory users, they will be unable to access the directory while their entries are inactivated by the role.

To temporarily disable the members of a role:

  1. On the Directory Server Console, select the Directory tab.

  2. Browse the navigation tree to locate the definition entry of your role. Roles are children of the entry where they were created.

  3. Select the role. Select Inactivate from the Object menu.

    You can also right-click the role and select Inactivate from the menu.

    The role is inactivated.

    To see the inactivated entries, select View > Inactivation State from the menu. A red bar through the icons of role members indicates that they have been inactivated.


Reactivating a Role

  1. On the Directory Server Console, select the Directory tab.

  2. Browse the navigation tree to locate the definition entry of your role. Roles are children of the entry where they were created.

  3. Select the role. Select Activate from the Object menu.

    You can also right-click the role and select Activate from the menu.

    The role is reactivated.

    To see inactivated entries, select Inactivation State from the View menu.The role icon appears as normal, indicating that the role is active.


Deleting a Role

Deleting a role deletes only the entry of the role definition, not its members.

To delete a role:

  1. In the Directory Server Console, select the Directory tab.

  2. Browse the navigation tree to locate the definition entry of your role. Roles are children of the entry where they were created.

  3. Right-click the role and select Delete.

    A dialog box appears asking you to confirm the deletion. Click Yes.

  4. The Deleted Entries dialog box appears to inform you that the role was successfully deleted. Click OK.


    Note Deleting a role deletes the role entry but does not delete the nsRoleDN attribute for each role member. To do this, enable the Referential Integrity Plug-In and configure it to manage the nsRoleDN attribute. For more information, see "Maintaining Referential Integrity," on page 70.



Managing Roles Using the Command Line

Roles are defined in entries that the directory administrator may access through command-line utilities. Once you create a role, you assign members 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.

All role definitions inherit from the LDAPsubentry and nsRoleDefinition object classes. The following table lists additional object classes and associated attributes specific to each type of role.




Role Type

Object Classes

Attributes

Managed Role  

nsSimpleRoleDefinition
nsManagedRoleDefinition  

Description (optional)  

Filtered Role  

nsComplexRoleDefinition
nsFilteredRoleDefinition  

nsRoleFilter
Description (optional)  

Nested Role  

nsComplexRoleDefinition
nsNestedRoleDefinition  

nsRoleDN
Description (optional)  


Note In some cases you need to protect the value of the nsRoleDN attribute with an ACI, as the attribute is writable. For more information about security and roles, refer to "Using Roles Securely".



Example of a Managed Role Definition

To create a role that will be assigned to all marketing staff, run the following ldapmodify command:

ldapmodify -a -D "cn=Directory Manager" -w secret -h host -p 389
dn: cn=Marketing,ou=people,dc=siroe,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: nsRoleDefinition
objectclass: nsSimpleRoleDefinition
objectclass: nsManagedRoleDefinition
cn: Marketing
description: managed role for marketing staff

Notice that the nsManagedRoleDefinition object class inherits from the LDAPsubentry, nsRoleDefinition and nsSimpleRoleDefinition object classes.

Assign the role to a marketing staff member named Bob by updating his entry with the following ldapmodify command:

ldapmodify -D "cn=Directory Manager" -w secret -h host -p 389
dn: cn=Bob,ou=people,dc=siroe,dc=com
changetype: modify
add: nsRoleDN
nsRoleDN: cn=Marketing,ou=people,dc=siroe,dc=com

The nsRoleDN attribute present in the entry indicates that the entry is a member of a managed role identified by the DN of its role definition: cn=Marketing,ou=people,dc=siroe,dc=com.


Example of a Filtered Role Definition

To set up a filtered role for sales managers, run the following ldapmodify command:

ldapmodify -a -D "cn=Directory Manager" -w secret -h host -p 389
dn: cn=SalesManagerFilter,ou=people,dc=siroe,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: nsRoleDefinition
objectclass: nsComplexRoleDefinition
objectclass: nsFilteredRoleDefinition
cn: SalesManagerFilter
nsRoleFilter: o=sales managers
Description: filtered role for sales managers

Notice that the nsFilteredRoleDefinition object class inherits from the LDAPsubentry, nsRoleDefinition, and nsComplexRoleDefinition object classes. The nsRoleFilter attribute specifies that all entries in the same subtree with the attribute o (organization) attributes having a value of sales managers will be a member of the role.


Example of a Nested Role Definition

To create a role that contains both the marketing staff and sales manager members of the roles created in the previous examples, use the following ldapmodify command:

ldapmodify -a -D "cn=Directory Manager" -w secret -h host -p 389
dn: cn=MarketingSales,ou=people,dc=siroe,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: nsRoleDefinition
objectclass: nsComplexRoleDefinition
objectclass: nsNestedRoleDefinition
cn: MarketingSales
nsRoleDN: cn=SalesManagerFilter,ou=people,dc=siroe,dc=com
nsRoleDN: cn=Marketing,ou=people,dc=siroe,dc=com

Notice the nsNestedRoleDefinition object class inherits from the LDAPsubentry, nsRoleDefinition, and nsComplexRoleDefinition object classes. The nsRoleDN attributes contain the DN of the marketing managed role and the sales managers filtered role.

Both of the users in the previous examples, Bob and Pat, would be members of this new nested role.


Using Roles Securely

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 easily add themselves to or remove themselves from a role. For example, if you had an interest group role called Mountain Biking, you would want interested users to add themselves or remove themselves easily.

However, in some security contexts it is inappropriate to have such open roles. For example, consider account inactivation roles. By default, account inactivation roles contain ACIs defined for their suffix (for more information about account inactivation, see "Inactivating Users and Roles," on page 269). 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 through the command line. 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=siroe,dc=com)),
 del=nsRoleDN:(!(nsRoleDN=cn=nsManagedDisabledRole,dc=siroe,dc=com)
     ")
     (version3.0;aci "allow mod of nsRoleDN by self
        except for 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, and 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.



Defining Class of Service (CoS)


The Class of Service (CoS) mechanism allows you to create virtual attributes not stored in the entries. Instead, they are generated by the CoS mechanism as the entry is sent to the client application. CoS simplifies entry management and reduces storage requirements.

As with groups and roles, CoS relies on helper entries in your directory and may be configured through the console or through the command line. The following sections describe CoS and provide the procedures for managing CoS in both ways:


About CoS

A CoS defines a virtual attribute and its value for all of its target entries, any entry within the scope of the CoS. Each CoS is comprised of the following entries in your directory:

  • CoS Definition Entry - Identifies the type of CoS you are using and the name of the CoS attribute that will be generated. Like the role definition entry, it inherits from the LDAPsubentry object class. The scope of the CoS is the entire subtree below the parent of the CoS definition entry. Multiple definitions may exist for the same CoS attribute which may therefore be multivalued.

  • Template Entry - Contains the values of one or more virtual attributes. All entries within the scope of the CoS will use the values defined here. There may be multiple template entries in which case the generated attribute may be multivalued.

There are three types of CoS, each of which corresponds to a different interaction between the CoS definition and template entries:

  • Pointer CoS - The CoS definition entry directly identifies the template entry by its DN. All target entries will have the same value for the CoS attribute as given in the template.

  • Indirect CoS - The CoS definition identifies an attribute, called the indirect specifier, whose value in a target entry determines the template used for that entry. That attribute in the target entry must contain a DN. With indirect CoS, each target entry may use a different template and thus have a different value for the CoS attribute.

  • Classic CoS - The CoS definition identifies the base DN of the template and a specifier, which is the name of an attribute in target entries. The template containing the CoS values is determined by the combination of the RDN (relative domain name) value of the specifier attribute in the target and the template's base DN.


    Note The server does not support LDAP search requests containing a filter that references CoS virtual attributes. Only actual attributes stored in entries, which does not include CoS or nsRole attributes, are supported in LDAP search filters. Take care when deciding which attributes to generate using CoS definitions.

    To find entries based on the values of virtual attribute, a directory client must retrieve a superset of the entries, such as an entire branch, and sort through them to select the entries of interest.


The following sections describe the CoS definition and template entries in more detail and provide examples of each type of CoS.


The CoS Definition and Template Entries

The CoS definition entry is an instance of the cosSuperDefinition object class. The CoS definition entry also inherits from one of the following object classes to specify the type of CoS:

  • cosPointerDefinition

  • cosIndirectDefinition

  • cosClassicDefinition

The CoS definition entry contains the attributes specific to each type of CoS for naming the virtual CoS attribute, the template DN, and the specifier attribute in target entries, if needed. By default, the CoS mechanism will not override the value of an existing attribute with the same name as the CoS attribute. However, the syntax of the CoS definition entry allows you to control this behavior.

The CoS template entry is an instance of the cosTemplate object class. The CoS template entry contains the value or values of the attributes generated by the CoS mechanism. The template entries for a given CoS are stored in the directory tree at the same level as the CoS definition.

When possible, definition and template and template entries should be located in the same place for easier management. Also, you should name them in a way that suggests the functionality they provide. For example, a definition entry DN such as "cn=classicCosGenerateEmployeeType,ou=People,dc=siroe,dc=com" is more descriptive than "cn=ClassicCos1,ou=People,dc=siroe,dc=com".

For more information about the object classes and attributes associated with each type of CoS, refer to "Managing CoS From the Command Line".


Pointer CoS Example

This example shows a CoS that defines a common postal code for all of the entries stored under dc=siroe,dc=com. The three entries for this example are shown in the following diagram:

Figure 5-1    Example of a Pointer CoS Definition and Template

The template entry is identified by its DN, cn=siroeUS,cn=data, in the CoS definition entry. Each time the postalCode attribute is queried on entries under dc=siroe,dc=com, the Directory Server returns the value available in the template entry cn=siroeUS,cn=data. Therefore, the postal code will appear with the entry uid=wholiday,ou=people,dc=siroe,dc=com, but it is not stored there. This mechanism can save significant storage space when several shared attributes are generated by CoS for thousands or millions of entries.


Indirect CoS Example

This example of an indirect CoS uses the manager attribute of the target entry to identify the template entry. In this way, the CoS mechanism can generate the department number of all employees to be the same as their manager's, insuring that it is always up to date. The three entries for this example are shown in the following diagram:

Figure 5-2    Example of an Indirect CoS Definition and Template

The indirect CoS definition entry names the specifier attribute, which in this example, is the manager attribute. William Holiday's entry is one of the target entries of this CoS, and his manager attribute contains the DN of cn=Carla Fuentes,ou=people,dc=siroe,dc=com. Therefore, Carla Fuentes's entry is the template, which in turn provides the departmentNumber attribute value of 318842.

Through the indirect specifier, an indirect CoS can use any entry in the directory as its template. For both security and performance reasons, you should use this type of CoS with care. In many cases, you can achieve the same result by limiting the location of the target entries with classic CoS or using the less flexible pointer CoS mechanism.


Classic CoS Example

The classic CoS mechanism determines the DN of the template from the base DN given in the definition entry and the specifier in the target entry. The value of the specifier attribute will be taken as the cn value in the template DN. Template DNs for classic CoS must therefore have the following structure:

cn=specifierValue,baseDN

The example in the following diagram shows a classic CoS definition that generates a value for the postal code:

Figure 5-3    Example of a Classic CoS Definition and Template

In this example, the Cos definition entry's cosSpecifier attribute names the employeeType attribute. The combination of this attribute and the template DN identifies the template entry as cn=sales,cn=siroeUS,cn=data. The template entry then provides the value of the postalCode attribute to the target entry.


CoS Limitations

The CoS functionality is a complex mechanism which, for performance and security reasons, is subject to the following limitations.

Restricted subtrees. You cannot create CoS definitions in the cn=config nor in the cn=schema subtrees. Therefore, these entries cannot contain virtual attributes.

Restricted attribute types. The following attribute types should not be generated by the CoS mechanism because they will not have the same behavior as real attributes of the same name:

  • userPassword - A CoS-generated password value cannot be used to bind to the directory server.

  • aci - The directory server will not apply any access control based on the contents of a virtual ACI value defined by CoS.

  • objectclass - The directory server will not perform schema checking on the value of a virtual object class defined by CoS.

  • nsRoleDN - A CoS-generated nsRoleDN value will not be used by the server to generate roles.

All templates must be local - The DNs of template entries, either in a CoS definition or in the specifier of the target entry, must refer to local entries in the directory server. Templates and the values they contain cannot be retrieved through directory chaining or referrals.

CoS virtual values are not combined with real values. The values of a CoS attribute are never a combination of real values from the entry and virtual values from the templates. When the CoS overrides a real attribute value, it replaces all real values with those from the templates (see "Overriding Real Attribute Values"). However, the CoS mechanism can combine virtual values from several CoS definition entries as described in "Multivalued CoS Attributes".

Filtered Roles cannot use CoS generated attributes. The filter string of a filtered role cannot be based on the values of a CoS virtual attribute. However, the specifier attribute in a Cos definition may reference the nsRole attribute generated by a role definition (see "Creating Role-Based Attributes").

Access Control Instructions (ACIs). The server controls access to attributes generated by a CoS in exactly the same way as regular, stored attributes. However, access control rules that depend on the value of attributes generated by CoS are subject to the conditions described in "CoS Limitations".

CoS Cache Latency. The CoS cache is an internal Directory Server structure which keeps all CoS data in memory to improve performance. This cache is optimized for retrieving CoS data to be used in computing virtual attributes, even while CoS definition and template entries are being updated. Therefore, once definition and template entries have been added or modified, there may be a slight delay before they are taken into account. This delay depends upon the number and complexity of CoS definitions, as well as the current server load, but it is usually on the order of a few seconds.


Managing CoS Using the Console

This section describes how to create and edit CoS definitions through the Directory Server Console. It includes the following sections:


Creating a New CoS

In the case of pointer CoS and classic CoS, you must create the template entry before the definition entry:

  1. In the Directory Server Console, select the Directory tab.

  2. Browse the directory tree and select the parent entry under which you wish to store the template entry.

  3. From the Object menu or the right-click context menu, select New > Other, and then select costemplate from the list in the New Object dialog.

    The Property Editor dialog opens with default values for certain attributes in the new template.

  4. Edit the new template object in the following manner:

    1. Add the LDAPsubentry and extensibleobject values to the objectclass attribute.

    2. Add the cn attribute and give it a value that will identify the template, for example, cosTemplateForHeadquartersFax.

    3. Change the naming attribute to the new cn attribute.

      You may add any other attribute and use it as the naming attribute instead, but using cn is common practice.

    4. Modify the cosPriority attribute by setting it to an integer value, or remove the priority attribute altogether if it is not needed.

    5. Add the attribute and its value that you wish to be generated on target entries by the CoS mechanism.

  5. Click OK in the Property Editor dialog to create the template entry.

  6. If you are going to define a pointer CoS for this template, select the new template entry in directory tree and select Edit > Copy DN from the menu.

The procedure for creating the definition entry is the same for all types of CoS:

  1. Browse the directory tree and select the parent entry under which you wish the new Class of Service to take effect.

  2. From the Object menu or the right-click context menu, select New > Class of Service.

    The Create New Class of Service dialog is displayed.

  3. Select General in the left pane. In the right pane, enter the name of your new Class of Service in the "Class Name" field. The name will appear in the cn naming attribute for the CoS definition entry. Enter a description of the class in the "Description" field.

  4. Click Attributes in the left pane. The right pane displays the list of attributes that will be generated by the CoS mechanism on the target entries.

    Click Add to browse the list of possible attributes and add them to the list.

  5. Once you have added an attribute to the list, the "Class of Service Behavior" column contains a drop-down list. Click in this cell to select the override behavior:

    • Does not override target entry attribute - The CoS attribute value will be generated only if there is no corresponding attribute value already stored in the same attribute of the target entry.

    • Overrides target entry attribute - The value of the attribute generated by the CoS will override any value for that attribute in the target entry.

    • Overrides target entry attribute and is operational - The attribute will override any target value and be an attribute operational, so that it is not visible to client applications unless explicitly requested.


      Note You can only make an attribute operational if it is also defined as operational in the schema.


  6. Click Template in the left pane. In the right pane, select how the template entry is identified and then fill in the corresponding fields. This will determine the type of CoS you wish to define.

    • By its DN - This choice will define a pointer CoS: enter the DN of a template entry in the "Template DN" field. Click Browse to select the template DN from the directory, or type Ctrl-V to paste the DN that you copied after creating the template entry.

    • Using the value of one of the target entry's attributes - This choice will define an indirect CoS: enter the name of the specifier attribute in the "Attribute Name" field. Be sure to select an attribute which contains DN values. Click Change to select the attribute from a list.

    • Using both its DN and the value of one of the target entry's attributes - This choice will define a classic CoS: enter both the base DN for a template and an attribute name. Click Browse to select the parent entry of the potential target entries, and click Change to select the attribute from a list.

  7. Click OK to create the CoS definition entry.


Editing an Existing CoS

  1. In the Directory Server Console, select the Directory tab.

  2. Browse the directory tree and select the parent entry that contains your CoS definitions. The CoS entries appears as children of this parent entry.

  3. Double-click the CoS.

    The Edit Entry dialog box appears.

  4. Click General in the left pane to change the CoS name and description.

  5. Click Attributes in the left pane to add or remove virtual attributes that will be generated by the CoS mechanism.

  6. Click Template in the left pane to redefine the name of the template specifier attribute or the template entry DN. This dialog also allows you to redefine the type of your CoS definition.

  7. Click OK to save your changes.


Deleting a CoS

  1. In the Directory Server Console, select the Directory tab.

  2. Browse the directory tree and select the parent entry that contains your CoS definitions. The CoS entries appears as children of this parent entry.

  3. Right-click the CoS and select Delete. A dialog box appears asking you to confirm the deletion. Click Yes.

  4. The Deleted Entries dialog box appears to inform you that the CoS was successfully deleted. Click OK.


Managing CoS From the Command Line

Because all configuration information and template data is stored as entries in the directory, you can use standard LDAP tools for CoS configuration and management. This section contains the following topics:


Creating the CoS Definition Entry From the Command Line

All CoS definition entries inherit from the LDAPsubentry object class and the cosSuperDefinition object class. In addition, each type of CoS inherits from specific object classes and contains the corresponding attributes. The following table lists the object classes and attributes associated with each type of CoS definition entry:


Table 5-1    CoS Definition Entries

CoS Type

CoS Definition Entry

Pointer CoS

 

objectclass: top
objectclass: LDAPsubentry
objectclass: cosSuperDefinition
objectclass: cosPointerDefinition
cosTemplateDN: DN_string
cosAttribute: list_of_attributes qualifier  
Indirect CoS

 

objectclass: top
objectclass: LDAPsubentry
objectclass: cosSuperDefinition
objectclass: cosIndirectDefinition
cosIndirectSpecifier: attribute_name
cosAttribute: list_of_attributes qualifier  
Classic CoS

 

objectclass: top
bbjectclass: LDAPsubentry
objectclass: cosSuperDefinition
objectclass: cosClassicDefinition
cosTemplateDn: DN_string
cosSpecifier: attribute_name
cosAttribute: list_of_attributes qualifier  

You can use the following attributes in your CoS definition entries (for more information about these attributes, refer to the iPlanet Directory Server Configuration, Command, and File Reference.):


Table 5-2    CoS Definition Entry Attributes

Attribute

Purpose Within the CoS Definition Entry

cosAttribute:
 attribute_name override merge  

Defines the name of the virtual attribute for which you want to generate a value. This attribute is multivalued, each value giving the name of an attribute whose value will be generated from the template. The qualifiers specify how the CoS attribute value is computed in special cases.  

cosIndirectSpecifier:
 attribute_name  

Defines the name of the attribute in target entries whose value is used by indirect CoS to identify the template entry. The named attribute is called the specifier and must contain a full DN string in each target entry. This attribute is single-valued but the specifier attribute may be multivalued to designate multiple templates.  

cosSpecifier:
 attribute_name  

Defines the name of the attribute in target entries whose value is used by classic CoS to identify the template entry. The named attribute is called the specifier and must contain a string that can be found in the RDN of template entries. This attribute is single-valued but the specifier attribute may be multivalued to designate multiple templates.  

cosTemplateDn:
 DN_string  

Provides the full DN of the template entry for a pointer CoS definition or the base DN of the template entry for classic CoS.  

The cosAttribute attribute allows two qualifiers following the name of the CoS attribute. The override qualifier has one of the following values:

  • default (or no qualifier) - Indicates that the server does not override a real attribute value stored in the entry when it has the same type as the virtual attribute.

  • override - Indicates that the server always returns the value generated by the CoS, even when there is a value stored with the entry.

  • operational - Indicates that the attribute will only be returned if it is explicitly requested in the search. Operational attributes do not need to pass a schema check in order to be returned. It also has the same behavior as the override qualifier.

    You can only make an attribute operational if it is also defined as operational in the schema. For example, if your CoS generates a value for the description attribute, you cannot use the operational qualifier because this attribute is not marked operational in the schema.

The merge qualifier is either absent or given with the following value:

  • merge-schemes - Allows the virtual CoS attribute to be multivalued, either from multiple templates or multiple CoS definitions. For more information, see "Multivalued CoS Attributes".


Overriding Real Attribute Values
You might create a pointer CoS definition entry that contains an override qualifier as follows:

dn: cn=pointerCoS,dc=siroe,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: cosSuperDefinition
objectclass: cosPointerDefinition
cosTemplateDn: cn=siroeUS,cn=data
cosAttribute: postalCode override

This pointer CoS definition entry indicates that it is associated with the template entry cn=siroeUS,cn=data that generates the value of the postalCode attribute. The override qualifier indicates that this value will take precedence over the value of the postalCode attribute if it exists in a target entry.


Note If the CoS attribute is defined with the operational or override qualifiers, you will not be able to manually update that attribute in any entry in the CoS scope where it is also present as a regular attribute.



Multivalued CoS Attributes
When you specify the merge-schemes qualifier, the generated CoS attribute may be multivalued. There are two ways for a CoS attribute to be multivalued:

  • With indirect or classic CoS, the specifier attributes in target entries may be multivalued. In this case, each value determines a template and the value from each template is part of the generated value.

  • There can be multiple CoS definition entries of any type containing the same attribute name in their cosAttribute. In this case, if all definitions contain the merge-schemes qualifier, the generated attribute will contain all values computed by each definition.

The two situations may occur together and define even more values. However, in all cases, duplicate values will only be returned once in generated attribute.

In the absence of the merge-schemes qualifier, the cosPriority attribute of the template entry will be used to determine a single value among all templates for the generated attribute, as described in the next section.

The merge-schemes qualifier never merges a "real" value defined in the target with generated values from the templates. The merge qualifier is independent of the override qualifier, all pairings are possible and the behaviors implied by each are complimentary. Also, the qualifiers may be specified in any order after the attribute name.


Note When there are multiple CoS definitions for the same attribute, they must all have the same override and merge qualifiers. When different pairs of qualifiers occur in CoS definitions, one of the combinations is selected arbitrarily among all definitions.



Cos Attribute Priority
If there are multiple CoS definitions or multivalued specifiers, but no merge-schemes qualifier the Directory Server uses a priority attribute to select a single template that defines the single value of the virtual attribute.

The cosPriority attribute represents the global priority of a particular template among all those being considered. A priority of zero is the highest priority. Templates that contain no cosPriority attribute are considered the lowest priority. When two or more templates provide an attribute value but have the same (or no) priority, a value is chosen arbitrarily.

Template priorities are not taken into account when using the merge-schemes qualifier. When merging, all templates being considered define a value regardless of any priority they define. The cosPriority attribute is defined on CoS template entries described in the following section.


Creating the CoS Template Entry From the Command Line

When using pointer CoS or classic CoS, the template entry inherits from the LDAPsubentry object class and is also an instance of the cosTemplate object class. This entry must be created specifically for the CoS definition. Making the CoS template entry an instance of the LDAPsubentry object classes allows ordinary searches to be performed unhindered by the configuration entries.

The indirect CoS mechanism refers to an arbitrary, existing template entry in the directory. It does not need to be identified ahead of time nor given the LDAPsubentry object class. The indirect CoS template is accessed only when the CoS is evaluated to generate a virtual attribute and its value.

In all cases, the CoS template entry must contain the attribute and the value that is generated by the CoS on the target entries. The attribute name is specified in the cosAttribute attribute of the CoS definition entry.

The following example shows a template entry of the highest priority for a pointer CoS that generates the postalCode attribute follows:

dn: cn=siroeUS,cn=data,dc=siroe,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: extensibleobject
objectclass: cosTemplate
postalCode: 44438
cosPriority: 0

The following sections provide examples of template entries along with examples of each type of CoS definition entry.


Example of a Pointer CoS

To create a pointer CoS that shares a common postal code with all entries in the dc=siroe,dc=com tree, run the following ldapmodify command:

ldapmodify -a -D "cn=directory manager" -w secret -h host -p 389

dn: cn=pointerCoS,dc=siroe,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: cosSuperDefinition
objectclass: cosPointerDefinition
cosTemplateDn: cn=siroeUS,cn=data,dc=siroe,dc=com
cosAttribute: postalCode

dn: cn=siroeUS,cn=data,dc=siroe,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: extensibleobject
objectclass: cosTemplate
postalCode: 44438

The CoS template entry (cn=siroeUS,dn=cata,dc=siroe,dc=com) supplies the value stored in its postalCode attribute to all entries located under the dc=siroe,dc=com suffix.


Example of an Indirect CoS

This indirect CoS uses the team attribute of the target entry to identify the CoS template entry. To add a new indirect CoS definition entry to the dc=siroe,dc=com suffix, run the following ldapmodify command:

ldapmodify -a -D "cn=directory manager" -w secret -h host -p 389

dn: cn=indirectCoS,dc=siroe,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: cosSuperDefinition
objectclass: cosIndirectDefinition
cosIndirectSpecifier: manager
cosAttribute: departmentNumber

Next, create the template entry for the manager Carla Fuentes as follows:

dn:cn=Carla Fuentes,cn=data,dc=siroe,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: extensibleobject
objectclass: cosTemplate
departmentNumber: 318842

Create a second template entry for the manager Sue Jacobs as follows:

dn:cn=Sue Jacobs,cn=data,dc=siroe,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: extensibleobject
objectclass: cosTemplate
departmentNumber: 71776

The definition entry looks in the target entries (the entries under dc=siroe,dc=com) for entries containing the manager attribute (because this attribute is specified in the cosIndirectSpecifier attribute of the definition entry). The manager attribute of the target entry can point to one of two templates, cn=Carla Fuentes,cn=data,dc=siroe,dc=com and cn=Sue Jacobs,cn=data,dc=siroe,dc=com. The department number is different depending upon the manager.


Example of a Classic CoS

This example of a classic CoS automatically generates postal codes using a combination of the template DN and the attribute specified in the cosSpecifier attribute. To create the classic CoS definition entry, run the following ldapmodify command:

ldapmodify -a -D "cn=directory manager" -w secret -h host -p 389

dn: cn=classicCoS,dc=siroe,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: cosSuperDefinition
objectclass: cosClassicDefinition
cosTemplateDn: cn=siroeUS,cn=data,dc=siroe,dc=com
cosSpecifier: employeeType
cosAttribute: postalCode override

Next, create the template entries for the sales and marketing departments as follows:

dn: cn=sales,cn=siroeUS,cn=data,dc=siroe,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: extensibleobject
objectclass: cosTemplate
postalCode: 44438

dn: cn=marketing,cn=siroeUS,cn=data,dc=siroe,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: extensibleobject
objectclass: cosTemplate
postalCode: 99111

The classic CoS definition entry applies to all entries under the dc=siroe,dc=com suffix. Depending upon the combination of employeeType attribute found in the entry and the cosTemplate DN, it can arrive at one of two templates. One, the sales template, provides a postal code specific to employees in the sales department. The marketing template provides a postal code specific to employees in the marketing department.


Creating Role-Based Attributes

You can create classic CoS schemes that generate attribute values for an entry based on the role possessed by the entry. For example, you could use role-based attributes to set the server look through limit on an entry-by-entry basis.

To create a role-based attribute, use the nsRole attribute as the cosSpecifier in the CoS definition entry of a classic CoS. Because the nsRole attribute can be multivalued, you can define CoS schemes that have more than one possible template entry. To resolve the ambiguity of which template entry to use, you can include the cosPriority attribute in your CoS template entry.

For example, you can create a CoS that allows members of the manager role to exceed the standard mailbox quota. The manager role exists as follows:

dn: cn=ManagerRole,ou=people,dc=siroe,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: nsRoleDefinition
objectclass: nsComplexRoleDefinition
objectclass: nsFilteredRoleDefinition
cn: ManagerRole
nsRoleFilter: o=managers
Description: filtered role for managers

The classic CoS definition entry would look as follows:

dn: cn=managerCOS,dc=siroe,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: cosSuperDefinition
objectlass: cosClassicDefinition
cosTemplateDn: cn=managerCOS,dc=siroe,dc=com
cosSpecifier: nsRole
cosAttribute: mailboxquota override

The cosTemplateDn attribute provides a value that, in combination with the attribute specified in the cosSpecifier attribute (in the example, the nsRole attribute of the target entry), identifies the CoS template entry. The CoS template entry provides the value for the mailboxquota attribute. An additional qualifier of override tells the CoS to override any existing mailboxquota attributes values in the target entry.

The corresponding CoS template entry is defined as follows:

dn:cn="cn=ManagerRole,ou=people,dc=siroe,dc=com",cn=managerCOS,
 dc=siroe,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: extensibleobject
objectlass: cosTemplate
mailboxquota: 1000000

The template provides the value for the mailboxquota attribute, 1000000.


Note The role entry and the CoS definition entry should be located in the same place in the directory tree so that they have the same target entries in their scope. The CoS target entry should also be located in the same place so that it is easy to find and maintain.



Making CoS Secure

Access control for reading applies to both the real and virtual attributes of an entry. A virtual attribute generated by the Class of Service mechanism is read just as a normal attribute and should be given read protection in the same way.

However, in order to make the CoS value secure, you must protect all of the sources of information it uses: the definition entries, the template entries, and the target entries. The same is true for update operations: write access to each source of information should be controlled to protect the value that is generated from them.

The following sections describe the general principals for read and write protection of data in each of the CoS entries. The detailed procedures for defining individual access control instructions (ACIs) is described in Chapter 6, "Managing Access Control."


Protecting the CoS Definition Entry

Even though the CoS definition entry does not contain the value of the generated attribute, it provides the information to find that value. Reading the CoS definition entry would reveal how to find the template entry containing the value, and writing this entry would modify how the virtual attribute is generated.

You should therefore define both read and write access control on the CoS definition entries.


Protecting the CoS Template Entries

The CoS template entry contains the value of the generated CoS attribute. Therefore, as a minimum, the CoS attribute in the template should be protected for both reading and updating.

In the case of pointer CoS, there is a single template entry which should not be allowed to be renamed. In most cases, it is simplest to protect the entire template entry.

With classic CoS, all template entries have a common parent given in the definition entry. If only templates are stored in this parent entry, access control to the parent will protect the templates. Otherwise, if other entries beneath the parent require access, the template entries will need to be protected individually.

In the case of indirect CoS, the template may be any entry in the directory, including user entries that might still need to be accessed. Depending on your needs, you may either control access to the CoS attribute throughout the directory, or you must insure that the CoS attribute is secure in each entry used as a template.


Protecting the Target Entries of a CoS

All entries in the scope of a CoS definition, for which the virtual CoS attribute will be generated, also contribute to computing its value.

When the CoS attribute already exists in a target entry, by default, the CoS mechanism will not override this value. If you do not want this behavior, you should either define your CoS to override the target entry (see "Overriding Real Attribute Values") or protect the CoS attribute in all potential target entries.

Both indirect and classic CoS also rely on a specifier attribute in the target entry. This attribute gives the DN or RDN of the template entry to use. You should protect this attribute either globally throughout the scope of the CoS or individually on each target entry where needed.


Protecting Other Dependencies

Finally, it is possible to define virtual CoS attributes in terms of other generated CoS attributes and roles. You will need to understand and protect these dependencies in order to guarantee the protection of your virtual CoS attribute.

For example, the CoS specifier attribute in a target entry could be nsRole, and therefore the role definition would also need to be protected. For more information, see "Using Roles Securely".

In general, any attribute or entry which is involved in the computation of the virtual attribute value should have both read and write access control. For this reason, complex dependencies should be well planned or simplified to reduce complexity. Keeping dependencies on other virtual attributes to a minimum also improves directory performance and reduces maintenance.


Previous     Contents     Index     Next     
Copyright © 2001 Sun Microsystems, Inc. Some preexisting portions Copyright © 2001 Netscape Communications Corp. All rights reserved.

Last Updated October 29, 2001