Sun Java System Access Manager 6 2005Q1 Developer's Guide |
Chapter 7
Identity ManagementThe 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:
OverviewThe 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 ObjectsAccess Manager defines and manages the following identity-related objects:
- Organizational Units (referred to as containers in the console)
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:
- sunManagedOrganization
- iplanet-am-managed-org-unit
- iplanet-am-managed-people-container
- iplanet-am-managed-group-container
- iplanet-am-managed-person
- iplanet-am-managed-static-group
- iplanet-am-managed-group
- iplanet-am-managed-assignable-group
- iplanet-am-managed-filtered-group
- iplanet-am-managed-role
- iplanet-am-managed-filtered-role
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.xmlThe 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.
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.
- 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 Relative Distinguished Name (RDN) for the object. RDN is "ou=People" or "cn=ContainerDefaultTemplateRole". For the core structure templates such as Organization or OrganizationaUnit, the value defined at run time (when you create Org's or containers from console or CLI). Thats why you don't see the RDN value for the core ones. Where as for others such as PeopleContainer & DefaultOrgRole, you see the RDN's. You can specify the RDN values for the PeopleContainers, Groups that can be created. A note of caution that the naming attribute specified in the RDN, for example ou from ou=Groups should match the naming attribute defined in the Group Creation template. For example, an organization has o=org as its naming attribute while a people container uses ou=People.
- childNode—This attribute specifies the child nodes (roles, groups, containers) that will be created in tandem with the object. The value is the name of the structure template for the respective object.
- template—This attribute specifies the name of the Creation template used to create this object.
- filter—This attribute is not currently used.
- priority—For internal use only, the value of this attribute should always remain 0.
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.
- name—This attribute defines the type of object that the template will create. It is also the name of the template itself. This attribute should not be modified.
- javaclass—This attribute defines the name of the Java class used to instantiate the object. This attribute should not be modified.
- required—This attribute defines the required LDAP object classes and attributes for the object.
- optional—This attribute defines the optional LDAP object classes and attributes for the object.
- validated—This attribute is reserved for future use.
- namingattribute—This attribute specifies the LDAP attribute used to name the object. For instance, the Basic User creation template has as its namingattribute the value of the LDAP attribute, uid.
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.
- name—This attribute defines the name of the search template.
- searchfilter—This attribute defines the value the search will look for.
- attrs—This attribute specifies the LDAP attributes that need to be returned.
Note
For a listing of interfaces applicable to each identity-related objects, see amEntrySpecific.xml.
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.
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.
amEntrySpecific.xmlThe 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.
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.
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 SDKThe 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:
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.
- 490=The user creation email subject can be defined with this key. The default is WARNING: user creation notice.
- 491=The user deletion email subject can be defined with this key. The default is WARNING: user deletion notice.
- 492=The user modification email subject can be defined with this key. The default is WARNING: user modification notice.
- 493=The user creation email body text can be defined with this key. The default is user is created: followed by the DN of the user.
- 494=The user deletion email body text can be defined with this key. The default is user is deleted: followed by the DN of the user.
- 495=The user modification email body text can be defined with this key. The default is user is modified: user_DN. attribute is changed: attribute old_value: original_value new value: modified_value
- 497=The entity from which the email comes is defined with this key. The default is Identity-Server.
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
- Get AMStoreConnection object to connect to the data store.
- From the AMStoreConnection, get AMPeopleContainer object where the users will be created.
- In AMPeopleContainer object, create users.
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
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 SamplesAccess 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.