Chapter 5   Identity Management


The Identity Management module of Sun^TM ONE Identity Server contains an XML template file and application programming interfaces (APIs) that provide functionality to, among other operations, create, delete and manage identity entries in the Sun ONE Directory Server used for data storage. This chapter offers information on the public APIs. It contains the following sections:

• Overview

• Object Templates

• Identity Server SDK

• amEntrySpecific.xml

• Management Sample Functions

Overview

---

The Identity Management module of Identity Server allows for the management of identity-related objects stored in the Directory Server. Towards this end, it provides interfaces for creating and managing identity-related objects in the Directory Server. The management functions that can be performed include the creation and deletion of specific objects as well as the ability to get, add, modify, or remove the attributes of these objects. The interfaces include a set of templates, defined in the ums.xml file, that contain LDAP configuration information for identity-related objects and a Java Software Development Kit (SDK) to embed the management functions into applications or services.

Abstract Objects

Identity Server represents the objects it manages abstractly; in other words, an organization in Identity Server does not necessarily map to an LDAP organization in the Directory Server. The default abstract objects are:

• organization

• organizational unit

• people container

• static group

• filtered group

• assignable dynamic group

• group container

  
  

  ---

  Note	For more information, see "amEntrySpecific.xml Schema".

  ---

  
  

Marker Object Classes

Abstract objects are identified in the Directory Server by object classes that are referred to as marker and defined in an Identity Server schema. The marker object classes are then used in LDAP object entries. For example, the Directory Server may use organizational units for their first level structure; by adding the Identity Server organization marker object class, iplanet-am-managed-org, to the LDAP entries of these organizational units, Identity Server can manage them as organizations. It is the use of marker object classes that allows Identity Server to manage most directory structures, regardless of the LDAP object classes and naming attributes deployed. The marker object classes are:

• iplanet-am-managed-filtered-group

• iplanet-am-managed-assignable-group

• iplanet-am-managed-static-group

• iplanet-am-managed-org

• iplanet-am-managed-org-unit

• iplanet-am-managed-people-container

• iplanet-am-managed-group-container

  
  

  ---

  Note	The marker object classes are defined in the Identity Server-specific LDAP schema ds_remote_schema.ldif which can be found in <identity_server_root>/SUNWam/ldif. It is loaded into the Directory Server when Identity Server is installed.

  ---

  
  

Object Templates

---

The ums.xml provides a set of parameters, known as Templates, that contain LDAP configuration information for all identity-related objects. Identity Server uses these templates to define the configuration of the Directory Server entries that store the Identity Server entry information created by the Identity Server SDK. The file can be found in the <identity_server_root>/SUNWam/config/ums directory and is based on the sms.dtd. The templates provide LDAP structure for:

• Users

• Groups

• Organizations

• Roles

• Organization Units

• Group Containers

• People Containers

The templates are used by the Identity Server SDK for the creation of identity-related objects in the Directory Server, as well as the dynamic generation of the object's roles and the construction of object searches. (These templates can be modified by administrators to alter the behavior of the Java interfaces.) Using these templates and the LDIF schema, parameters are configured for all identity-related objects.

When Identity Server is installed, the ums.xml file is stored in the Directory Server as the DAI service. (DAI is a service in the Identity Server whose configuration is not made available through the console.) The Identity Server SDK gets the configuration information from this node when it is being asked to create an identity-related object, generate a role or perform a search. Any attribute specified in the ums.xml can be set for a created object.

---

Caution

Because ums.xml defines templates for directory entries created by the SDK, if it is modified and reloaded, there will be inconsistencies between the entries created prior and the newer ones to be created. Therefore, modifications to this file are not recommended unless Identity Server is being installed as a brand new entity.

---

Structure of ums.xml

The ums.xml defines three types of templates: Structure, Creation and Search. Structure templates define the Directory Server DIT attributes for the object. Creation templates define an LDAP template for the object being created. Search templates define guidelines for performing searches using LDAP.

Structure Templates

Structure templates define the form an Identity Server object will take in the Directory Server DIT. This conforms to where the object is located within the DIT; the objects are strictly LDAP entries. There are six attributes that need to be defined for each subschema.

• class—This attribute represents the name of the Java class that will implement the object. This attribute is fixed and should never be modified.

• name—This attribute defines the entry type of the object. For example, an organization object has o=org as its name.

• childNode—This attribute specifies the child nodes that will be created in tandem with the object.

• template—This attribute specifies the Creation template used to create this object.

• filter—This attribute specifies a filter that will be used to identify the object.

• priority—This attribute is defined as 0.

Creation Templates

Every identity object that Identity Server creates has a corresponding creation template which defines the LDAP schema for the object. It specifies which object classes and attributes are mandatory or optional and which default values, if any, should be set. This conforms to the actual LDAP entry in the Directory Server. There are six attributes that need to be defined for each subschema.

• name—This attribute defines the name of the object the template will create. It is also the name of the template itself.

• javaclass—This attribute defines the name of the Java class used to instantiate the object.

• required—This attribute defines the required LDAP attributes for the object.

• optional—This attribute defines the optional LDAP attributes for the object.

• validated—This attribute is reserved for future use.

• namingattribute—This attribute specifies the LDAP entry type.

Search Templates

Search templates are used to define how searches for Identity Server objects are performed in the Directory Server. This template defines a default search filter and the attributes returned in a search. For example, a search filter is constructed which defines and specifies which attributes and values are to be retrieved from the Directory Server.

• name—This attribute defines the name of the search template.

• searchfilter—This attribute defines the LDAP search filter.

• attrs—This attribute specifies the LDAP attributes that need to be returned.

Modifying ums.xml

Any new LDAP attributes or object classes must be added to the ums.xml file in order for them to be recognized by the Identity Server. In most cases, the attributes that service developers might want to add may already exist in the inetorgperson and the inetuser object classes. If, for example, a custom mail service is being added with, specifically, an employee_id attribute, the ums.xml file does not need to be modified because this attribute already exists in the inetorgperson object class. Generally, as in the example, the ums.xml file does not need to be modified. The only circumstances where this file would need to be modified are:

• if DSAME is being installed against a legacy DIT.

• if new object classes are being added to users or organizations.

• if service developers want to change the default organizations or roles.

• if service developers need to change an entry's naming attribute.

Additional information on when and how to modify the ums.xml file is covered in the section on installing against a legacy DIT in the Sun ONE Identity Server Installation and Configuration Guide.

---

Caution

It is highly recommended that the ums.xml configuration file is duplicated before any modifications are made.

---

Adding Custom Object Classes

If a service developer wanted to add new or customized object classes to the Directory Server for Identity Server's use, they would need to modify the templates in the ums.xml file. Then, to manage them from the Identity Server console, these new object classes and attributes have to be modelled as an XML service file and imported into Identity Server using the procedures described in Chapter 6 "Service Management."

---

Note	umsExisting.xml contains objectclasses and user object class tags which will be replaced after installation and is used when installing Identity Server with an existing directory server information tree.

---

Identity Server SDK

---

The Identity Server SDK contains APIs for identity management. These interfaces can be used by developers to integrate management functions into external applications or services that will be managed by the Identity Server. The APIs function to create or delete identity-related objects as well as get, modify, add or delete the object's attributes. The com.iplanet.am.sdk package contains all the interfaces and classes necessary to perform these operations in the Directory Server.

---

Note	The Identity Server Javadocs can be accessed from any browser by copying the complete <identity_server_root>/SUNWam/docs/ directory into the <identity_server_root>/SUNWam/public_html directory and pointing the browser to http://<server_name.domain_name>:<port>/docs/index.html.

---

SDK Interfaces

Below are brief explanations of the Identity Server SDK interfaces.

AMConstants

AMConstants is the base interface for all identity-related objects. It is used to define the scope of a search of the Directory Server. It can search for a specific object, a particular level of the DIT or an attribute.

AMObject

AMObject provides basic methods to manage identity-related objects. Since this is a generic class, it does not have any Templates (defined in "Object Templates") associated with it.

AMOrganization

The AMOrganization interface provides the methods used to manage organizations. Associated with this interface are the following ums.xml Templates that define its behavior at runtime. The name of the structural template used by this class is Organization; the name of the creation template used is BasicOrganization, and the name of the search template is BasicOrganizationSearch.

AMOrganizationalUnit

The AMOrganizationalUnit interface provides the methods used to manage organizational units. Associated with this object are the following ums.xml Templates that define its behavior at runtime. The name of the structural template used by this class is OrganizationalUnit; the name of the creation template used is BasicOrganizationalUnit, and the name of the search template is BasicOrganizationalUnitSearch.

AMPeopleContainer

The AMPeopleContainer interface provides the methods used to manage people containers. Associated with this object are the following ums.xml Templates that define its behavior at runtime. The name of the structural template used by this class is PeopleContainer; the name of the creation template used is BasicPeopleContainer, and the search template is BasicPeopleContainerSearch.

AMGroupContainer

The AMGroupContainer interface provides the methods used to manage group containers. Associated with this object are the following ums.xml Templates that define its behavior at runtime. The name of the structural template used by this class is GroupContainer; the name of the creation template used is BasicGroupContainer, and the search template is BasicGroupContainerSearch.

AMGroup

The AMGroup interface provides the methods used to manage groups. This is the basic class for all derived groups, such as static groups, dynamic groups and assignable dynamic groups. No default templates are defined for this class.

AMStaticGroup

The AMStaticGroup interface provides the methods used to manage static groups. This class extends the base AMGroup interface. The name of the creation template used with this class is BasicGroup; and the search template used is BasicGroupSearch. It does not have a pre-defined structural template.

AMDynamicGroup

The AMDynamicGroup interface provides the methods used to manage dynamic groups. This class extends the base AMGroup interface. Associated with this object are the following ums.xml Templates that define its behavior at runtime. The creation template used is named BasicDynamicGroup; and the search template used is named as BasicDynamicGroupSearch. It does not have a pre-defined structural template.

AMAssignableDynamicGroup

The AMAssignableDynamicGroup interface provides the methods used to manage assignable dynamic groups. This class extends the base AMGroup interface. Associated with this object are the following ums.xml Templates that define its behavior at runtime. The creation template used is named BasicAssignableDynamicGroup; and the search template used is named BasicAssignableDynamicGroupSearch. It does not have a pre-defined structural template.

AMRole

The AMRole interface provides the methods used to manage roles. Associated with this object are the following ums.xml Templates that define its behavior at runtime. The creation template used is named BasicManagedRole; and the search template used is named BasicManagedRoleSearch. It does not have a pre-defined structural template.

AMUser

The AMUser interface provides the methods used to manage users. Associated with this object are the following ums.xml Templates that define its behavior at runtime. The creation template used is named BasicUser; and the search template used is named BasicUserSearch. It does not have a pre-defined structural template.

AMTemplate

The AMTemplate interface represents a service template associated with a AMObject. Identity Server distinguishes between virtual and entry attributes. Per Sun ONE Directory Server terminology, a virtual attribute is an attribute not physically stored in an LDAP entry but still returned with it as a result of a LDAP search. Virtual attributes are analogous to inherited attributes. Entry attributes are non-inherited attributes.

---

Note	More information on virtual attributes can be found in "Virtual Attribute" of Appendix B "Directory Server Concepts."

---

For AMOrganization, AMOrganizationalUnit and AMRole, virtual attributes can be grouped in a Template on a per-service basis; there may be one service Template for each service for any given AMObject. Such templates determine the service attributes inherited by the users within the scope of this object. There are three types of templates: POLICY_TEMPLATE, DYNAMIC_TEMPLATE and ORGANIZATION_TEMPLATE. POLICY_TEMPLATE and DYNAMIC_TEMPLATE are implemented using CoS Templates; ORGANIZATION_TEMPLATE does not have virtual attributes.

Template Priority
When any object inherits more than one template for the same service (by virtue of being in the scope of two or more objects with service templates), the conflict is resolved through template priorities. In this priority scheme, zero is the highest possible priority with the lower priorities extending towards infinity. Templates with higher priorities will be favored over and to the exclusion of templates with lower priorities. Templates which do not have an explicitly assigned priority are considered to have the lowest priority possible, or no priority. In the case where two or more templates are being considered for inheritance of an attribute value, and they have the same (or no) priority, the result is undefined, but does not exclude the possibility that an arbitrarily chosen value will be returned.

AMStoreConnection

The AMStoreConnection class represents a connection to the Identity Server data store; the Identity Server data store is the Directory Server. This class controls and manages access to the Directory Server by providing methods to create, remove and get different types of identity-related objects. A SSOToken is required in order to instantiate a AMStoreConnection object.

The SDK And Cache

Caching in the Identity Server SDK is used for storing all AMObject attributes (i.e., attributes of identity-related objects) that are retrieved from the Directory Server. The cache does not hold AMObject directly, only its attributes. All attributes retrieved from the Directory Server using the interface methods AMObject.getAttributes(), AMObject.getAttribute(String name) or AMObject.getAttributes(setAttributeNames) will be cached.

Cache Properties

The following cache properties can be configured by accessing the AMConfig.properties file. They are:

• com.iplanet.services.stats.state—Depending on whether this property is set to file or console, the cache statistics will be printed to either a amSDKStats file or the Identity Server console.

• com.iplanet.services.stats.directory—The value of this property is the directory in which the amSDKStats file is created.

• com.iplanet.am.statsInterval—The interval at which cache statistics are printed can be specified as the value of this property. It indicates the number of seconds after which the stats will be printed. For example, a value of 3600 would cause the cache statistics to be printed after 3600 seconds. This will be used only if com.iplanet.services.stats.state is set to file or console.

Table 5-1 is explains the information that is recorded in the statistics files.

Table 5-1    Recorded Cache Properties

Information Name	What is recorded
Interval	Number of get requests during the specified interval
Hits during interval	Number of hits during the specified interval
Hit ratio for this interval	Hit ratio for the specified interval
Total number of requests	Overall number of get requests since a server re-start
Total number of Hits	Overall number of hits since a server re-start
Overall Hit ratio	Overall hit ratio since a server re-start

Installing the SDK Remotely

It is possible for an external application to perform management functions on the Identity Server data store (Directory Server) without installing the full Identity Server application at the external location. By installing the SUNWamsdk package using the pkgadd utility and answering NO to the first question, "Install the remote client only", the full SDK will be installed. Answering YES, the Identity Server SDK can be installed on a non-Identity Server machine.

amEntrySpecific.xml

---

The purpose of the amEntrySpecific.xml service file is to define the attributes that will display on the Create, Properties and Search pages specific to each of the Identity Server abstract objects. Each Identity Server abstract object can have its own schema definition in the amEntrySpecific.xml file which is based on the sms.dtd as described in Chapter 6 "Service Management."

amEntrySpecific.xml Schema

Each abstract object can have a schema defined in the amEntrySpecific.xml file. The schema defines what attributes will be displayed on the function pages used to manage abstract type objects:

• Create—The Create page is displayed when the administrator clicks New.

• Properties—The Properties Page is displayed when the Properties icon (an arrow in a box) next to an abstract type object is clicked.

• Search—The Search link is in the top left frame of the Identity Server console.

If a service developer wants to customize these Identity Server function pages for any of the abstract objects, they would need to modify the amEntrySpecific.xml. For example, to display an attribute on the group page, the new attribute needs to be added to the amEntrySpecific.xml file. Any abstract object with customized attributes in the Directory Server would need to have those attributes reflected in the amEntrySpecific.xml file also. (Most often, a service developer would only be customizing the organization pages.) Code Example 5-1 is the organization attribute subschema that defines the display of an organization's Organization Status and its choice values.

---

Code Example 5-1    Organization Subschema of amEntrySpecific.xml

<AttributeSchema name="inetdomainstatus"

type="single_choice"

syntax="string"

any="optional|filter"

i18nKey="o2">

<ChoiceValues>

<ChoiceValue>Active</ChoiceValue>

<ChoiceValue>Inactive</ChoiceValue>

</ChoiceValues>

</AttributeSchema>

</SubSchema>

...

If the type attribute is not specified in amEntrySpecific.xml, the defaults will be used. A default setting means that only the name of the entry will display on the object function pages in the Identity Server console.

All the attributes listed in the schema definitions in the amEntrySpecific.xml file are displayed when the abstract type object pages are displayed. If the attribute is not listed in a schema definition in the amEntrySpecific.xml file, the Identity Server console will not display the attribute. For additional information on the Identity Server abstract objects and marker object classes, see the Sun ONE Identity Server Installation and Configuration Guide.

---

Note	The User service is not configured in the amEntrySpecific.xml file but in its own amUser.xml file.

---

Management Sample Functions

---

Following are several samples that illustrate identity management functions using the Identity Server.

Create, Delete Or Modify Users

Users can be created, deleted or modified can be accomplished using the SDK. There is an interface that can be called for any SDK user creation, deletion, or modification. The property com.iplanet.am.sdk.userEntryProcessingImpl should be set to the implementation in AMConfig.properties.

---

Code Example 5-2   

public interface AMUserEntryProcessed {

/**

* Method which gets invoked whenever a user is created

* @param token the SSOToken

* @param userDN the DN of the user being added

* @param attributes a map consisting of attribute names and

* a set of values for each of them

*/

public void processUserAdd(SSOToken token, String userDN,

Map attributes);

}

Create Organization

The following code sample creates a new organization with one user by opening a connection to the Directory Server with AMStoreConnection. A new top organization (newtoporg.com) is then created with its own attributes. User John Smith is also created as a member of the new organization.

---

Code Example 5-3    Create New Organization And One User  

...

// instantiate a store connector from SSO Token

AMStoreConnection amsc = new AMStoreConnection(ssoToken);

// create a new top level organization without non-default attributes

AMOrganization org = amsc.createTopOrganization("newtoporg.com", new HashMap());

// set attribute for the newly created organization

org.setStringAttribute("description", "organization description");

// save new attribute to the organization object

org.store();

// create new user "john" with "cn", "sn" attribute

// Map to hold all users to be created, key is the string value for user naming attribute,

// value is a Map which contains all the initial values for the user

Map usersMap = new HashMap();

// Map to hold attributes for the user

Map attrsMap = new HashMap();

// set cn = John Smith

Set values = new HashSet();

values.add("John Smith");

attrsMap.put("cn", values);

// set sn = Smith

values = new HashSet();

values.add("Smith");

attrsMap.put("sn", values);

// set put user john in the usersMap with "cn" & "sn" specified above

usersMap.put("john", attrsMap);

// create user john in the organization

Set users = org.createUsers(usersMap);

...

Retrieve Templates

The following code sample retrieves a service's dynamic templates by opening a connection to the Directory Server with AMStoreConnection. It retrieves a service's dynamic template by defining the DN of the top organization (toporg.com) as well as the string attribute of the specific service to be retrieved.

---

Code Example 5-4    Retrieve Service's Dynamic Template  

...

// instantiate a store connector from SSO Token

AMStoreConnection amsc = new AMStoreConnection(ssoToken);

// retrieve top level organization by DN

AMOrganization org = amsc.getOrganization("o=toporg.com,o=isp");

// retrieve Dynamic type AMTemplate for iPlanetAMSessionService

AMTemplate template = org.getTemplate("iPlanetAMSessionService", AMTemplate.DYNAMIC_TEMPLATE);

// retrieve attributes

String maxSessionTime = template.getStringAttribute("iplanet-am-session-max-session-time ");

...

Create Users With Modified LDAP Schema

There might be a need to modify the Directory Server schema in order to create users with non-default object classes. Here are the steps to create users with extended object classes:

1. Modify Directory Schema with the new set of attributes and object classes.

   For more information on this function, see the Sun ONE Directory Server documentation.

2. Write a new XML service file which contains the definitions for the new object classes and attributes.

   When writing this file, the object classes should be defined under the Global element and the attributes should be defined under the User element. More information can be found in Chapter 6 "Service Management."

3. Write a new module configuration properties file.

   This file contains the key-value pairs for the internationalization keys used in the file created in Step 2. More information can be found in "Configuring Module Credential Requirements" of Chapter 3 "Authentication Service."

4. Load the two files using the amadmin command line interface.

   More information on this tool can be found in the Sun ONE Identity Server Administration Guide.

5. Restart the Directory Server and Identity Server.

6. Register the new service to the desired organization using the Console.

   For getting more details about registering a new service, refer to the Sun ONE Identity Server Administration Guide.

7. Select the new service to create a user with the additional object classes.

   When creating new user there is an option to select the newly configured service.

   
   

   ---

   Note

   Instead of creating a new XML service file, amUser.xml can be modified. In this case, un-register the old amUser service, modify the file and re-register the modified service. Key-value pairs still need to be included in the amUser.properties file for newly defined internationalization keys. ums.xml does not need to be modified for this option.

   ---