Sun ONE logo      Previous      Contents      Index      Next     

Sun ONE Identity Server Customization and API Guide

Appendix E
Directory Server Concepts

Sun™ One Identity Server uses Sun ONE Directory Server to store its data. Certain features of the LDAP-based Directory Server are used by Identity Server to help manage its data. This chapter contains information on these Directory Server features and how they are used. It contains the following sections:


Because Identity Server needs an underlying data store, it has been built to work with Sun ONE Directory Server. They are complementary in architecture and design data. Use of Directory Server, though, may not be exclusive to Identity Server and therefore, needs to be treated as a completely separate deployment. For more information on Directory Server deployment, see the Sun ONE Directory Server documentation.

This appendix explains three Directory Server functions that are used by the Identity Server. A role is an identity grouping mechanism; an access control instruction (ACI) defines rules to allow or deny access to Directory Server data, and class of service is an attribute grouping mechanism.


Roles are a Directory Server entry mechanism similar to the concept of a group. A group has members; a role has members. A role’s members are LDAP entries that are said to possess the role. The criteria of the role itself is defined as an LDAP entry with attributes, identified by the Distinguished Name (DN) attribute of the entry. Directory Server has a number of different types of roles but Identity Server can only manage one of them: the managed role.


The other Directory Server role types can still be used in a directory deployment; they just can not be managed by Identity Server.

Users can possess one or more roles. For example, a contractor role which has attributes from the Session Service and the URL Policy Agent Service might be created. Thus, when new contractors start, the administrator can assign them this role rather than setting separate attributes in the contractor entry. If the contractor were then to become a full-time employee, the administrator would just re-assign the user a different role.

Managed Roles

With a managed role, membership is defined in each member entry and not in the role definition entry. An attribute which designates membership is placed in each LDAP entry that possesses the role. This is in sharp contrast to a traditional static group which centrally lists the members in the group object entry itself.


By inverting the membership mechanism, the role will scale better than a static group. In addition, the referential integrity of the role is simplified, and the roles of an entry can be easily determined.

An administrator assigns the role to a member entry by adding the nsRoleDN attribute to it. The value of nsRoleDN is the DN of the role definition entry. The following apply to managed roles:

Definition Entry

A role’s definition entry is a LDAP entry in which the role’s characteristic attributes are defined. These attributes are passed onto the member entry. Below is a sample LDAP entry that represents the definition entry of a manager role.

Code Example 12-1  LDAP Definition Entry

dn: cn=managerrole,dc=siroe,dc=com

objectclass: top

objectclass: LDAPsubentry

objectclass: nsRoleDefinition

objectclass: nsSimpleRoleDefinition

objectclass: nsManagedRoleDefinition

cn: managerrole

description: manager role within company

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

Member Entry

A role’s member entry is a LDAP entry to which the role is applied. An LDAP entry that contains the attribute nsRoleDN and its value DN indicates that the entry has the characteristics defined in the value DN entry. In Code Example 12-2 below, the DN identifies Code Example 12-1 above as the role definition entry: cn=managerrole,dc=siroe,dc=com.

Virtual Attribute

When a member entry that contains the nsRoleDN attribute is returned by a Directory Server search, nsRoleDN will be be duplicated as the nsRole attribute in the same entry. nsRole will carry a value of any managed, filtered or nested roles assigned to the user (such as ContainerDefaultTemplateRole). Code Example 12-2 includes this virtual attribute when returned by Directory Server only.

Code Example 12-2  LDAP Member Entry 

dn: uid=managerperson,ou=people,dc=siroe,dc=com

objectclass: top

objectclass: person

objectclass: inetorgperson

uid: managerperson

gn: manager

sn: person

nsRoleDN: cn=managerrole,ou=people,dc=siroe,dc=com

nsRole: cn=managerrole,ou=people,dc=siroe,dc=com

nsRole: cn=containerdefaulttemplaterole,ou=people,dc=siroe,dc=com

description: manager person within company

How Identity Server Uses Roles

Identity Server uses roles to apply Access Control Instructions. When first installed, the Identity Server configures ACI that define administrator permissions to directory data. These ACI are then designated in roles (such as Organization Admin Role and Organization Help Desk Admin Role) which, when assigned to a user, define the user’s level of access. For a list of roles created for each Identity Server object configured, see "Access Control Instructions".


Managed groups in Identity Server are modeled almost the same as roles. They add an attribute to an LDAP entry to make the entry a member of the dynamic group

Role Creation

When a role is created, it contains the auxiliary LDAP object class iplanet-am-managed-role. This object class, in turn, contains the following allowed attributes:

Role Location

All roles in an organization are viewed from the organization’s top-level. For example, if an administrator wants to add a user to the administrator role for a people container, the administrator would go to the organization above the people container, look for the role based on the people container’s name, and add the user to the role.


Alternately, an administrator might go to the user profile and add the role to the user.

Displaying The Correct Login Start Page

The attribute iplanet-am-user-admin-start-dn can be defined for a role or a user; it would override the iplanet-am-role-type attribute by defining an alternate display page URL. Upon a user’s successful authentication:

  1. Identity Server checks the iplanet-am-user-admin-start-dn for the user.
  2. This attribute is contained in the User service. If it is set, the user is started at this point. If not, Identity Server goes to step 2.


    The value of iplanet-am-user-admin-start-dn can override the administrator’s start page. For example, if a group administrator has read access to the top-level organization, the default starting page of the top-level organization, taken from iplanet-am-role-type, can be overridden by defining iplanet-am-user-admin-start-dn to display the group’s start page.

  3. Identity Server checks the user for the value of iplanet-am-role-type.
  4. If the attribute defines an administrator-type role, the value of iplanet-am-role-managed-container-dn is retrieved and the highest point in the directory tree is displayed as a starting point. For more information on the iplanet-am-role-type attribute, see "Role Creation".


    If the attribute has no value, a search from Identity Server root is performed for all container-type objects; the highest object in the directory tree that corresponds to the iplanet-am-role-type value is where the user starts. Although rare, this step is memory-intensive in very large directory trees with many container entries.

Access Control Instructions

Control over access to directory information is implemented in Identity Server using roles. Users inherit access permissions based on their role membership and parent organization. Identity Server installs pre-configured administrator roles that define different levels of permission for administrators to access directory information; these roles are dynamically created when a group, organization, container or people container object is configured. They are:

These default roles, when possessed by a user entry, define that user’s level of access to Directory Server data. For example, when an organization is created, the Identity Server SDK creates an Organization Admin role and an Organization Help Desk Admin role. The permissions are read and write access to all entries in the organization and read access to all entries in the organization, respectively.


The Identity Server SDK gets the ACIs from the attribute iplanet-am-admin-console-dynamic-aci-list (defined in the amAdminConsole.xml service file) and sets them in the roles after they have been created.

Defining ACIs

ACIs are defined in the Identity Server console administration XML service file, amAdminConsole.xml. This file contains two global attributes that define ACIs for use in Identity Server: iplanet-am-admin-console-role-default-acis and iplanet-am-admin-console-dynamic-aci-list.


This global attribute defines which Access Permissions are displayed in the Create Role screen of the Identity Server console. By default, Organization Admin, Organization Help Desk Admin and No Permissions are displayed. If other default permissions are desired, they must be added to this attribute.


This global attribute is where all of the defined administrator-type ACIs are stored. For information on how ACIs are structured, see "Format of Predefined ACIs".


Because ACIs are stored in the role, changing the default permissions in iplanet-am-admin-console-dynamic-aci-list after a role has been created will not affect it. Only roles created after the modification has been made will be affected.

Format of Predefined ACIs

ACIs defined in Identity Server for use with administrator-type roles follow a different format than those defined using Directory Server. The format of the predefined Identity Server ACI is permissionName | ACI Description | DN:ACI ## DN:ACI ## DN:ACI where:

Default ACIs

Following are the default ACIs installed by Identity Server. They are copied from a Identity Server configuration whose top-level organization is configured as o=isp.

Class Of Service

Both dynamic and policy attributes use class of service (CoS), a feature of the Directory Server that allows attributes to be created and managed in a single central location, and dynamically added to user entries as the user entry is called. Attribute values are not stored within the entry itself; they are generated by CoS as the entry is sent to the client browser. Dynamic and policy attributes using CoS consist of the following two LDAP entries:

The CoS Definition entry and the Template entry interact to provide attribute information to their target entries; any entry within the scope of the CoS. Only those services which have dynamic or policy attributes use the Directory Server CoS feature; no other services do.


For additional information on the CoS feature, see the Sun ONE Directory Server documentation.

CoS Definition Entry

CoS definition entries are stored as LDAP subentries under the organization level but can be located anywhere in the DIT. They contain the attributes specific to the type of CoS being defined. These attributes name the virtual CoS attribute, the template DN and, if necessary, the specifier attribute in target entries. By default, the CoS mechanism will not override the value of an existing attribute with the same name as the CoS attribute. The CoS definition entry takes the cosSuperDefinition object class and also inherits from the following object class that specifies the type of CoS:


The cosClassicDefinition object class determines the attribute and value that will appear with an entry by taking the base DN of the template entry from the cosTemplateDN attribute in the definition entry and combining it with the target entry specifier as defined with the cosSpecifier attribute, also in the definition entry. The value of the cosSpecifier attribute is another LDAP attribute which is found in the target entry; the value of the attribute found in the target entry is appended to the value of cosTemplateDN and the combination is the DN of the template entry. Template DNs for classic CoS must therefore have the following structure cn=specifierValue,baseDN.

CoS Template Entry

CoS Template entries are an instance of the cosTemplate object class. The CoS Template entry contains the value or values of the virtual attributes that will be generated by the CoS mechanism and displayed as an attribute of the target entry. The template entries are stored under the definition entries.


When possible, definition and template entries should be located at the same level for easier management.

Conflicts and CoS

There is the possibility that more than one CoS can be assigned to a role or organization, thus creating conflict. When this happens, Identity Server will display either the attribute value based on a pre-determined template priority level or the aggregate of all attribute values defined in the cosPriority attribute. For example, an administrator could create and load multiple services, register them to an organization, create separate roles within the organization and assign multiple roles to a particular user. When Identity Server retrieves this user entry, it sees the CoS object classes, and adds the virtual attributes. If there are any priority conflicts, it will look at the cosPriority attribute for a priority level and return the information with the lowest priority number (which is the highest priority level). For more information on CoS priorities, see "cosQualifier Attribute" of Chapter 6, "Service Management" or the Sun ONE Directory Server documentation.


Conflict resolution is decided by the Directory Server before the entry is returned to Identity Server. Identity Server allows only the definition of the priority level and CoS type.

Previous      Contents      Index      Next     

Copyright 2003 Sun Microsystems, Inc. All rights reserved.