Sun Java System Directory Server Enterprise Edition 6.0 Administration Guide

Chapter 9 Directory Server Groups, Roles, and CoS

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

This chapter covers the following topics:

About Groups, Roles, and Class of Service

Groups, roles, and CoS are defined as follows:

Directory Server provides the ability to perform searches that are based on the values of the roles, and groups and the CoS computed attributes. Filter strings used in any operation can include the nsRole attribute or any attribute generated by a CoS definition. Filter strings can also be used to perform any of the comparison operations on the value of this attribute. However, computed CoS attributes cannot be indexed. Therefore, any search that involves a CoS-generated attribute might consume a large amount of resources in terms of time and memory.

To take full advantage of the features offered by roles, groups, and class of service, determine your directory topology in the planning phase of your directory deployment. Refer to Grouping Directory Entries and Managing Attributes in Sun Java System Directory Server Enterprise Edition 6.0 Deployment Planning Guide for a description of these features and how they can simplify your topology.

To gain a deeper understanding of how roles and groups work, see Chapter 8, Directory Server Groups and Roles, in Sun Java System Directory Server Enterprise Edition 6.0 Reference. For a detailed description of CoS, see Chapter 9, Directory Server Class of Service, in Sun Java System Directory Server Enterprise Edition 6.0 Reference.

Managing Groups

Groups enable you to associate entries for ease of administration. For example, using groups makes it easier to define access control instructions (ACIs). Group definitions are special entries that either name their members in a static list or provide a filter that 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 two types of groups are static groups and dynamic groups.

ProcedureTo Create a New Static Group

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

  1. Create a new static group using the ldapmodify command.

    For example, to create a new static group called System Administrators and to add some members, you could use this command:


    $ ldapmodify -a -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w -
    dn: cn=System Administrators, ou=Groups, dc=example,dc=com
    cn: System Administrators
    objectclass: top
    objectclass: groupOfNames
    ou: Groups
    member: uid=kvaughan, ou=People, dc=example,dc=com
    member: uid=rdaugherty, ou=People, dc=example,dc=com
    member: uid=hmiller, ou=People, dc=example,dc=com
  2. Check to see that the new group has been created and that the members have been added.

    For example, to check that Kirsten Vaughan is in the new System Administrators group, type:


    $ ldapsearch -b "dc=example,dc=com" uid=kvaughan isMemberOf
    uid=kvaughan,ou=People,dc=example,dc=com
    isMemberOf: cn=System Administrators, ou=Groups, dc=example,dc=com 
    isMemberOf: cn=HR Managers,ou=groups,dc=example,dc=com

ProcedureTo Create a New Dynamic Group

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

    Create a new dynamic group by using the ldapmodify command.

    For example, to create a new dynamic group called Database Administrators and to add members with the surname Jensen, you could use this command:


    $ ldapmodify -a -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w -
    dn: cn=Database Administrators, ou=Groups, dc=example,dc=com
    cn: Database  Administrators
    objectclass: top
    objectclass: groupOfUrls
    ou: Groups
    memberURL: ldap:///dc=example,dc=com??sub?(sn=Jensen)

Managing Roles

A role is an alternate grouping mechanism that is designed to be more efficient and easier for applications to use. While roles are defined and administered like groups, a generated role attribute in each member entry automatically indicates the roles of an entry. For example, an application can read the roles of an entry, rather than having to select a group and browse the members list.

By default, the scope of a role is limited to the subtree where the scope is defined. However, you can extend scoping of the nested role. You can allow the scope to nest roles located in other subtrees and to have members anywhere in the directory. For details see To Extend the Scope of a Role and Example of a Nested Role Definition.

This section explains how to use roles securely, and how to manage roles from the command line.

Using Roles Securely

To use roles securely, you must set access control instructions (ACIs) to protect appropriate attributes. For example, user A possesses the managed role, MR. Managed roles are equivalent to static groups, and explicitly assign a role to each member entry by adding the nsRoleDN attribute to the entry. 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 no ACI exists to prevent the user from having write access to the nsRoleDN attribute, the user can remove the nsRoleDN attribute from his own entry and unlock himself.

To prevent users from removing the nsRoleDN attribute, you must apply ACIs. With filtered roles, you must protect the part of the filter that would prevent the user from being able to relinquish the filtered role by modifying an attribute. Users should not be allowed to add, delete, or modify the attribute used by the filtered role. In the same way, if the value of the filter attribute is computed, all the attributes that can modify the value of the filter attribute need to be protected. As nested roles can contain filtered and managed roles, the preceding points should be considered for each of the roles that are contained in the nested role.

For detailed instructions on setting ACIs for security, see Chapter 6, Directory Server Access Control.

Managing Roles From the Command Line

Roles are defined in entries that the Directory Administrator can access through command-line utilities. After you create a role, you assign members to the role as follows:

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

Example of a Managed Role Definition

To create a role for all marketing staff, use the following ldapmodify command:


$ ldapmodify -a -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w -
dn: cn=Marketing,ou=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

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

Assign the role to a marketing staff member who is named Bob by updating his entry as follows:


$ ldapmodify -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w -
dn: cn=Bob Arnold,ou=marketing,ou=People,dc=example,dc=com
changetype: modify
add: nsRoleDN
nsRoleDN: cn=Marketing,ou=marketing,ou=People,dc=example,dc=com

The nsRoleDN attribute indicates that the entry is a member of a managed role. The managed role is identified by the DN of its role definition. To allow users to modify their own nsRoleDN attribute, but to prevent users from adding or removing the nsManagedDisabledRole, add 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;aci "allow mod of nsRoleDN by self except for critical values"; 
allow(write) userdn="ldap:///self";)

Example of a Filtered Role Definition

To set up a filtered role for sales managers, assuming that they all have the isManager attribute, use the following ldapmodify command:


$ ldapmodify -a -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w -
dn: cn=ManagerFilter,ou=sales,ou=People,dc=example,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: nsRoleDefinition
objectclass: nsComplexRoleDefinition
objectclass: nsFilteredRoleDefinition
cn: ManagerFilter 
nsRoleFilter: (isManager=True)
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 a filter that finds all employees in the ou=sales organization that have subordinates, for example:


$ ldapsearch -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w - \
 -b "ou=People,dc=example,dc=com" -s sub "(cn=*Fuentes)"
dn: cn=Carla Fuentes,ou=sales,ou=People,dc=example,dc=comcn: Carla Fuentes 
isManager: TRUE...
nsRole: cn=ManagerFilter,ou=sales,ou=People,
dc=example,dc=com

Note –

The filter string of a filtered role can be based on any attribute, except computed attributes that are generated by the CoS mechanism.


When filtered role members are user entries, you can choose to restrict their ability to add or remove themselves from the role. Protect the filtered attributes with ACIs.

Example of a Nested Role Definition

The roles that are nested within the nested role are specified by using the nsRoleDN attribute. Use the following command to create a role that contains both the marketing staff and sales manager members of the roles created in the previous examples:


$ ldapmodify -a -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w -
dn: cn=MarketingSales,ou=marketing,ou=People,dc=example,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: nsRoleDefinition
objectclass: nsComplexRoleDefinition
objectclass: nsNestedRoleDefinition
cn: MarketingSales
nsRoleDN: cn=ManagerFilter,ou=sales,ou=People,dc=example,dc=com
nsRoleDN: cn=Marketing,ou=marketing,ou=People,dc=example,dc=com
nsRoleScopeDN: ou=sales,ou=People,dc=example,dc=com

Notice that 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 Carla, would be members of this new nested role.

The scope of this filter includes the default scope, which is the subtree where the filter is located, and the subtree below any values of the nsRoleScopeDN attribute. In this case, the ManagerFilter is in the ou=sales,ou=People,dc=example,dc=com subtree. This subtree must be added to the scope.

Extending the Scope of a Role

Directory Server provides an attribute that allows the scope of a role to be extended beyond the subtree of the role definition entry. This single-valued attribute, nsRoleScopeDN, contains the DN of the scope to be added to an existing role. The nsRoleScopeDN attribute can only be added to a nested role. See Example of a Nested Role Definition.

ProcedureTo Extend the Scope of a Role

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

The nsRoleScopeDN attribute enables you to extend the scope of a role in one subtree to include an entry in another subtree. For example, imagine two main subtrees in the example.com directory tree: o=eng,dc=example,dc=com ( the engineering subtree) and o=sales,dc=example,dc=com (the sales subtree.) A user in the engineering subtree requires access to a sales application governed by a role in the sales subtree (SalesAppManagedRole). To extend the scope of the role, do the following:

  1. Create a role for the user in the engineering subtree.

    For example, create the role EngineerManagedRole. This example uses a managed role, but it could just as well have been a filtered or nested role.

  2. Create a nested role, for example, SalesAppPlusEngNestedRole , in the sales subtree to house the newly created EngineerManagedRole and the initial SalesAppManagedRole .

  3. Add the nsRoleScopeDN attribute to the SalesAppPlusEngNestedRole, with the DN of the engineering subtree scope that you want to add, in this case, o=eng,dc=example,dc=com.

    The necessary permissions must be granted to the engineering user so that he can access the SalesAppPlusEngNestedRole role and, in turn, the sales application. In addition, the entire scope of the role must be replicated.


    Note –

    The restriction of extended scope to nested roles means that an administrator who previously managed roles in one domain only has rights to use the roles that already exist in the other domain. The administrator is not able to create an arbitrary role in the other domain.


Class of Service

The class of service (CoS) mechanism generates computed attributes as an entry is retrieved for a client application, which simplifies entry management and reduces storage requirements. The CoS mechanism allows attributes to be shared between entries, and as with groups and roles, CoS relies on helper entries.

For an explanation of how you can use CoS in your deployment, see Managing Attributes With Class of Service in Sun Java System Directory Server Enterprise Edition 6.0 Deployment Planning Guide.

For a description of how CoS is implemented in Directory Server, see Chapter 9, Directory Server Class of Service, in Sun Java System Directory Server Enterprise Edition 6.0 Reference.


Note –

Any search operation can test the existence of a CoS-generated attribute or compare the value of the attribute. The names of the computed attributes may be used in any filter string from a client search operation, except in an internal filter used in a filtered role.


Using CoS Securely

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

Protecting the CoS Definition Entry

Although the CoS definition entry does not contain the value of the generated attribute, it does provide the information to find that value. Reading the CoS definition entry reveals how to find the template entry that contains the value. Writing to this entry modifies how the computed attribute is generated.

You should therefore define both read and write ACIs for the CoS definition entries.

Protecting the CoS Template Entries

The CoS template entry contains the value of the generated CoS attribute. Therefore, at a minimum, the CoS attribute in the template must be protected by an ACI for both reading and updating.

Protecting the Target Entries of a CoS

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

When the CoS attribute already exists in a target entry, by default, the CoS mechanism does not override this value. If you do not want this behavior, define your CoS to override the target entry, 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 specifies the DN or RDN of the template entry to use. You should use an ACI to protect this attribute either globally throughout the scope of the CoS or individually on each target entry where it is needed.

Protecting Other Dependencies

Computed CoS attributes can be defined in terms of other generated CoS attributes and roles. You must understand and protect these dependencies to ensure that your computed CoS attribute is protected.

For example, the CoS specifier attribute in a target entry could be nsRole. Therefore the role definition must also be protected by an ACI.

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

Managing CoS From the Command Line

Because all configuration information and template data are stored as entries in the directory, you can use the LDAP command-line tools to configure and manage CoS definitions. This section shows how to create CoS definition entries and CoS template entries from the command line.

Creating the CoS Definition Entry From the Command Line

All CoS definition entries have the LDAPsubentry object class and inherit from 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 that are associated with each type of CoS definition entry.

Table 9–1 Object Classes and Attributes in CoS Definition Entries

CoS Type 

CoS Definition Entry 

Pointer CoS 

objectclass: top

objectclass: LDAPsubentry

objectclass: cosSuperDefinition

objectclass: cosPointerDefinition

cosTemplateDN: DN

cosAttribute: attributeName override merge

Indirect CoS 

objectclass: top

objectclass: LDAPsubentry

objectclass: cosSuperDefinition

objectclass: cosIndirectDefinition

cosIndirectSpecifier: attributeName

cosAttribute: attributeName override merge

Classic CoS 

objectclass: top

objectclass: LDAPsubentry

objectclass: cosSuperDefinition

objectclass: cosClassicDefinition

cosTemplateDN: DN

cosSpecifier: attributeName

cosAttribute: attributeName override merge

In all cases, cosAttribute is multivalued. Each value defines an attribute that is generated by the CoS mechanism.

You can use the following attributes in CoS definition entries. For more information about each of these attributes, see the individual attributes in Sun Java System Directory Server Enterprise Edition 6.0 Man Page Reference.

Table 9–2 CoS Definition Entry Attributes

Attribute 

Purpose Within the CoS Definition Entry 

cosAttribute

attributeName override merge

Defines the name of the computed attribute for which you want to generate a value. This attribute is multivalued, and each value represents the name of an attribute whose value is generated from the template. The override and merge qualifiers specify how the CoS attribute value is computed in special cases described following this table.

The attributeName cannot contain any subtypes. Attribute names with subtypes are ignored, but other values of cosAttribute are processed.

cosIndirectSpecifier

attributeName

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 attributeName can be multivalued to designate multiple templates.

cosSpecifier

attributeName

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 attributeName can be multivalued to designate multiple templates.

cosTemplateDN

DN

Provides the full DN of the template entry for a pointer CoS definition or the base DN of the template entry for classic CoS. This attribute is single-valued.  

The cosAttribute attribute allows two qualifiers following the name of the CoS attribute, the override qualifier and the merge qualifier.

The override qualifier describes the behavior when an attribute that is dynamically generated by CoS already physically exists in the entry. The override qualifier can be one of the following:

The merge qualifier is either absent or merge-schemes. This qualifier allows the computed 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=example,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: cosSuperDefinition
objectclass: cosPointerDefinition
cosTemplateDn: cn=exampleUS,cn=data
cosAttribute: postalCode override

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


Note –

If the CoS attribute is defined with the operational or override qualifiers, you cannot perform write operations on the “real” value of that attribute in any entry in the CoS scope.


Multivalued CoS Attributes

When you specify the merge-schemes qualifier, the generated CoS attribute can be multivalued in two ways:

The two situations can occur together and define even more values. However, in all cases, duplicate values will only be returned one time in a generated attribute.

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

The merge-schemes qualifier never merges a “real” value that is 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 can be specified in any order after the attribute name.


Note –

When there are multiple CoS definitions for the same attribute, the definitions 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 multiple CoS definitions or multivalued specifiers exist, but no merge-schemes qualifier, Directory Server uses a priority attribute to select a single template that defines the single value of the computed 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 that the templates define. The cosPriority attribute is defined on CoS template entries as described in the following section.


Note –

The cosPriority attribute must not have a negative value. Also, attributes generated by indirect CoS do not support priority. Do not use cosPriority in template entries of an indirect CoS definition.


Creating the CoS Template Entry From the Command Line

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

The template of the indirect CoS mechanism is an arbitrary, existing entry in the directory. The target does not need to be identified ahead of time or given the LDAPsubentry object class, but the target must have the auxiliary cosTemplate object class. The indirect CoS template is accessed only when the CoS is evaluated to generate a computed 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:


dn: cn=ZipTemplate,ou=People,dc=example,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: extensibleobject
objectclass: cosTemplate
postalCode: 95054
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

The following command creates a pointer CoS definition entry that has the cosPointerDefinition object class. This definition entry uses the CoS template entry that is stated in the example in the previous section to share a common postal code among all entries in the ou=People,dc=example,dc=com tree.


$ ldapmodify -a -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w -
dn: cn=pointerCoS,ou=People,dc=example,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: cosSuperDefinition
objectclass: cosPointerDefinition
cosTemplateDn: cn=ZipTemplate,ou=People,dc=example,dc=com
cosAttribute: postalCode

The CoS template entry (cn=ZipTemplate,ou=People,dc=example,dc=com ) supplies the value stored in its postalCode attribute to all entries located under the ou=People,dc=example,dc=com suffix. If you search for any entry that does not have a postal code in the same subtree, you will see the value of the generated attribute:


$ ldapsearch -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w - \
 -b "ou=People,dc=example,dc=com" -s sub "(cn=*Jensen)"
dn: cn=Babs Jensen,ou=People,dc=example,dc=com
cn: Babs Jensen
...
postalCode: 95054

Example of an Indirect CoS

Indirect CoS names an attribute in the cosIndirectSpecifier attribute to locate the template specific to each target. The template entry for indirect CoS may be any entry in the directory, including other user entries. This example indirect CoS uses the manager attribute of the target entry to identify the CoS template entry. The template entry is the manager’s user entry. The manager’s user entry contains the value of the attribute to generate. The value is that of departmentNumber in this case.

The following command creates the indirect CoS definition entry, which contains the cosIndirectDefinition object class:


$ ldapmodify -a -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w -
dn: cn=generateDeptNum,ou=People,dc=example,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: cosSuperDefinition
objectclass: cosIndirectDefinition
cosIndirectSpecifier: manager
cosAttribute: departmentNumber

Next, add the cosTemplate object class to the template entries, and make sure that they define the attribute to be generated. In this example, all manager entries are templates:


$ ldapmodify -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w -
dn: cn=Carla Fuentes,ou=People,dc=example,dc=com
changetype: modify
add: objectclass
objectclass: cosTemplate
-
add: departmentNumber
departmentNumber: 318842

With this CoS, target entries (the entries under ou=People,dc=example,dc=com) that contain the manager attribute automatically have the department number of their manager. The departmentNumber attribute is computed on the target entries because it does not exist in the server. However, the departmentNumber attribute is returned as part of the target entry. For example, if Babs Jensen’s manager is defined to be Carla Fuentes, her department number is the following:


$ ldapsearch -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w - \
 -b "ou=People,dc=example,dc=com" -s sub "(cn=*Jensen)"
dn: cn=Babs Jensen,ou=People,dc=example,dc=com
cn: Babs Jensen
...
manager: cn=Carla Fuentes,ou=People,dc=example,dc=com
departmentNumber: 318842

Example of a Classic CoS

This example shows how to generate a postal address with a classic CoS. The generated value is specified in a template entry that is located by a combination of the cosTemplateDN in the CoS definition and the value of the cosSpecifier attribute in the target entry. The following command creates the definition entry by using the cosClassicDefinition object class:


$ ldapmodify -a -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w -
dn: cn=classicCoS,dc=example,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: cosSuperDefinition
objectclass: cosClassicDefinition
cosTemplateDn: ou=People,dc=example,dc=com
cosSpecifier: building
cosAttribute: postalAddress

Using the same command, create the template entries that give the postal address for each building:


dn: cn=B07,ou=People,dc=example,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: extensibleobject
objectclass: cosTemplate
postalAddres: 7 Old Oak Street, Anytown, CA 95054

With this CoS, target entries (the entries under ou=People,dc=example,dc=com) that contain the building attribute will automatically have the corresponding postal address. The CoS mechanism searches for a template entry that has the specifier attribute value in its RDN. In this example, if Babs Jensen is assigned to building B07, her postal address is generated as follows:


$ ldapsearch -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w - \
 -b "ou=People,dc=example,dc=com" -s sub "(cn=*Jensen)"
dn: cn=Babs Jensen,ou=People,dc=example,dc=com
cn: Babs Jensen
...
building: B07
postalAddress: 7 Old Oak Street, Anytown, CA 95054

Creating Role-Based Attributes

You can create classic CoS schemes that generate attribute values for an entry that is 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 is as follows:


dn: cn=ManagerRole,ou=People,dc=example,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: nsRoleDefinition
objectclass: nsComplexRoleDefinition
objectclass: nsFilteredRoleDefinition
cn: ManagerRole
nsRoleFilter: (isManager=True)
Description: filtered role for managers

The classic CoS definition entry is created as follows:


dn: cn=generateManagerQuota,ou=People,dc=example,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: cosSuperDefinition
objectclass: cosClassicDefinition
cosTemplateDn: cn=managerCOS,ou=People,dc=example,dc=com
cosSpecifier: nsRole
cosAttribute: mailboxquota override

The CoS template name must be a combination of the cosTemplateDn and the value of nsRole, which is the DN of the role. For example:


dn:cn="cn=ManagerRole,ou=People,dc=example,dc=com",\
 cn=managerCOS,ou=People,dc=example,dc=com
objectclass: top
objectclass: LDAPsubentry
objectclass: extensibleobject
objectclass: cosTemplate
mailboxquota: 1000000

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. Target entries that are members of the role will have computed attributes generated by the role and by the CoS, for example:


$ ldapsearch -h host1 -p 1389 -D cn=admin,cn=Administrators,cn=config -w -\
 -b "ou=People,dc=example,dc=com" -s sub "(cn=*Fuentes)"
dn: cn=Carla Fuentes,ou=People,dc=example,dc=comcn: Carla Fuentes
isManager: TRUE...nsRole: cn=ManagerRole,ou=People,dc=example,dc=com
mailboxquota: 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.


Monitoring the CoS Plug-In

Directory Server enables you to monitor certain aspects of the CoS plug-in. CoS monitoring attributes are stored in the cn=monitor,cn=Class of Service,cn=plugins,cn=config entry. For details of the each attribute under this entry and the information that they provide, see Sun Java System Directory Server Enterprise Edition 6.0 Man Page Reference.

Setting CoS Logging

Directory Server logs warning messages when it is forced to make an arbitrary distinction among multiple applicable definition entries. Such warning messages takes this form:


Definition /defDN1/ and definition /defDN2/ compete to provide attribute
 '/type/' at priority /level/

You can also configure Directory Server to log informational messages when the server is forced to make an arbitrary distinction among multiple, potentially applicable definition entries. To do so, set the error log to include messages from plug-ins.


Note –

Because setting additional log levels can result in a heavy logging load, you might not want to set logging on a production server.


The content of informational messages takes the following form:


Definition /defDN1/ and definition /defDN2/ potentially compete 
to provide attribute '/type/' at priority /level/

You can then choose whether to resolve such cases of CoS ambiguity by setting CoS priorities appropriately on the definition entries.

Maintaining Referential Integrity

Referential integrity is a plug-in mechanism that ensures that relationships between entries are maintained. Several types of attributes, such as those for group membership, contain the DN of another entry. Referential integrity can be used to ensure that when an entry is removed, all attributes that contain its DN are also removed.

For example, if a user’s entry is removed from the directory and referential integrity is enabled, the server also removes the user from any groups of which the user is a member. If referential integrity is not enabled, the user must be manually removed from the group by the administrator. This is an important feature if you are integratingDirectory Server with other Sun Java System products that rely on the directory for user and group management.

How Referential Integrity Works

When the referential integrity plug-in is enabled it performs integrity updates on specified attributes immediately after a delete, rename, or move operation. By default, the referential integrity plug-in is disabled.

Whenever you delete, rename, or move a user or group entry in the directory, the operation is logged to the referential integrity log file:

instance-path/logs/referint

After a specified time, known as the update interval, the server performs a search on all attributes for which referential integrity is enabled, and matches the entries resulting from that search with the DNs of deleted or modified entries present in the log file. If the log file shows that the entry was deleted, the corresponding attribute is deleted. If the log file shows that the entry was changed, the corresponding attribute value is modified accordingly.

When the default configuration of the referential integrity plug-in is enabled, it performs integrity updates on the member, uniquemember, owner, seeAlso, and nsroledn attributes immediately after a delete, rename, or move operation. You can, however, configure the behavior of the referential integrity plug-in to suit your own requirements. The following behavior can be configured:

ProcedureTo Configure the Referential Integrity Plug-In


Note –

All attributes in all databases that are used by the referential integrity plug-in must be indexed. The indexes need to be created in the configuration of all the databases. When the retro change log is enabled, the cn=changelog suffix must be indexed. For information, see Chapter 12, Directory Server Indexing.


Certain limitations are associated with using the referential integrity plug-in in a replicated environment. For a list of these limitations, see Replication and Referential Integrity.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

  1. Make sure that all replicas are configured and that all replication agreements are defined.

  2. Determine the set of attributes for which you will maintain referential integrity and the update interval that you want to use on your master servers.

  3. Enable the referential integrity plug-in on all master servers using the same set of attributes and the same update interval.

    • To define the attributes for referential integrity, use this command:


      $ dsconf set-server-prop -h host -p port ref-integrity-attr:attribute-name
      
    • To define the referential integrity update interval, use this command:


      $ dsconf set-server-prop -h host -p port ref-integrity-check-delay:duration
      
    • To enable referential integrity, use this command:


      $ dsconf set-server-prop -h host -p port ref-integrity-enabled:on
  4. Ensure that the referential integrity plug-in is disabled on all consumer servers.