Sun Java logo     Previous      Contents      Index      Next     

Sun logo
Sun Java System Access Manager 6 2005Q1 Developer's Guide 

Chapter 7
Identity Management

The Identity Management module of Sun Java™ System Access Manager 6 2005Q1 contains an XML template file and application programming interfaces (APIs) that provide the functionality to, among other operations, create, delete and manage identity entries in the Sun Java System Directory Server used for data storage. This chapter offers information on these identity-related features. It contains the following sections:

Overview

The Identity Management module allows for the management of Identity-related Objects using the Access Manager console or command line tools. These objects, that are created and managed via Access Manager, are actually stored as LDAP entries in Directory Server. To bridge the gap between the two products, Access Manager provides interfaces that are used to create and delete identity-related objects as well as get, add, modify, or remove their attributes.

Access Manager Console

All aspects of the Access Manager console are covered in Chapter 3, "The Access Manager Console," of this manual and the Sun Java System Access Manager Administration Guide.

ums.xml

This file defines a set of templates that contain the configuration information needed to set up each identity-related object created with Access Manager as an LDAP entry in the Directory Server data store. More information on ums.xml can be found in Object Templates And ums.xml.

Identity Management Software Development Kit (SDK)

The SDK is used to integrate the management functions of Access Manager into external applications or services. More information on the SDK can be found in Identity Management SDK.

Identity-related Objects

Access Manager defines and manages the following identity-related objects:

These identity-related objects are not LDAP objects as defined in the Directory Server schema. These objects are configured using an Access Manager schema, managed using the Access Manager application and only stored in Directory Server. In other words, an identity-related object in Access Manager does not necessarily correspond to its LDAP counterpart in Directory Server. But, because they are stored in Directory Server, these Access Manager objects must be mapped to the existing Directory Server schema. Thus, Access Manager object entries are appended with marker object classes.

Marker Object Classes

An identity-related object stored in Directory Server is identified as such through the use of special marker object classes appended to its LDAP entry. These object classes are defined in the Access Manager schema, ds_remote_schema.ldif, located in IdentityServer_base/SUNWam/ldif. When a marker object class is added to a Directory Server entry, Access Manager is able to access and manage that entry using its console or command line tools. For example, an enterprise’s existing directory schema may use organizational unit as its root rather than the default organization; by adding the Access Manager organization marker object class, sunManagedOrganization, to the LDAP entries of the organizational unit, Access Manager can manage it as the organization’s root. It is through the use of marker object classes that Access Manager can manage most existing directory structures. The marker object classes are:

For information on how to configure an existing directory tree within Access Manager, see the Sun Java System Access Manager Migration Guide.

Identity-related Objects As LDAP Entries

Following is a discussion of the Access Manager objects and how they map to LDAP entries in Directory Server.

Organizations

Represented by the marker object class sunManagedOrganization, organization is the root entry of an Access Manager tree. It generally maps to an LDAP organization or organizationalUnit object class.

Containers

Functionally, there are three types of containers in Access Manager.

Organizational Units

Represented by the marker object class iplanet-am-managed-org-unit, an organizational unit is referred to as a container in the Access Manager console. It generally maps to the LDAP organizationalUnit object class and can contain sub-organizations, other containers, roles, groups, and users.

People Containers

Represented by the marker object class iplanet-am-managed-people-container, a people container is an organizational unit which is a parent for user entries. It generally maps to the LDAP organizationalUnit object class and can contain sub-people containers and users.

Group Containers

Represented by the marker object class iplanet-am-managed-group-container, a group container is an organizational unit which is a parent for any number of group entries. It generally maps to the LDAP organizationalUnit object class and can only contain groups and other group containers.

Users

Represented by the markerobject class iplanet-am-managed-person, a user is the representation of a person. It maps to an LDAP inetOrgPerson. It is a leaf node that may not contain other entries.

Groups

Functionally, there are three types of groups in Access Manager. Assignable Groups (Dynamic) (by default) and Static Groups are configured using the Membership By Subscription option in the console. Filtered Groups are configured by choosing the Membership By Filter option in the console.

Assignable Groups (Dynamic)

Represented by the marker object class iplanet-am-managed-assignable-group, an assignable group is one in which an administrator wants to explicitly add the user to a group. For example, Larry wants to give Ramona permission to look at his employees’ telephone numbers so he adds her to the ReadPhoneNumbers group. In Directory Server, member entries contain the memberof LDAP attribute (inetAdmin object class) and the group membership is dynamically established.

Note

Assignable groups are referred to as Dynamic when seen in the console as, technically, they are created with an LDAP filter albeit a static one.

Static Groups

Represented by the marker object class iplanet-am-managed-static-group, a static group is one in which members are added by appending the groupOfUniqueNames object class to the LDAP group entry itself. It can contain users, filtered groups or other static sub-groups. This type of group can be enabled using the Administration Service in the console. By default, it is disabled and all groups created are of the type Assignable Groups (Dynamic).

Filtered Groups

Represented by the marker object class iplanet-am-managed-filtered-group, a filtered group is created through the use of an LDAP filter. All user entries are funneled through the filter and dynamically assigned to the group. The filter would look for a specified attribute in an entry and return those entries that contain the attribute as a member of the group.

Roles

Functionally, there are two types of roles in Access Manager. Roles can only be created in organizations, suborganizations and generic containers; they can not be configured in people containers.

Static Roles

Represented by the marker object class iplanet-am-managed-role, a static role is a role entry in which the members are added by appending the groupOfUniqueNames object class to the role entry itself. It can contain users.

Filtered Roles

Represented by the marker object class iplanet-am-managed-filtered-role, a filtered role is created through the use of an LDAP filter. All user entries are funneled through the filter and dynamically assigned to the role. The filter would look for a specified attribute in an entry and return those entries that contain the attribute as a member of the role.

Object Templates And ums.xml

The ums.xml provides a set of parameters, or templates, that contain the LDAP configuration information for all Identity-related Objects managed using Access Manager. The templates are used to create LDAP entries for the identity-related objects so they can be stored in Directory Server. In addition, the templates are used for the dynamic generation of roles and the construction of object searches. The file can be found in the IdentityServer_base/SUNWam/config/ums directory; it is based on the sms.dtd which is defined in Chapter 8, "Service Management," of this manual.

Note

These templates can be modified by administrators to alter the behavior of the Java interfaces. But, if ums.xml is modified and reloaded, there will be inconsistencies between the entries created prior to the modifications and the newer ones.

Structure Of ums.xml

The ums.xml defines three types of templates: Structure, Creation and Search. Structure templates define the Directory Server information tree 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 Access Manager object will take within the Directory Server information tree. In other words, these templates define the child nodes (roles, groups, containers) that are created IN ADDITION to the creation of the object itself. There are six attributes that need to be defined for each object’s structure.

Creation Templates

Every identity object that Access Manager 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 object’s template.

Search Templates

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

Modifying ums.xml

Any LDAP attributes or object classes not already present in the Directory Server LDAP schema must be added to the ums.xml file in order for them to be recognized by the Access Manager. 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 employeeNumber attribute, the ums.xml file does not need to be modified because this attribute already exists in the inetorgperson object class. Generally, the ums.xml file does not need to be modified. Some circumstances where this file would need to be modified are:

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 Java System Access Manager Migration Guide.

Caution

It is recommended that the ums.xml configuration file be backed up before any modifications are made.

Adding Custom Object Classes

If a service developer wants to add new or customized object classes to the Directory Server for Access Manager’s use, they would need to modify the templates in the ums.xml file. The DAI Service would then need to be deleted from Directory Server and the modified ums.xml reloaded using the amadmin command line tool.

Once ums.xml has been modified, the new object classes and attributes must be defined in an XML service file which would then be imported into Access Manager using the procedures described in Chapter 8, "Service Management," of this manual. This configures Access Manager to manage the new object classes from the console.

Note

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

DAI Service

When Access Manager is installed, the ums.xml file is stored in Directory Server as the Directory Access Instructions (DAI) service. The DAI service is only available for modification through the Directory Server; it is not available through the Access Manager console or command line interface. The Access Manager SDK gets the configuration information from this directory tree node, when needed, to create an identity-related object or perform a search. Any attribute specified in the ums.xml can be set for a created object. If ums.xml is modified, the DAI Service would need to be deleted from Directory Server and reloaded using the amadmin command line tool. To delete the DAI Service from Directory Server, delete the DAI branch (ou=DAI,ou=services,root-suffix) or use the amadmin command line tool with the -r option. To reload ums.xml, use amadmin and the -s option. (The administrator user and password options will also be used for both.) For more detailed information on the command line tools, see the Sun Java System Access Manager Administration Guide.

Note

When using the amadmin command line tool to reload ums.xml, the full DN of the amadmin user must be used as a parameter. If not, the LDAP Authentication Service will not be able to find the administrator in its search for the user DN. For example, instead of using amadmin -u amadmin -w 11111111 -s ums.xml file path, the input command would be:

amadmin -u "uid=amadmin,ou=people,dc=example_org,dc=com" -w 11111111 -s ums.xml file path

amEntrySpecific.xml

The purpose of the amEntrySpecific.xml service file is to define attributes from an existing directory to display on the Access Manager console’s functional pages for all Identity-related Objects. These functional pages are as follows:

Each object can have its own schema definition in the amEntrySpecific.xml file which is based on the sms.dtd as described in Chapter 8, "Service Management," of this manual.

Note

Dynamic attributes are not supported in amEntrySpecific.xml.

If a service developer wants to customize the console’s functional pages with attributes that are not default to the Access Manager tree, they would modify the amEntrySpecific.xml file. For example, to display an attribute on the group page, the new attribute needs to be added to the amEntrySpecific.xml file. Any 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 7-1 is the organization attribute subschema that defines the display of an organization’s Organization Status and its choice values. Note that based on the information inany Attribute, this Organization Status attribute will be displayed on the Search page and is not an attribute requiring a value for creation.

Code Example 7-1  Organization Subschema of amEntrySpecific.xml 

...

<SubSchema name="Organization">

<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 Access Manager 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 Access Manager console will not display the attribute.

Note

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

Identity Management SDK

The Access Manager SDK contains an API for identity management. These interfaces can be used by developers to integrate management functions into external applications or services that will be managed by Access Manager. The API functions 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 Directory Server.

Interfaces

Below are brief explanations of the Identity Management API.

Note

All operations performed using the API open and close LDAP connections via a connection pool. The connection pool size can be set in the serverconfig.xml file. For more information, see Appendix B, "serverconfig.xml File," in this manual.

AMAssignableDynamicGroup

The AMAssignableDynamicGroup interface provides the methods used to manage Assignable Groups (Dynamic). 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 the BasicAssignableDynamicGroup; and the search template used is the BasicAssignableDynamicGroupSearch. It does not have a pre-defined structural template.

AMCallback

AMCallBack is a plug-in class that needs to be extended by external applications in order to do special pre/post-processing for the creation, deletion and modification operations for users, organizations, roles and groups.

AMConstants

AMConstants is the base interface for all identity-related objects. It is used to define constants for use with the SDK (constants associated with searches, etc.).

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.

AMEventListener

The AMEventListener interface that can be used to monitor and react to events. This listener can be called when an identity-related object is removed, renamed or modified. It must be implemented using the following procedure:

  1. Implement the AMEventListener interface.
  2. Get an instance of the object to which AMEventListener will listen.

    3. For example, get an AMUser object and add the listener: AMUser.addEventListener().

  3. When an event changes something in this object, the listener will be called.

    4. Caution

    Access Manager does not currently support attaching an event listener to template creation code.

AMFilteredRole

The AMFilteredRole interface provides the methods used to manage Filtered Roles. Associated with this object are the following ums.xml templates that define its behavior at runtime. The creation template used is BasicFilteredRole; and the search template used is BasicFilteredRoleSearch. It does not have a pre-defined structural template.

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.

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 structural template used by this class is GroupContainer; the creation template used is BasicGroupContainer, and the search template is BasicGroupContainerSearch.

AMObject

AMObject provides basic methods to manage identity-related objects. Since this is a generic class, it does not have any templates (as defined in Object Templates And ums.xml) 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 structural template used by this class is Organization; the creation template used is BasicOrganization, and the search template is BasicOrganizationSearch.

Note

The AMOrganization interface contains methods that can be used to search through identity-related objects in Directory Server. More information can be found in Search Methods In The SDK.

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 structural template used by this class is OrganizationalUnit; the creation template used is BasicOrganizationalUnit, and 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 structural template used by this class is PeopleContainer; the creation template used is BasicPeopleContainer, and the search template is BasicPeopleContainerSearch.

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 BasicManagedRole; and the search template used is BasicManagedRoleSearch. It does not have a pre-defined structural template.

AMSearchControl

The AMSearchControl class provides a way to customize search behavior. Common behaviors are time limit, result limit and virtual list view.

Code Example 7-2  Sample Code Using AMSearchControl

SSOTokenManager manager = SSOTokenManager.getInstance();

SSOToken token = manager.createSSOToken(new

AuthPrincipal("uid=amadmin,ou=People,dc=example,dc=com"), "11111111");

suo = getSampleUserOperations(token);

amsc = new AMStoreConnection(token);

//System.out.println(suo.createUser(amsc));

AMSearchControl amc = new AMSearchControl();

amc.setTimeOut (2000);

amc.setSearchScope (AMConstants.SCOPE_ONE);

AMPeopleContainer amp =

amsc.getPeopleContainer("ou=people,dc=example,dc=com");

Set userset = (amp.searchUsers(amc, "(uid=u*)")).getSearchResults();

Object users[] = userset.toArray();

System.out.println((String)users[0]);

System.exit(0);

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.

AMStoreConnection

The AMStoreConnection class provides the means to establish a connection to the data store Directory Server and provides methods to create, remove and get different types of identity-related objects. A SSOToken is required in order to instantiate a AMStoreConnection object.

AMTemplate

The AMTemplate interface represents a service template associated with AMObject. Access Manager distinguishes between virtual and entry attributes. As defined for Sun Java System Directory Server, 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. An entry attribute is a non-inherited attributes.

Note

More information on virtual attributes can be found in Virtual Attribute of Appendix E, "Directory Server Concepts," in this manual.

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. The templates are: DYNAMIC_TEMPLATE and ORGANIZATION_TEMPLATE. DYNAMIC_TEMPLATE are implemented using CoS; ORGANIZATION_TEMPLATE does not have virtual attributes or LDAP attributes.

Template Priority

When an 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. (This conflict will only occur with services that contain Dynamic Attributes.) The priority is defined by the value of the cosQualifier Attribute as discussed in Chapter 8, "Service Management," of this manual. (The comparison values are default, override, and merge-schemes.) The priority level for a service template is set when then template is created using the Access Manager console. The levels are Highest, Higher, High, Medium, Low, Lower, and Lowest. Templates with higher priorities will be favored over templates with lower priorities when default is the value of cosQualifier. 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 merged. If the value is override, the priority level of the template takes precedence over any priority specified in the user profile. Merge-schemes signifies that the priority values will not be used, but a merged list of attribute values from all templates will be assigned. Templates which do not have an explicitly assigned priority are considered to have the lowest priority possible, or no priority.

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 BasicUser; and the search template used is BasicUserSearch. It does not have a pre-defined structural template.

Default Implementation Of AMUser

There is a default implementation of AMUser. Assuming an SSOToken and a user DN, the code to find the user status is illustrated in Code Example 7-3.

Code Example 7-3  Sample Code To Find User Status 

AMStoreConnection conn = new AMStoreConnection (ssoToken) ;

AMUser user = conn.getUser (userDN) ;

if (user.isActivated()) {

....

} else {

....

}

AMUserPasswordValidation

AMUserPasswordValidation is an interface to plugin external modules to validate user names and passwords. The methods of this class must be overridden by the implementation plugin modules. The modules will be invoked whenever a userID or password value is being added or modified using Access Manager console, the amadmin CLI or the SDK directly.

Search Methods In The SDK

The SDK provides a variety of methods to conduct searches throughout the organizational tree. They are provided within the AMOrganization interface. Criteria is needed by the API to perform a search. Typically, the criteria is a LDAP search filter string, the scope of the search (one level or sub-tree), and where the search will begin (the base DN). The SDK provides the APIs to conduct searches and obtain results for all identity objects.

Note

The SDK always includes the objectclass used to search so it is not required to explicitly include the filter. For example if searching for users, the SDK will include the default user search filter provided in the BasicUserSearch search template in the ums.xml.

This section specifically discusses one of the search methods: searchUsers. (For information on all of the search methods, refer to the Access Manager Javadocs.) Code Example 7-4 is the set of different search methods available for searchUsers.

Code Example 7-4  Available Search Methods For searchUsers

public Set searchUsers(String wildcard, int level)

throws AMException, SSOException;

public Set searchUsers(String wildcard, Map avPairs, int level)

throws AMException, SSOException;

public AMSearchResults searchUsers(String wildcard, Map avPairs, AMSearchControl searchControl)

throws AMException, SSOException;

public AMSearchResults searchUsers(String wildcard,

AMSearchControl searchControl)

throws AMException, SSOException

public AMSearchResults searchUsers(String wildcard,

AMSearchControl searchControl, String avfilter)

throws AMException, SSOException;

Search Method Parameters

Here are brief descriptions of some of the search method parameters.

AMSearchControl

This class provides a way to specify detailed search criteria such as the scope of the search, the maximum results, time out value, etc. It must be implemented for all searches to set these criteria.

wildCard

This parameter can be used to specify the wild card used for naming attributes. For example, if searching for all users whose naming attributes (uid or cn) start with "Ma", then the wild card could be Ma*.

avPair

This parameter is a map of attribute/value pairs that need to be added to a search filter. The key of the map is the attribute name and the value is a set of values. The SDK will construct a filter from this avPair map. Each of the pairs in the map will be OR ("|") and not AND (&) to construct the filter.

avFilter

In most cases it will be sufficient to OR the attributes, but this parameter provides flexibility for applications to pass their own search filter to meet search criteria. Such filters could be a complex LDAP search filter as in the following example:

(&(objectclass=iplanet-am-managed-person)((customEmployeeNumer=12*)&(customDepartment=3459932)))

This example illustrates when two conditions (the employee number and department number) need to be met. For this purpose, AND (&) is used.

Note

The methods that return a java.util.Set will throw an exception if the search fails as a result of exceeding the search limit or the time limit. In such cases, even partial results of the failed search will not be returned. To obtain the partial results in such cases, the methods that return an AMSearchResults object must be used. The error code can be verified by using the class methods to check if the search was successful.

searchUsers Sample Code

Code Example 7-5 demonstrates how to search for all users in an organization (DN: dc=example,dc=com) who belong to department 3459932 and whose user names end with smith.

Code Example 7-5  Sample Code For Search Methods 

// Note obtain a valid token of a principal who has privileges to

// perform this operation.

SSOToken token = getSSOToken();

// Create an AMStoreConnection and obtain an AMOrganization

// instance for dc=example, dc=com

AMStoreConnection amc = new AMStoreConnection(token);

AMOrganization amOrg = amc.getOrganization("dc=example,dc=com");

// Construct the search filter

// Need to retrieve all usernames ending with smith

String wildCard = "*smith"

Map avPair = new HashMap();

Set departmentValue = new HashSet();

departmentValue.add("3459932");

avPair.put("customDepartment", departmentValue);

// Set the search control

AMSearchControl = new AMSearchControl();

// Sub tree search

searchControl.setSearchScope(AMConstants.SCOPE_SUB);

// Time out 3000 milliseconds.

searchControl.setTimeOut(3000);

// Would like to get only first 100 results

searchControl.setMaxResults(100);

// Perform the search

AMSearchResults results = amOrg.searchUsers(wildcard, avPair,

searchControl);

// Check if any time out or size limit errors occured.

if (results.getErrorCode == AMSearchResults.SUCCESS) {

// Process the results

} else {

// Verify the error condition and take appropriate action

}

Here the filter to conduct the search will look like:

(&(uid=*smith)(objectclass=inetorgperson)((customerDepartment="3459932")))

To add an additional department, one more value can be added to the search as in:

(&(uid=*smith)(objectclass=inetorgperson)((customerDepartment="3459932")|(customerDepartment="3459933")))

Search Groups Sample Code

Code Example 7-6 uses interfaces from the com.iplanet.am.sdk package to search groups.

Code Example 7-6  Search Groups Code Sample

try {

Set orgSet1 = new HashSet();

Set orgSet2 = new HashSet();

Set orgSet3 = new HashSet();

Set orgSet4 = new HashSet();

AMSearchResults results = null;

AMSearchControl ctl = new AMSearchControl(); //use default values

String DN = "ou=Groups,dc=idp1,dc=com";

AMOrganizationalUnit org = conn.getOrganizationalUnit(DN);

if (org.isExists()) {

//get all groups in this OU:

orgSet1 = org.getAssignableDynamicGroups(AMConstants.SCOPE_SUB); //get Assignable Dynamic Groups

orgSet2 = org.getDynamicGroups(AMConstants.SCOPE_SUB); //get Dynamic Groups

orgSet3 = org.getStaticGroups(AMConstants.SCOPE_SUB); //get Static Groups

//set up the avPairs for the search on attribute within group

Map avPairs = new HashMap();

Set set = new HashSet(1);

set.add("true");

avPairs.put("iplanet-am-group-subscribable", set);

results = org.searchAssignableDynamicGroups( "*", avPairs, ctl ); //returns all subscribable groups

orgSet4 = results.getSearchResults();

}

//Print the results

return "Assignable Dynamic Groups: " + orgSet1.toString() +

"Dynamic Groups: " + orgSet2.toString() +

"Static Groups: " + orgSet3.toString() +

"Group with subscribable=true:" + orgSet4.toString();

} catch (Exception ex) {

ex.printStackTrace();

return "got errors";

}

Email Notification And The SDK

amProfile.properties is the localization file for the SDK. All strings that may be visible via an error message or a feature are stored in this file as key=value pairs. The file itself is located in IdentityServer_base/SUNWam/locale. Although all of the properties are not discussed in this section, there are some worth noting that pertain to email notification. The Administration Service has a number of notification attributes: User Creation, User Deletion and User Modification notification lists. When a user profile is created, deleted or modified, a notification email will be sent to the addresses listed as values of these attributes. To modify the message that is sent, the following key=value pairs in amProfile.properties need to be modified.

More information on the Administration Service and the notification attributes themselves can be found in the Sun Java System Access Manager Administration Guide.

Caching And The SDK

Caching in the Identity Management SDK is used for storing all AMObject attributes (For example, attributes of identity-related objects) that are retrieved from Directory Server. The cache does not hold AMObject directly, only its attributes. All attributes retrieved from Directory Server using the methods AMObject.getAttributes(), AMObject.getAttribute(String name) or AMObject.getAttributes(setAttributeNames) will be cached. Table 7-1 contains a listing of the recorded cache properties.

Table 7-1  Recorded Cache Properties

Information Name

What is recorded

Number of requests during this interval

Number of get requests during the specified interval

Number of cache hits during this interval

Number of hits during the specified interval

Hit ratio for this interval

Hit ratio for the specified interval

Total number of requests since server start

Overall number of get requests since a server re-start

Total number of cache hits since server start

Overall number of hits since a server re-start

Overall Hit ratio

Overall hit ratio since a server re-start

Total Cache Size

The total size of the cached information

Cache properties can be configured by modifying attributes in the AMConfig.properties file. For more information see SDK Caching of Appendix A, "AMConfig.properties File," in this manual.

Installing The SDK Remotely

It is possible for an external application to perform management functions on the Directory Server without installing the full Access Manager application at the external location. By installing the SUNWamsdk package using the pkgadd utility (or the installer), the Identity Management SDK can be installed on a non-Access Manager machine. For more details on the Identity Management SDK only installation option, refer to the Java Enterprise System Installation Guide.

Note

If the SUNWamsdk package is installed remotely and Access Manager is running in SSL mode, a certificate database needs to be created. Create the database using the Sun Java System Web Server command line tool certutil or the Web Server console and then copy the database to the remote machine. For more information, see the Sun Java System Web Server documentation set.

Management Function Samples

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

Note

Access Manager can authenticate and authorize against directories other than Sun Java System Directory Server (for example, Microsoft™ Active Directory), but Access Manager can not perform management functions against these directories such as creating users or deleting organizations.

Creating Objects

Typically, three steps are involved in creating an object with the SDK. The following three steps are specific to creating users but can be modified for any object.

To Create A User
  1. Get AMStoreConnection object to connect to the data store.
  2. From the AMStoreConnection, get AMPeopleContainer object where the users will be created.
  3. In AMPeopleContainer object, create users.

    4. Code Example 7-7  Sample Code To Create A User 

    /**

    * This method will describe the SDK usage for creating a user.

    * It uses AMStoreConnection to get the organization object

    * It also uses the Set Parameters to store the different

    * attributes of the user. It throws

    * an AMException if it's unble to create it and we throw

    * message "unable to create" to the GUI by catching the same

    */

    public String createUser(HttpServletRequest req, Set parameters, AMStoreConnection conn) {

    try {

    Map userAttributeMap = new HashMap();

    if (parameters.contains("uid")) {

    uid = req.getParameter("uid");

    storeUserAttributes("uid", uid, userAttributeMap);

    }

    if(parameters.contains("firstname")) {

    firstName = req.getParameter("firstname");

    storeUserAttributes("givenname", firstName, userAttributeMap);

    }

    if(parameters.contains("lastname")) {

    lastName = req.getParameter("lastname");

    storeUserAttributes("sn", lastName, userAttributeMap);

    }

    if(parameters.contains("password")) {

    passWord = req.getParameter("userPassword");

    storeUserAttributes("userPassword", passWord, userAttributeMap);

    }

    Map userMap1 = new HashMap();

    userMap1.put(uid, userAttributeMap);

    String orgDN = req.getParameter("orgName");

    String dn = "ou=People" + "," + orgDN;

    AMPeopleContainer ampc = conn.getPeopleContainer(dn);

    ampc.createUsers(userMap1);

    userDN = "uid=" + uid + "," + dn;

    /*

    * This is to keep the context of the user

    */

    contextUser = conn.getUser(userDN);

    return showCreateUserSuccess();

    } catch (Exception ex) {

    ex.printStackTrace();

    return "Unable to create";

    }

To Create An Organization
  1. Get AMStoreConnection object to connect to the data store.
  2. From the AMStoreConnection, get AMOrganization object for the top level organization.
  3. In AMOrganization object, create sub-organization.

    4. Note

    org.createUsers creates users directly under the organization. In order to create users in a people container, use the AMPeopleContainer object.

Retrieve Templates

Code Example 7-8 retrieves a service’s dynamic templates by opening a connection to 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 7-8  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("dc=toporg,dc=com");

// 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");

...

Tip

As an alternative to creating a new XML service file, amUser.xml can be modified. In this case, unregister the old amUser service file, modify it and re-register the modified file. Attribute/value pairs need to be integrated into the amUser.properties file for newly-defined internationalization keys. ums.xml does not need to be modified for this option.

Identity Management Samples

Access Manager contains samples that illustrate user management functions. These include a sample to add an attribute to the user profile and one to illustrate how to create organizations, users, roles, and services using the SDK. They can be found in IdentityServer_base/SUNWam/samples/um.

Adding User Attributes

This sample explains how to add new attributes to the User profile so that those new attributes can be managed via the user page in the Access Manager console. There are 2 ways this can be achieved: modify the existing amUser.xml, or create a new XML service file and import it into Access Manager.

Creating Objects With The SDK

This sample contains sample Java code that can be generated and run to create some identity-related objects including an organization, roles and users. The defined SampleOrgOperations.java creates an organization, gets the registered services, and adds them. SampleUserOperations.java and SampleRoleOperations.java can also be used for their respective purposes.



Previous      Contents      Index      Next     

Part No: 817-7649.   Copyright 2005 Sun Microsystems, Inc. All rights reserved.