| Previous Contents Index Next |
| Directory Server Access Management Edition Programmer's Guide |
Chapter 8 iPlanet Directory Server And DSAME
iPlanet Directory Server Access Management Edition (DSAME) uses iPlanet Directory Server (DS) to store its data. Certain features of the LDAP-based DS are also used by DSAME to help manage the data. This chapter contains information on these DS features and how they are used. It contains the following sections:
Overview
DSAME has been built to work with DS. They are complementary in architecture and design data. DSAME needs an underlying directory server to function. Use of the directory, though, is not exclusive to DSAME and, therefore, needs to be treated as a completely separate deployment. For more information on the directory server, see the iPlanet Directory Server documentation.
Roles
Roles are a DS entry grouping 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 role itself is defined in an LDAP entry as a role object and is identified by the DN of the object. DS has a number of different types of roles but DSAME can only manage one of them: the managed role.
Note The other DS role types can still be used in a directory deployment; they just can not be managed by DSAME.
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. Then, when new contractors start, the administrator would assign them this role instead of setting separate attributes in the contractor entry. If the contractor were then to become a full-time employee, the administrator could just re-assign them a different role.
Managed Roles
With a managed role, role membership is defined in each role's member entry and not in the role's definition entry. An attribute which designates membership is placed upon each entry which belongs to the role. This is in contrast to a traditional static group which centrally lists the members in the group object entry itself.
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:
Multiple managed roles can be created for each organization or sub-organization.
A managed role can be enabled with any number of services.
Any user that possesses a role with a service will inherit the service attributes from that role.
Note All DSAME roles can only be configured directly under organization or sub-organization entries.
Role Definition Entry
A role definition entry is a LDAP entry where the role's characteristics are defined. Below is a sample of a manager role definition entry.
The nsManagedRoleDefinition object class inherits from the LDAPsubentry, nsRoleDefinition and nsSimpleRoleDefinition object classes.
Role Member Entry
A role member entry is an LDAP entry in which the role is applied. The nsRoleDN attribute indicates that the entry is a member of a managed role identified by the DN of its role definition entry; in Code Example 8-2 below, the DN identifies Code Example 8-1 as the role definition entry cn=managerrole,dc=siroe,dc=com.
Virtual Attribute
When a role member entry that contains the nsRoleDN attribute is returned by DS, nsRoleDN will be aliased to the nsRole attribute on that same entry. nsRole will carry a value of any managed, filtered or nested roles assigned to the user (such as ContainerDefaultTemplateRole). The LDIF Code Example 8-2 includes this virtual attribute when returned by DS only.
How DSAME Uses Roles
DSAME uses roles to apply access control instructions. When installed, the DSAME application configures access control instructions (ACIs) to define administrator permissions. These ACIs 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 access permissions.
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:
iplanet-am-role-managed-container-dn contains the DN of the identity-related object that the role was created to manage.
iplanet-am-role-type contains a value used by the DSAME console for display purposes. After authentication, the console gets the user's roles and checks this attribute for the correct page to display based on which of the following three values it has:
- If the user has no administrator roles, the User profile page will display. If the user has an administrator role, the console will start the user at the top-most administrator page based on which value is present.
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.
Note 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 also 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:
DSAME checks the iplanet-am-user-admin-start-dn for the user.
DSAME checks the user for the value of iplanet-am-role-type.
- This attribute is contained in the User service. If it is set, the user is started at this point. If not, DSAME goes to step 2.
- 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 tree is displayed as a starting point. For more information on the iplanet-am-role-type attribute, see "Role Creation".
Access Control Instructions (ACIs)
Note This section refers to ACIs as they are applied to administrative roles only. There are other ACIs which are created and used in DSAME but do not apply to this topic or to roles.
Access control in DSAME is implemented using DS roles. Users inherit access permissions based on their role membership and parent organization. DSAME installs pre-configured administrator roles that define access permissions for administrators that are dynamically created when a group, organization, container or people container is configured. (They are Organization Admin, Organization Help Desk Admin, Group Admin, Container Admin, Container Help Desk Admin and People Container Admin.) These roles apply a set of default access control instructions (ACIs) that define read and write access to the entries in the corresponding object. For example, when an organization is created, the DSAME SDK creates an Organization Admin role and an Organization Help Desk Admin role. The permissions are read and write access to all organization entries and read access to all organization entries, respectively.
Note The DSAME 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 DSAME console Administration XML service file, amAdminConsole.xml. This file contains two global attributes that define ACIs for use in DSAME: iplanet-am-admin-console-role-default-acis and iplanet-am-admin-console-dynamic-aci-list.
iplanet-am-admin-console-role-default-acis
This global attribute defines which Access Permissions are displayed in the Create Role screen of the DSAME 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.
iplanet-am-admin-console-dynamic-aci-list
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".
Format of Predefined ACIs
ACIs set using DSAME for use in administrator-type roles follow a different format than those set using the DS. The format of the predefined DSAME ACI is permissionName | ACI Description | DN:ACI ## DN:ACI ## DN:ACI where:
permissionName—The name of the permission which generally includes the object being controlled and the type of access. For example, Organization Admin is an administrator that controls access to an organization object.
ACI Description—A text description of the access these ACIs allow.
DN:ACI—There can be any number of DN:ACI couplets separated by the ## symbols. The SDK will get and set each couplet in the DN entry. This format also supports tags which can be dynamically substituted when the role is created. Without these tags, the DN and ACI would be hard-coded to specific organizations in the DIT which would make them unusable as defaults. For example, if there is a default set of ACIs for every Organization Admin, the organization name should not be hard-coded in this role. The supported tags are ROLENAME, ORGANIZATION, GROUPNAME, and PCNAME. These tags are substituted with the DN of the entry when the corresponding entry type is created. See the "Default ACIs" for examples of ACI formats. Additionally, more complete ACI information can be found in the iPlanet Directory Server documentation.
Note If there are duplicate ACIs within the default permissions, the SDK will print a debug message.
Default ACIs
Following are the default ACIs installed by DSAME. They are copied from a DSAME configuration whose top-level organization is o=isp.
Top Level Admin|Access to all entries|o=isp:aci: (target="ldap:///o=isp")(targetattr="*")(version 3.0; acl "Proxy user rights"; allow (all) roledn = "ldap:///ROLENAME";)
Organization Admin|Read and Write access to all organization entries|o=isp:aci:(target="ldap:///($dn),o=isp")(targetfilter=(!(|(nsroledn=cn=Top Level Admin Role,o=isp)(nsroledn=cn=Top Level Help Desk Admin Role,o=isp))))(targetattr = "*")(version 3.0; acl "Organization Admin Role access allow"; allow (all) roledn = "ldap:///cn=Organization Admin Role,[$dn],o=isp";)##o=isp:aci: (target="ldap:///cn=Organization Admin Role,($dn),o=isp")(targetattr="*")(version 3.0; acl "Organization Admin Role access deny"; deny (write,add,delete,compare,proxy) roledn = "ldap:///cn=Organization Admin Role,($dn),o=isp";)
Organization Help Desk Admin|Read access to all organization entries|ORGANIZATION:aci:(target="ldap:///ORGANIZATION")(targetfilter=(!(|(nsroledn=cn=Top Level Admin Role,o=isp)(nsroledn=cn=Top Level Help Desk Admin Role,o=isp)(nsroledn=cn=Organization Admin Role,ORGANIZATION))))(targetattr = "*") (version 3.0; acl "Organization Help Desk Admin Role access allow"; allow (read,search) roledn = "ldap:///ROLENAME";)##ORGANIZATION:aci: (target="ldap:///ORGANIZATION")(targetfilter=(!(|(nsroledn=cn=Top Level Admin Role,o=isp)(nsroledn=cn=Organization Admin Role,ORGANIZATION))))(targetattr = "userPassword") (version 3.0; acl "Organization Help Desk Admin Role access allow"; allow (write)roledn = "ldap:///ROLENAME";)
Container Admin|Read and Write access to all organizational unit entries|o=isp:aci:(target="ldap:///($dn),o=isp")(targetfilter=(!(|(nsroledn=cn=Top Level Admin Role,o=isp)(nsroledn=cn=Top Level Help Desk Admin Role,o=isp))))(targetattr = "*")(version 3.0; acl "Container Admin Role access allow"; allow (all) roledn = "ldap:///cn=Container Admin Role,[$dn],o=isp";)o=isp:aci: (target="ldap:///cn=Container Admin Role,($dn),o=isp")(targetattr="*")(version 3.0; acl "Container Admin Role access deny"; deny (write,add,delete,compare,proxy) roledn = "ldap:///cn=Container Admin Role,($dn),o=isp";)
Container Help Desk Admin|Read access to all organizational unit entries|ORGANIZATION:aci:(target="ldap:///ORGANIZATION")(targetfilter=(!(|(nsroledn=cn=Top Level Admin Role,o=isp)(nsroledn=cn=Top Level Help Desk Admin Role,o=isp)(nsroledn=cn=Container Admin Role,ORGANIZATION))))(targetattr = "*") (version 3.0; acl "Container Help Desk Admin Role access allow"; allow (read,search) roledn = "ldap:///ROLENAME";)##ORGANIZATION:aci: (target="ldap:///ORGANIZATION")(targetfilter=(!(|(nsroledn=cn=Top Level Admin Role,o=isp)(nsroledn=cn=Container Admin Role,ORGANIZATION))))(targetattr = "userPassword") (version 3.0; acl "Container Help Desk Admin Role access allow"; allow (write) roledn = "ldap:///ROLENAME";)
Group Admin|Read and Write access to all group members|ORGANIZATION:aci:(target="ldap:///GROUPNAME")(targetattr = "*") (version 3.0; acl "Group and people container admin role"; allow (all) roledn = "ldap:///ROLENAME";)##ORGANIZATION:aci: (target="ldap:///ORGANIZATION")(targetfilter=(!(|(!FILTER)(|(nsroledn=cn=Top Level Admin Role,o=isp)(nsroledn=cn=Top Level Help Desk Admin Role,o=isp)(nsroledn=cn=Organization Admin Role,ORGANIZATION)(nsroledn=cn=Container Admin Role,ORGANIZATION)))))(targetattr != "iplanet-am-web-agent-access-allow-list || iplanet-am-web-agent-access-not-enforced-list || iplanet-am-domain-url-access-allow || iplanet-am-web-agent-access-deny-list")(version 3.0;acl "Group admin's right to the members"; allow (read,write,search) roledn = "ldap:///ROLENAME";)
People Container Admin|Read and Write access to all users|ORGANIZATION:aci:(target="ldap:///PCNAME")(targetfilter=(!(|(nsroledn=cn=Top Level Admin Role,o=isp)(nsroledn=cn=Top Level Help Desk Admin Role,o=isp)(nsroledn=cn=Organization Admin Role,ORGANIZATION)(nsroledn=cn=Container Admin Role,ORGANIZATION))))(targetattr != "iplanet-am-web-agent-access-allow-list || iplanet-am-web-agent-access-not-enforced-list || iplanet-am-domain-url-access-allow || iplanet-am-web-agent-access-deny-list") (version 3.0; acl "People container admin role"; allow (all) roledn = "ldap:///ROLENAME";)
Class Of Service
Both dynamic and policy attributes use class of service (CoS), a feature of the DS that allows attributes to be created and managed in a single central location, and dynamically added to user entries. Attribute values are not stored with 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 entries:
CoS Definition Entry—This entry identifies the type of CoS being used (ClassicCoS). It contains all the information, save the attribute values, needed to generate an entry defined with CoS. The scope of the CoS is the entire sub-tree below the parent of the CoS definition entry.
The CoS definition entry and template entry interact to provide attribute information to their target entries, which is any entry within the scope of the CoS. Only those services which have dynamic or policy attributes use the DS CoS feature; no other services do.Template Entry—This entry contains a list of the shared attribute values. Changes to the attribute values are automatically applied to all entries within the scope of the CoS.
Note For additional information on the CoS feature, see the iPlanet 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. 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:
cosClassicDefinition
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.
Note 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 could be assigned to a role or organization, thus creating possible conflicts. When this happens, DSAME 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 DSAME 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 2 "DSAME And XML" or the iPlanet Directory Server documentation.
Note Conflict resolution is decided by the DS before the entry is returned to DSAME. DSAME allows only the definition of the priority level and CoS type.
Existing Applications
If a customer is using an existing application and wants to manage its attributes using the DSAME console, a LDAP schema is probably defined and has been loaded into the DS. If DS does not already have the existing application's attributes and object classes loaded, then it needs to be updated using the DS console or the ldapmodify command line interface. The schema update needs to be completed before loading the application's created XML service file. Other options for adding or modifying DS schema can be found in the iPlanet Directory Server documentation or in the iPlanet Directory Server Access Management Edition Installation and Configuration Guide.
Previous Contents Index Next
Copyright © 2002 Sun Microsystems, Inc. All rights reserved.
Last Updated May 14, 2002