Sun ONE Identity Server 6.1 Migration Guide |
Chapter 3
Configuring Identity Server with a Provisioned DirectoryThis chapter provides instructions for installing Sun ONE Identity Server against a directory tree that is already provisioned with user data. It also explains how to configure Identity Server to work with your directory information tree (DIT), and how to make the necessary changes to your existing Sun ONE Directory Server and directory entries. The number and scope of changes you must make will depend upon how your directory tree is structured, and how you plan to use Identity Server.
Topics in this chapter include:
Overview of Installation & Configuration TasksThere are a number of steps you must take before you will see your existing directory data in Identity Server. This chapter groups steps into two distinct phases: installation and post-installation configuration.
Installing and Starting Identity Server 6.1
- Install Identity Server 6.1.
In this step you run the Java Enterprise System installer. For detailed installation instructions, see the Java Enterprise System Installation Guide.
- Start Identity Server.
For detailed instructions, see "Starting Identity Server and Logging In" in this chapter.
Post-Installation Configuration
Detailed instructions for each of the following steps are provided in this chapter.
- Manually Configure Directory Server to work with Identity Server.
In this step you enable the Directory Server referential integrity plug-in, and create new database indexes. See "Configuring the Directory Server" in this chapter.
- Enable User Management services.
- Add Marker Object Classes to Existing Directory Entries.
Before Identity Server can recognize the data in an existing directory, you must add special object classes to entries for all organizations, groups and users that will be managed by Identity Server. Sample scripts are bundled in the product to help you automatically add these object classes to your directory. Detailed steps and examples are provided in this chapter. See "Adding Identity Server Object Classes to Existing Directory Entries".
- Add Custom Object Classes to Identity Server Schema.
If your existing directory tree contains custom object classes, Identity Server won’t recognize them until you manually configure both Identity Server and Directory Server. The types of changes you need to make are illustrated in this chapter using the directory tree for MadisonParc, a fictitious company. Detailed steps are in "Adding Custom Object Classes to Identity Server Schema".
- Load Identity Server LDIF into your directory.
In this step, you commit all of your LDIF modifications to make actual changes in the Directory Server. Detailed instructions are in "Loading Identity Server LDIF into Your Directory".
- In the Identity Server console, enable User Management.
This is the last step in the instructions for "Enabling User Management Services".
MadisonParc Examples Used in This Chapter
The MadisonParc examples in this chapter help to illustrate the kinds of manual modifications you must make in both Directory Server and Identity Server. Figure 3-1 illustrates the Directory Server console view of the directory tree for MadisonParc. The tree includes three organizational units (ou) at the top level of the tree: Groups, People, and Special Users. These organizational units contain entries for MadisonParc employees. Two organizations (dc), Customers and Suppliers, were created under the root level to contain entries for non-employees.
Figure 3-1 The existing directory tree for MadisonParc and Identity Server 6.0.
In the MadisonParc example, there are two custom object classes and three custom attributes. These object classes and attributes are not included in the Identity Server schema nor in the Directory Server 5.1 SP1 schema.Table 3-1 summarizes the custom objects and their uses in the MadisonParc directory tree.
Before a MadisonParc administrator can use Identity Server to manage these extensions, the following modifications would have to be made in the Identity Server schema:
If your existing directory tree contains custom object classes or attributes, you’ll need to make similar changes in your directory and in your Identity Server XML files.
Detailed steps and examples are provided in this chapter. See "Adding Custom Object Classes to Identity Server Schema".
Before You BeginYou resolve the following Directory Server issues before you can install Identity Server against an existing Directory Server that is provisioned with users. Refer to the documentation for Sun ONE Directory Server for detailed information about the following issues.
Migrating Pre-5.2 Versions of Directory Server
If you are using a pre-5.2 version of Directory Server, you can upgrade your existing Directory Server to version 5.2, and then migrate your existing data to the upgraded directory. For detailed instructions, see the Sun ONE Directory Server Installation and Tuning Guide at the following URL:
http://docs.sun.com/source/816-6697-10/
Backing Up Directory Server
The installation and post-installation tasks described in this chapter require numerous changes to your existing directory. Be sure to back up the Directory Server before you install running the Identity Server installation program. To back up Directory Server, use db2ldif or db2bak,or use the Directory Server console. For detailed information on backing up your directory, see the Sun ONE Directory Server Administration Guide at the following URL:
http://docs.sun.com/doc/816-6698-10
Directory Server Access
Before you run the Identity Server Installation program, be sure that Directory Server is running, and that Identity Server can access it. You must also have appropriate administrator privileges in the Directory Server to modify user entries.
Installing Identity Server User and Policy Management ServicesSee the Java Enterprise System Installation Guide for detailed instructions on installing Identity Server User and Policy Management Services. The Java Enterprise System installer will guide you to provide information about your existing provisioned directory. Once the installation program is finished, you can start Identity Server, and log in to its administration console.
Starting Identity Server and Logging InAfter you’ve installed Identity Server and configured Directory Server appropriately, you can check the installation. Start Identity Server and log in to the Identity Server Console as the user amAdmin. Once you successfully log in, you’ll see the Identity Server web interface.
To Start Identity Server
- Start Directory Server.
Execute the start or restart command in the directory where the Directory Server instance is installed. Examples:
- Start the web container that runs Identity Server.
If the web container is Sun ONE Web Server, then execute the start command in directory were the Web Server instance is installed. Examples:
If the web container is Sun ONE Application server, then execute the start command in the directory where the Application Server instance is installed. Examples, where server1 is the instance name by default:
If the web container is BEA WebLogic or IBM WebSphere, then see the instructions for starting the server in the documentation that comes with the product.
To Log into the Identity Server Console
- Go to the login URL using the form:
http://host.domain:port/amserver/UI/Login
where host is the host name of the system, domain is the domain name of the server that runs Identity Server services, and port is the Identity Server services port number.
Example: http://ginac.sun.com:58080/amserver/UI/Login
- In the Login page, enter the Top-Level Administrator user name amAdmin, and then enter the password you specified at installation.
The Policy Management services are automatically installed against your existing provisioned directory. When you see the Identity Server interface (see Figure 3-2), you can immediately begin creating policies. See the Identity Server Administration Guide for more information. You will see the root suffix and organizations you specified during installation. For the MadisonParc example used at the beginning of this chapter, you would see the root suffix MadisonParc, and the two organizations Customers and Suppliers.
Figure 3-2 First-time login for MadisonParc
.
.
Note
You will not see directory entries below the organization level until you complete the post-configuration tasks described in the following sections:
Also immediately after Installation, if you look in the Directory Server console view, you’ll see the Identity Server object classes, roles, users, and services Figure 3-3. illustrates the Identity Server objects and existing directory tree for the MadisonParc examples used in this chapter.
Figure 3-3 Policy Management services installed against the existing MadisonParc directory tree.
Configuring the Directory ServerAfter you’ve installed the Identity Server schema, you must configure the Directory Server to work with Identity Server. Perform the steps in the following procedures:
When the referential integrity plug-in is enabled, it performs integrity updates on specified attributes immediately after a delete or rename operation. This ensures that relationships between related entries are maintained throughout the database. Database indexes enhance the search performance in Directory Server.
To Enable the Referential Integrity Plug-In
The plug-in is not enabled until you restart Directory Server.
To Add Identity Server Indexes
- In Directory Server console, click Configuration.
- Add the nsroledn index.
- In the navigation tree, double-click the Data icon, and then click the root suffix that contains the directory entries you want to use in Identity Server.
- Click the Indexes tab.
- Under “Additional Indexes,” for the nsroledn attribute, check the following checkboxes: Equality, Presence, and Substring.
- Click Save.
- In the “Indexes” window, after the index is successfully created, click Close.
- Add the memberof index.
- In the Indexes tab, click "Add attribute..."
- In the “Select Attributes” window, select the attribute memberof, and then click OK.
- In the Indexes tab, for the memberof attribute, check the following checkboxes: Equality and Presence.
- Click Save.
- In the “Indexes” window, after the index is successfully created, click Close.
- Add the iplanet-am-static-group index.
- In the Indexes tab, click "Add attribute..."
- In the “Select Attributes” window, select the attribute iplanet-am-static-group, and then click OK.
- In the Indexes tab, for the iplanet-am-static-group attribute, check the following checkbox: Equality.
- Click Save.
- In the “Indexes” window, after the index is successfully created, click Close.
- Add the iplanet-am-modifiable-by index.
- In the Indexes tab, click "Add attribute..."
- In the “Select Attributes” window, select the attribute iplanet-am-modifiable-by, and then click OK.
- In the Indexes tab, for the iplanet-am-modifiable-by attribute, check the following checkbox: Equality.
- Click Save.
- In the “Indexes” window, after the index is successfully created, click Close.
- Add the iplanet-am-user-federation-info-key index.
- In the Indexes tab, click "Add attribute..."
- In the “Select Attributes” window, select the attribute iplanet-am-user-federation-info-key, and then click OK.
- In the Indexes tab, for the iplanet-am-user-federation-info-key attribute, check the following checkbox: Equality.
- Click Save.
- In the “Indexes” window, after the index is successfully created, click Close.
- Restart Directory Server.
Enabling User Management ServicesThis section provides an overview of the configuration tasks you’ll need to perform in order to see your existing user data displayed in the Identity Server interface. If you want to enable user management before proceeding with the configuration tasks, first log in to Identity Server, and then skip to step Step 8 this section. Note that if you skip to step Step 8 without performing the necessary configuration, although you will be able to create and manage new user entries, you will not be able to access your existing data through Identity Server.
To enable User Management Services
- Add Identity Server object classes and attributes to your existing DIT.
For detailed instructions, see "Adding Identity Server Object Classes to Existing Directory Entries" in this chapter.
- Modify the Identity Server schema.
See "Adding Custom Object Classes to Identity Server Schema" in this chapter for more information. The section provides detailed instructions on performing the following steps:
- To load all XML files, enter the following command:
Identity_Server_root/config/ums/amserveradmin
"user_naming_attibute=amadmin,ou=people,root_suffix" password- Load installExisting.ldif file into your Directory Server.
For detailed instructions, see "Loading Identity Server LDIF into Your Directory" in this chapter.
- Load install.ldif file into your Directory Server.
For detailed instructions, see "install.ldif" in this chapter.
- Restart Identity Server. To start Identity Server services, you must start both Directory Server and the web container that runs Identity Server.
- Start Directory Server.
Execute the start or restart command in the directory where the Directory Server instance is installed. Examples:
UNIX
DirectoryServer_base/slapd-instanceName/slapd-start
Windows
C: DirectoryServer_base\slapd-instanceName\slapd-start.bat
- Start the web container that runs Identity Server.
- If the web container is Sun ONE Web Server, then execute the start command in directory were the Web Server instance is installed. Examples:
- If the web container is Sun ONE Application server, then execute the start command in the directory where the Application Server instance is installed. Examples, where server1 is the instance name by default:
- If the web container is BEA WebLogic or IBM WebSphere, then see the instructions for starting the server in the documentation that comes with the product.
- Log in to Identity Server console as amAdmin.
You will not see your existing groups and users from your existing directory tree until you complete the following two steps.
- In the Identity Server console, click Service Management > Administration.
- In the “Administration“ window, click the "Enable User Management" box, and then click Save.
Once you’ve checked the “Enable User Management” box, you should see all entries beneath the organization level in Identity Server. For instructions on using Identity Server to create or manage users and policies, see the Administration Guide.
Figure 3-4 Identity Server with data from existing MadisonParc directory tree
Adding Identity Server Object Classes to Existing Directory EntriesAfter you’ve installed configured Identity Server, you must modify your existing directory entries to include the necessary Identity Server object classes and attributes. You can think of the Identity Server object classes as markers that indicate the directory entries you want to manage through Identity Server. These markers enable Identity Server to recognize the entries in your directory. The object classes contain special attributes that are necessary to achieve delegated administration.
Before You Begin
There are a number of resources you can use to facilitate the remaining steps for using an existing directory.
Examples Used in This Section
The examples used in this chapter are based on the directory tree for a fictitious company named MadisonParc. Figure 3-5 shows two organizations, Customers and Suppliers, under the root.
Utilities and Scripts You Can Use
You can make these modifications by using Sun ONE Directory Server Console, or by using the ldapmodify or db2ldif utilities that come with Directory Server. You can also use the sample scripts that come with Identity Server.
Directory Server Utilities
Make sure that you’re using the appropriate version of ldapmodify. Set your path to use the ldapmodify command that is shipped with Sun ONE Directory Server. (Do not use the version shipped with Solaris, which is found in /bin or /usr/bin.) Follow these procedures:
Open a DOS prompt window and set the path to the ldapmodify tool.
Example:
set PATH=IdentityServer_base\tools;%PATH%
For detailed information on how to make changes to the directory using these utilities or by using SunONE Console, see the documentation for Sun ONE Directory Server http://docs.sun.com/prod/s1dirsrv.
Figure 3-5 The existing MadisonParc directory tree
.Sample Migration Scripts
The sample scripts included with Identity Server require Perl 5.x or later. Table Table 3-2 provides descriptions of what each script adds to existing directory entries. You’ll find the sample scripts in the following location:
While these samples should prove useful, keep in mind that they are only tools to assist you in properly formatting the directory tree and other data. Each script generates an LDIF file that you can inspect before making actual changes in your directory. You run each script a second time with the last line uncommented to make the actual changes. Steps for using each sample script are included in this chapter under the following headings:
Important: The changes made by using these scripts cannot be automatically undone. Be sure to back up your data before running each script.
Two Approaches to Modifying the Existing Directory Tree
You can use one of two approaches for modifying the directory tree. One option is to make all the necessary modifications to your directory tree before loading the Identity Server LDIF and XML configuration files. This procedure is more error-prone, but may be faster if you have experience using LDAP.
The other option is to make a few modifications in your LDIF and XML files, and then start Identity Server to make sure those modifications were done correctly. This second approach is the recommended approach. For example, you may want to add the Identity Server object classes for each of your organizations, restart Identity Server, and verify that your organizations appear in the Identity Server Administration Console. Then add marker object classes for groups, check them and so forth.
Marking Organizations
If you used an existing organization as your default organization during installation, you do not have to make these changes. The installation program automatically added these object classes and attributes. Skip to "Marking People Containers".
If you have sub-organizations or custom organizations you must make the following changes:
In the MadisonParc example, these object classes and their attributes are added to the organizations dc=Customers and dc=Suppliers.
To Mark Organizations Using the Sample Script
- Copy update-o.pl to the following directory:
DirectoryServer_base/shared/bin
- Set the $base variable to the base suffix of the directory tree to be managed by Identity Server. Example: dc=MadisonParc,dc=com
- In the directory where the script is located, enter the following command:
perl update-o.pl
- When prompted, provide the following information:
Enter Host Name: Enter the name of the computer system in which your Directory Server is installed.
Enter Bind User Name: Enter a username that has sufficient privileges for accessing the entire directory. Example: cn=Directory Manager
Enter Bind password: Enter the password for the user you specified above.
Enter port number: Enter the Directory Server port number. Example: 389
- Check the results in the file orgs-updated.ldif that is generated by the script, and verify that the appropriate changes are listed. The changes contained in this file will automatically be made in the directory in the next step.
Important Note: If there are organizations that you do not want to be managed by Identity Server, you should delete those entries from this orgs-updated.ldif now. Then, instead of going on to the next step, manually load the file using the following command:
ldapmodify -h hostname -p port -D bind_user -w password -a -c -f
orgs-updated.ldif- In the script update-o.pl, uncomment the last line and replace variables appropriately. For example, to add marker object classes to MadisonParc directory entries, the last line of the script is changed from this:
#system("$LDAP_MODIFY -h’$host’ -p’$port’ -D’$bind_user’
-w’$bind_pwd’ -a -c -f orgs-updated.ldif");to this:
system("$LDAP_MODIFY -h’ginac.MadisonParc.com’ -p’389’
-D’cn=Directory Manager’ -w’password’ -a -c -f
orgs-updated.ldif");In Code Example 3-1, the modifications to the MadisonParc directory entries are indicated in bold:
Marking People Containers
People containers are typically assigned the ou attribute and are used to store all user entries for a branch of the directory. To each people container, add the iplanet-am-managed-people-container object class.
To Mark People Containers Using the Sample Script
- Copy update-people.pl to the following directory:
DirectoryServer_base/shared/bin
- Be sure the $base variable is set to the base suffix of the directory tree to be managed by Identity Server. Example: dc=MadisonParc,dc=com
In the MadisonParc example, the script was also modified to include people containers located under the organizations. In Code Example 3-2, bold indicates the change in the search scope.
Code Example 3-2 The scope in update-people-container.pl is modified.
# run search to find all people containers, putting their DNs in to a file
system("$LDAP_SEARCH -h \"$host\" -p \"$port\" -D \"$bind_user\"
-w \"$bind_pwd\" -b \"$base\" -s sub -T \"(&(ou=$people)
(!(objectclass=iplanet-am-*)))\" dn > people.dn");
- In the directory where the script is located, at the command line enter the following:
perl update-people.pl
- When prompted, provide the following information:
Enter Host Name: Enter the name of the computer system in which your Directory Server is installed.
Enter Bind User Name: Enter a username that has sufficient privileges for accessing the entire directory. Example: cn=Directory Manager
Enter Bind password: Enter the password for the user you specified above.
Enter port number: Enter the Directory Server port number. Example: 389
Enter People Container: Enter the name of the people container that contains the uids you want to modify. Example: People
- Check the results in the file people-updated.ldif which is created in the same directory as the script, and verify that the appropriate changes were made. The changes contained in this file will automatically be made in the directory in the next step.
Important Note: If there are people containers that you do not want to be managed by Identity Server, you should delete those entries from people-updated.ldif now. Then, instead of going on the to next step, manually load the file using the following command:
ldapmodify -h hostname -p port -D bind_user -w password -a -c -f
people-updated.ldif- In the script update-people.pl, uncomment the last line and replace variables appropriately. In the MadisonParc example, the last line of the script is changed from this:
#system("$LDAP_MODIFY -h’$host’ -p’$port’ -D’$bind_user’
-w’$bind_pwd’ -a -c -f people-updated.ldif");to this:
system("$LDAP_MODIFY -h’ginac.MadisonParc.com’ -p’389’
-D’cn=Directory Manager’ -w’password’ -a -c -f
people-updated.ldif");In Code Example 3-3, marker object class for the people container under dc=Customers is indicated in bold.
Marking Organizational Units
Organizational units are typically assigned the ou attribute. To each container that is an organizational unit, add the following object class:
iplanet-am-managed-org-unit
To Mark Organizational Units Using the Sample Script
- Copy update-ou.pl to the following directory:
DirectoryServer_base/shared/bin
- Set the $base variable to the base suffix of the directory tree to be managed by Identity Server. Example: dc=MadisonParc,dc=com.
- In the directory where the script is located, at the command line enter the following:
perl update-ou.pl
- When prompted, provide the following information:
Enter Host Name: Enter the name of the computer system in which your Directory Server is installed.
Enter Bind User Name: Enter a username that has sufficient privileges for accessing the entire directory. Example: cn=Directory Manager
Enter Bind password: Enter the password for the user you specified above.
Enter port number: Enter the Directory Server port number. Example: 389
- Check the results in the file orgunit-updated.ldif which is created in the same directory as the script, and verify that the appropriate changes are listed. The changes contained in this file will automatically be made in the directory in the next step.
Important Note: If there are organizational units that you do not want to be managed by Identity Server, you should delete those entries from this ou-updated.ldif now. Then, instead of going on the to next step, manually load the file using the following command:
ldapmodify -h hostname -p port -D bind_user -w password -a -c -f
orgunit-updated.ldif- In the script update-ou.pl, uncomment the last line and replace variables appropriately. In the MadisonParc example, the last line of the script is changed from this:
#system("$LDAP_MODIFY -h’$host’ -p’$port’ -D’$bind_user’
-w’$bind_pwd’ -a -c -f orgunit-updated.ldif");to this:
system("$LDAP_MODIFY -h’ginac.MadisonParc.com’ -p’389’
-D’cn=Directory Manager’ -w’password’ -a -c -f
orgunit-updated.ldif");In Code Example 3-4, marker object class for the organizational units under dc=MadisonParc,dc=com is indicated in bold.
Code Example 3-4 Organizational unit entry with marker object class.
...
dn: ou=People,dc=Customers,dc=MadisonParc,dc=com
ou: People
objectClass: top
objectClass: organizationalunit
objectClass: iplanet-am-managed-people-container
...
Marking Users
To each user entry, add the following object classes:
To Mark Users Using the Sample Script
- Copy update-users.pl to the following directory:
DirectoryServer_base/shared/bin
- Be sure the $base variable is set to the base suffix of the directory tree to be managed by Identity Server. Example: dc=MadisonParc,dc=com
- Be sure the $base-component variable is set to the base suffix of the directory tree.Example: dc=MadisonParc,dc=com
- In the directory where the script is located, at the command line enter the following:
perl udpate-users.pl
- Check the results in the file users-updated.ldif which is created in the same directory as the script, and verify that the appropriate changes were made. The changes contained in this file will automatically be made in the directory in the next step.
Important Note: If there are users that you do not want to be managed by Identity Server, you should delete those entries from users-updated.ldif now. Then, instead of going on the to next step, manually load the file using the following command:
ldapmodify -h hostname -p port -D bind_user -w password -a -c -f
users-updated.ldif- In the script update-users.pl, uncomment the last line and replace variables appropriately. In the MadisonParc example, the last line of the script is changed from this:
#system("$LDAP_MODIFY -h’$host’ -p’$port’ -D’$bind_user’
-w’$bind_pwd’ -a -c -f users-updated.ldif");to this:
system("$LDAP_MODIFY -h’ginac.MadisonParc.com’ -p’389’
-D’cn=Directory Manager’ -w’password’ -a -c -f
users-updated.ldif");In Code Example 3-5, the user marker object class is indicated in bold.
Code Example 3-5 User entry with user marker object class.
dn: uid=scarter, ou=People, dc=MadisonParc,dc=com
nsUniqueId: d8855082-1dd111b2-8024a6c9-802bec30
givenName: Sam
telephoneNumber: +1 408 555 4798
sn: Carter
ou: Accounting
ou: People
l: Sunnyvale
roomNumber: 4612
mail: scarter@MadisonParc.com
facsimileTelephoneNumber: +1 408 555 9751
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
objectClass: inetuser
objectClass: inetadmin
objectClass: iplanet-am-managed-person
objectClass: iplanetPreferences
objectClass: iplanet-am-user-service
uid: scarter
cn: Sam Carter
userPassword: {SSHA}3XwjhBgbt6ae5syCndDeANoossEGRJ1NdnLyZw==
employeeType: Manager
departmentNumber: 1000
businessCategory: East
inetUserStatus: Active
Marking Static Groups
Static groups formed by adding uids to the group entry.
To each group entry containing values for the uniquemember attribute, add the following object classes:
To Mark Static Groups Using the Sample Script
- Copy update-static-groups.pl to the following directory:
DirectoryServer_base/shared/bin
- Set the $base variable to the base suffix of the directory tree to be managed by Identity Server. Example: dc=MadisonParc,dc=com.
- In the directory where the script is located, at the command line enter the following:
perl update-static-groups.pl
When prompted, provide the following information:
Enter Host Name: Enter the name of the computer system in which your Directory Server is installed.
Enter Bind User Name: Enter a username that has sufficient privileges for accessing the entire directory. Example: cn=Directory Manager
Enter Bind password: Enter the password for the user you specified above.
Enter port number: Enter the Directory Server port number. Example: 389
- Check the results in the file static-groups-updated.ldif which is created in the same directory as the script, and verify that the appropriate changes are listed. The changes contained in this file will automatically be made in the directory in the next step.
Important Note: If there are static groups that you do not want to be managed by Identity Server, you should delete those entries from static-groups-updated.ldif now. Then, instead of going on the to next step, manually load the file using the following command:
ldapmodify -h hostname -p port -D bind_user -w password -a -c -f
static-groups-updated.ldif- In the script update-static-groups.pl, uncomment the last line, and replace variables appropriately. For example, in the MadisonParc example, the last line of the script is changed from this:
#system("$LDAP_MODIFY -h’$host’ -p’$port’ -D’$bind_user’
-w’$bind_pwd’ -a -c -f static-groups-updated.ldif");to this:
system("$LDAP_MODIFY -h’ginac.MadisonParc.com’ -p’389’
-D’cn=Directory Manager’ -w’password’ -a -c -f
static-groups-updated.ldif");In Code Example 3-6, marker object class for static groups is indicated in bold
Code Example 3-6 Static group entry with marker object classes.
dn: cn=Directory Administrators, dc=MadisonParc,dc=com
nsUniqueId: 60a72e02-1dd211b2-8003a6c9-802bec30
objectClass: top
objectClass: groupofuniquenames
objectClass: iplanet-am-managed-group
objectClass: iplanet-am-managed-static-group
cn: Directory Administrators
uniqueMember: uid=kvaughan, ou=People, dc=MadisonParc,dc=com
uniqueMember: uid=alutz, ou=People, dc=MadisonParc,dc=com
uniqueMember: uid=gjensen, ou=People, dc=MadisonParc,dc=com
uniqueMember: uid=tcouzens, ou=People, dc=MadisonParc,dc=com
Marking Dynamic (Filtered) Groups
Dynamic or filtered groups are formed by building a search construct to find all user entries containing a specific attribute. These groups contain the memberURL attribute.
To each group containing the attribute memberURL, add the following object classes:
To Mark Filtered Groups Using the Sample Script
- Copy update-filtered-groups.pl to the following directory:
DirectoryServer_base/shared/bin
- Set the $base variable to the base suffix of the directory tree to be managed by Identity Server.
Example: dc=MadisonParc,dc=com
- In the directory where the script is located, at the command line enter the following:
perl update-filtered-groups.pl
- When prompted, provide the following information:
Enter Host Name: Enter the name of the computer system in which your Directory Server is installed.
Enter Bind User Name: Enter a username that has sufficient privileges for accessing the entire directory. Example: cn=Directory Manager
Enter Bind password: Enter the password for the user you specified above.
Enter port number: Enter the Directory Server port number. Example: 389
- Check the results in the file filtered-groups-updated.ldif which is created in the same directory as the script, and verify that the appropriate changes were made. The changes contained in this file will automatically be made in the directory in the next step.
Important Note: If there are filtered or dynamic groups that you do not want to be managed by Identity Server, you should delete those entries from filtered-groups-updated.ldif now. Then, instead of going on the to next step, manually load the file using the following command:
ldapmodify -h hostname -p port -D bind_user -w password -a -c -f
filtered-groups-updated.ldif- In the script update-filtered-groups.pl, uncomment the last line in the update-o.pl file, and replace variables appropriately. In the MadisonParc example, the last line of the script is changed from this:
#system("$LDAP_MODIFY -h’$host’ -p’$port’ -D’$bind_user’
-w’$bind_pwd’ -a -c -f filtered-groups-updated.ldif");to this:
system("$LDAP_MODIFY -h’ginac.MadisonParc.com’ -p’389’
-D’cn=Directory Manager’ -w’password’ -a -c -f
filtered-groups-updated.ldif");In Code Example 3-7, marker object class for a filtered group is indicated in bold.
Code Example 3-7 Dynamic or filtered group with marker object classes.
dn: cn=North,ou=groups,dc=MadisonParc,dc=com
nsUniqueId: 60a72e35-1dd211b2-8003a6c9-802bec30
objectClass: top
objectClass: groupOfUniqueNames
objectClass: groupofurls
objectClass: iplanet-am-managed-group
objectClass: iplanet-am-managed-filtered-group
ou: groups
cn: North
memberURL: ldap:///dc=MadisonParc,dc=com??sub?(&(|(objectclass=person)(objectc
lass=groupofuniquenames))(businessCategory=*North*))
Marking Assignable Dynamic Groups
The assignable dynamic group is an Identity Server concept. In Identity Server, users in this type of group are typically allowed limited self-registration and account management privileges. In the MadisonParc example, users at the top level have administrators to create and manage their entries to comply with corporate specifications. Users under the Customers or Suppliers organizations are placed in assignable dynamic groups. The users can acquire membership by themselves when they log into the MadisonParc portal. Their membership entitles them to limited access to the MadisonParc portal; the information they provide at registration is minimal.
Add the following object classes to each dynamic group that you want to use as an assignable dynamic group in Identity Server:
To Mark Assignable Dynamic Groups Using the Sample Script
- Copy update-assignable-dynamic-groups.pl to the following directory:
DirectoryServer_base/shared/bin
- Set the $base variable to the base suffix of the directory tree to be managed by Identity Server. Example: dc=MadisonParc,dc=com
- In the directory where the script is located, at the command line enter the following:
perl update-assignable-dynamic-groups.pl
- When prompted, provide the following information:
Enter Host Name: Enter the name of the computer system on which your Directory Server is installed.
Enter Bind User Name: Enter a username that has sufficient privileges for accessing the entire directory. Example: cn=Directory Manager
Enter Bind password: Enter the password for the user you specified above.
Enter port number: Enter the Directory Server port number. Example: 389
- Check the results in the file assignable-dynamic-groups-updated.ldif which is created in the same directory as the script, and verify that the appropriate changes were made. The changes contained in this file will automatically be made in the directory in the next step.
Important Note: If there are assignable dynamic groups that you do not want to be managed by Identity Server, you should delete those entries from this assignable-dynamic-groups-updated.ldif now. Then, instead of going on the to next step, manually load the file using the following command:
ldapmodify -h hostname -p port -D bind_user -w password -a -c -f
assignable-dynamic-groups-updated.ldif- In the script update-assignable-dynamic-groups.pl, uncomment the last line in the update-assignable-dynamic-groups.pl file, and replace variables appropriately. In the MadisonParc example, the last line of the script is changed from this:
#system("$LDAP_MODIFY -h’$host’ -p’$port’ -D’$bind_user’
-w’$bind_pwd’ -a -c -f
assignable-dynamic-groups-updated.ldif");to this:
system("$LDAP_MODIFY -h’ginac.MadisonParc.com’ -p’389’
-D’cn=Directory Manager’ -w’password’ -a -c -f
assignable-dynamic-groups-updated.ldif");Marking Group Containers
Group containers are organizational units (ou) that contain groups. To each group container that includes the ou:Groups attribute, add the following object class:
iplanet-am-managed-group-container
To Mark Group Containers Using the Sample Script
- Copy update-groups.pl to the following directory:
DirectoryServer_base/shared/bin
- Be sure the $base variable is set to the base suffix of the directory tree to be managed by Identity Server.
Example: dc=MadisonParc,dc=com.
In the MadisonParc example, the script was also modified to include all group containers located under organizations. In Code Example 3-8, the script changes are indicated in bold.
Code Example 3-8 The scope in update-groups.pl is modified.
# run search to find all group containers, putting their DNs in to a file
system("$LDAP_SEARCH -h \"$host\" -p \"$port\" -D \"$bind_user\"
-w \"$bind_pwd\" -b \"$base\" -T \"(&(ou=groups)
(!(objectclass=iplanet-am-*))(objectclass=organizationalunit))\
" dn > group-container-updated.dn");
- In the directory where the script is located, at the command line enter the following command:
perl update-groups.pl
- When prompted, provide the following information:
Enter Host Name: Enter the name of the computer system in which your Directory Server is installed.
Enter Bind User Name: Enter a username that has sufficient privileges for accessing the entire directory. Example: cn=Directory Manager
Enter Bind password: Enter the password for the user you specified above.
Enter port number: Enter the Directory Server port number. Example: 389
- Check the results in the file groups-updated.ldif which is created in the same directory as the script, and verify that the appropriate changes were made. The changes contained in this file will automatically be made in the directory in the next step.
Important Note: If there are group containers that you do not want to be managed by Identity Server, you should delete those entries from this groups-updated.ldif now. Then, instead of going on the to next step, manually load the file using the following command:
ldapmodify -h hostname -p port -D bind_user -w password -a -c -f
groups-updated.ldif- In the script update-groups.pl, uncomment the last line, and replace variables appropriately. In the MadisonParc example, the last line of the script is changed from this:
#system("$LDAP_MODIFY -h’$host’ -p’$port’ -D’$bind_user’
-w’$bind_pwd’ -a -c -f groups-updated.ldif");to this:
system("$LDAP_MODIFY -h’ginac.MadisonParc.com’ -p’389’
-D’cn=Directory Manager’ -w’password’ -a -c -f
groups-updated.ldif");In Code Example 3-9, marker object class for a group under dc=Customers is indicated in bold.
Code Example 3-9 Group container with marker object class.
...
dn: ou=Groups,dc=Customers,dc=MadisonParc,dc=com
nsUniqueId: 7880b101-1dd211b2-8007a6c9-802bec30
ou: Groups
objectClass: top
objectClass: organizationalunit
objectClass: iplanet-am-managed-group-container
...
Adding Custom Object Classes to Identity Server SchemaIf your existing directory tree contains object classes you’ve created that do not come with Directory Server, then you’ll have to add those object classes and attributes to the Identity Server schema. In the examples in this section, the MadisonParc directory tree uses two object classes and two user attributes that do not come with the Directory Server schema or with Identity Server schema. These object classes and attributes help to distinguish MadisonParc employees at the top level of the directory tree from non-employees in the Customers and Suppliers organizations. Before Identity Server can manage these extensions, changes must be made in the following three Identity Server files:
This chapter contains detailed instructions for making these modifications. The instructions are provided here to help you see your existing data in Identity Server after you run the Installation program.
For background information on the Identity Server schema and detailed information about customizing Identity Server, see ”Understanding Identity Server XMLs and DTDs” in the Programmer’s Guide.
Modifying the Creation Templates
The creation templates configure Identity Server to add or allow specific object classes and attributes when these entries are created. To expose custom object classes in the UI, you must modify the creation templates for both users and organizations in the umsExisting.xml file.
In the MadisonParc example, the existing directory tree has new object classes for both users and organizations.
The DAI Service
When you install Identity Server services, the ums.xml file is stored in Directory Server as the Directory Access Instructions (DAI) service. Identity Server will not allow you to load the umsExisting.xml file if the DAI service is already installed in Directory Server. Always remove the DAI service before modifying the umsExisting.xml file. Once you’re finished modifying the files, you must reload the DAI service into Directory Server.
To Remove the DAI Service
In the following directory:
IdentityServer_base/bin
execute the following command:
./amadmin -u "user_naming_attibute=amadmin,ou=people,root_suffix" -w
password -r DAITo Load the DAI Service
In the following directory:
IdentityServer_base/bin
execute the following command:
./amadmin -u "user_naming_attibute=amadmin,ou=people,root_suffix" -w
password -s umsExisting.xmlTo Modify the Creation Templates
- If during installation, you chose to load the Identity Server schema, or if you have already run the amserveradmin command for any reason, skip this step and go on to step 2. Otherwise, remove the DAI service. In the following directory:
IdentityServer_base/bin
execute the following command:
./amadmin -u "user_naming_attibute=amadmin,ou=people,root_suffix" -w
password -r DAI- Locate the following file:
UNIX
IdentityServer_base/SUNWam/config/ums/umsExisting.xml
Windows
IdentityServer_base\config\ums\umsExisting.xml
- Modify any custom naming attributes. For example, the MadisonParc directory tree uses the domain attribute instead of the organization attribute.
Under the following SubConfiguration:
"BasicOrganization" id="CreationUmsObjects
change
<Value>objectClass=organization</Value>
to
<Value>objectClass=domain</Value>
In Code Example 3-10, bold indicates the changed value. Note that three lines down, the naming attribute dc was changed by Identity Server during installation.
Code Example 3-10 Changing the organization naming attribute in the creation template.
<SubConfiguration name="BasicOrganization" id="CreationUmsObjects">
<AttributeValuePair> <Attribute name="name" />
<Value>BasicOrganization</Value>
</AttributeValuePair>
<AttributeValuePair> <Attribute name="javaclass" />
<Value>com.iplanet.ums.Organization</Value>
</AttributeValuePair>
<AttributeValuePair> <Attribute name="required" />
<Value>objectClass=top</Value>
<Value>objectClass=domain</Value>
<Value>objectClass=sunManagedOrganization</Value>
<Value>objectClass=sunNameSpace</Value>
<Value>dc</Value>
<Value>inetdomainstatus=Active</Value>
</AttributeValuePair>
<AttributeValuePair> <Attribute name="namingattribute"/>
<Value>dc</Value>
</AttributeValuePair>
<AttributeValuePair> <Attribute name="optional" />
<Value>*</Value>
</AttributeValuePair>
</SubConfiguration>
- Add custom organization object classes.
In the MadisonParc example, madisonparc-org is added to the organization creation template.
Under the following SubConfiguration:
"BasicOrganiation" id="CreationUmsObjects">
under the following element:
<AttributeValuePair><Attribute name="required" />
add the following:
<Value>objectClass=madisonparc-org</Value>
<Value>madisonparc-org-description</Value>
Example:
<SubConfiguration name="BasicOrganization" id="CreationUmsObjects">
<AttributeValuePair> <Attribute name="name" />
<Value>BasicOrganization</Value>
</AttributeValuePair>
<AttributeValuePair> <Attribute name="javaclass" />
<Value>com.iplanet.ums.Organization</Value>
</AttributeValuePair>
<AttributeValuePair> <Attribute name="required" />
<Value>objectClass=top</Value>
<Value>objectClass=domain</Value>
<Value>objectClass=sunManagedOrganization</Value>
<Value>objectClass=sunNameSpace</Value>
<Value>objectClass=madisonparc-org</Value>
<Value>dc</Value>
<Value>inetdomainstatus=Active</Value>
</AttributeValuePair>
<AttributeValuePair> <Attribute name="namingattribute"/>
<Value>dc</Value>
</AttributeValuePair>
<AttributeValuePair> <Attribute name="optional" />
<Value>*</Value>
<Value>madisonparc-org-description</Value>
</AttributeValuePair>
</SubConfiguration>
- Add custom user object classes.
In the MadisonParc example, company is added to the user creation template.
Under the following SubConfiguration:
"BasicUser" id="CreationUmsObjects">
under the following element:
<AttributeValuePair><Attribute name="required" />
add the following:
<Value>objectClass=company</Value>
Example:
<SubConfiguration name="CreationTemplates" >
<SubConfiguration name="BasicUser" id="CreationUmsObjects">
<AttributeValuePair> <Attribute name="name" />
<Value>BasicUser</Value>
</AttributeValuePair>
<AttributeValuePair> <Attribute name="javaclass" />
<Value>com.iplanet.ums.User</Value>
</AttributeValuePair>
<AttributeValuePair> <Attribute name="required" />
<Value>objectClass=top</Value>
<Value>objectClass=person</Value>
<Value>objectClass=organizationalPerson</Value>
<Value>objectClass=inetOrgPerson</Value>
<Value>objectClass=iPlanetPreferences</Value>
<Value>objectClass=iplanet-am-user-service</Value>
<Value>objectClass=inetuser</Value>
<Value>objectClass=inetAdmin</Value>
<Value>objectClass=iplanet-am-managed-person</Value>
<Value>objectClass=company</Value>
<Value>cn=default</Value>
<Value>sn=default</Value>
<Value>uid</Value>
<Value>inetuserstatus=Active</Value>
</AttributeValuePair>
<AttributeValuePair> <Attribute name="optional" />
<Value>*</Value>
<Value>companyname</Value>
<Value>acctname</Value>
</AttributeValuePair>
<AttributeValuePair> <Attribute name="namingattribute"/>
<Value>uid</Value>
</AttributeValuePair>
</SubConfiguration>
- Reload the DAI service (the ums.xml file or umsExisting.xml file).
In the following directory:
IdentityServer_base/bin
execute the following command:
./amadmin -u "user_naming_attibute=amadmin,ou=people,root_suffix" -w password -s
IdentityServer_base/SUNWam/config/ums/umsExisting.xmlAdding Attributes to the Organization Schema
To add attributes to the Organization schema, you must modify two services files:
The Identity Server console uses the information in amEntrySpecific.xml for display purposes. Each Identity Server abstract entry may have a subschema in this XML file. In the following example, you would add the object class external to the organization subschema. If the directory tree contained customized organizational units, groups, or people containers, you would add or modify their subschemas in the same XML file.
The subschema name for an organizational unit will be OrganizationalUnit. The subschema name for a people container will be PeopleContainer.
Note
The User subschema is not configured here in the amEntrySpecific.xml file, but in the amUser.xml file (see "Adding Attributes to the User Schema".) Although any service XML file may describe an attribute that is only for a user, the amEntrySpecific.xml file can serve as a default place holder for user attributes that are not tied to a particular service.
The "any" attribute
The any attribute in the XML descriptions may have five possible values: filter, display, adminDisplay, userReadOnly, required, or optional. The values tell the Console whether the attribute should appear in the GUI. Typically, required and optional are not both displayed at the same time; they are mutually exclusive.
filter. The attribute is displayed in a search page.
display. The attribute is read/write for administrators and regular users.
adminDisplay. The attribute is read/write for administrators and is not displayed for regular users.
userReadOnly. The attribute is read/write for administrators but is read only for regular users. It is displayed as a label for regular users so that it is not editable. For example, the display, adminDisplay, and userReadOnly settings are used when displaying the user profile page and can be used to customize the page.
required.The attribute is displayed in the create page and requires a value during creation of the entry. If any=required, the attribute must have a value or the Console will not allow the Create operation. In the user interface, required fields are indicated with an asterisk (*). Use an empty string (" ") to tell the Administration Console to display nothing.
optional.The attribute is displayed in the create page but does not require a value during creation of the entry. If any=optional, the attribute will appear on the Create page without an asterisk. This would indicate that you don’t have to give it a value to create the entry. In the Create User page, the UserId is a required attribute but the First Name is optional.
In the following MadisonParc example, the attribute madisonparc-org-description will be displayed on the Organization page, and will be required for creation. This is indicated by the use of the required value. It will also be used on the Search page in Identity Server Console, as indicated by the use of the filter value.
<AttributeSchema name="madisonparc-org-description"
type="single"
syntax="string"
any=required|filter
i18nKey="o3"
/>
The "type" attribute
The type attribute can use a string, string list, single choice, multiple choice, or boolean value. For example, the madisonparc-org-description attribute can have only one of two descriptions: internal or external). You would make this attribute a single choice; each description would be one of the choices. The Identity Server Console would display a list containing only these cities. If multiple cities were allowed, the attribute could be a multiple choice.
To Add Attributes from a Custom Organization to the Organization Subschema
- In the following file add the custom object class to the subschema Organization:
UNIX
IdentityServer_base/SUNWam/config/xml/amEntrySpecific.xml
Windows
IdentityServer_base\config\xml\amEntrySpecific.xml
In this example, the custom object class madisonparc-org-description was added to amEntrySpecific.xml.
<AttributeSchema name="madisonparc-org-description"
type="single"
syntax="string"
any=required|filter
/>
- In the same amEntrySpecific.xml file, create internationalization (i18n) keys (also called index keys or localization keys) for each attribute. All i18n Keys in an organization must be made up of unique strings. The Identity Server Administration Console will use this key to look up the display name for the attribute.
<AttributeSchema name="madisonparc-org-description"
type="single"
syntax="string"
any="required|filter"
i18nKey="o3"
/>
- In the following file
:
UNIX
IdentityServer_base/SUNWam/locale/amEntrySpecific.properties
Windows
IdentityServer_base\locale\amEntrySpecific.properties
add the value for i18n Key you created in Step 2. This is the name that will be displayed in the graphical user interface.Example:
iplanet-am-entry-specific-service-description=Identity Server Entry Specific
g1=Member List
g2=Users Can Subscribe to this Group
dg1=Membership Filter
r1=Membership Filter
o1=Full DNS name
o2=Organization Status
o3=Organization Description
All the attributes listed in the subschema are displayed in the Administration Console when an organization is displayed. If an attribute is not listed, the Administration Console will not display the attribute.
Tip
If an attribute has no i18n Key, it will not be displayed on the administration console. If you add an attribute, and you don’t see it in the administration console, be sure to check the i18n Key and properties.
If you see any parsing errors, you should go back and double-check the changes you made in the previous steps. Also examine the syntax in the amEntrySpecific.xml file, and make sure you’ve used the correct syntax. If you need to look at syntax examples, look at the other service XML files located in the following directory:
Adding Attributes to the User Schema
In this step, you will modify two files for services:
The amUser.xml file is where user attributes are described, just as organization and group schema are described in the amEntrySpecific.xml (see Step 2). The file amUser.xml describes the User service for Identity Server. Note that any service may describe an attribute that is for a user only. This file is just the default placeholder for user attributes that are not tied to a particular service.
When displaying a user’s attributes, the Identity Server Administration Console gets all attributes from all services that are subschema type User, and displays them using the same values as used in the amEntrySpecific.xml file (see "The "any" attribute" and "The "type" attribute"). In the following examples, a few attributes from the madisonparc-user object class are added to the file, thus it is not necessary to create a new service. It’s only necessary to modify, or extend, the iplanetamuserservice.
Additional Notes About the amUser.xml File
The file amUser.xml contains a special attribute. The any=display attribute tells Identity Server whether to display the attribute in the user profile page. This is a misleading name since it implies access control. It is strictly used for display. If this attribute is set to no then the console will not display the attribute.
Also note that the attributes are defined under subschema User and not Dynamic. Any attribute defined under User is physically an attribute in the user entry. If you want the attribute to be a role-based or organization-based attribute, then you would define it under the Dynamic subschema. For detailed information, see ”Understanding Identity Server XMLs and DTDs” in the Programmer’s Guide.
To Add Attributes from a Custom Organization to the User Subschema
- In the following file, add the attributes from the custom object class to the User subschema:
UNIX
IdentityServer_base/SUNWam/config/xml/amUser.xml
Windows
IdentityServer_base\config\xml\amUser.xml
For example, the following two attributes from the custom object class company were added to the file:
<AttributeSchema name="companyname"
type=single
syntax=string
any=required|display
/>
<AttributeSchema name="acctnumber"
type=single
syntax=string
any=required|filter|display
- In the same amUser.xml file, create i18n Keys (also called index keys or localization keys) for each attribute. All i18n Keys in an organization must be made up of unique strings. The Identity Server Console will use this key to look up the display name for the attribute.:
<AttributeSchema name="companyname"
type=single
syntax=string
any=required|display
i18nKey=u120
/>
<AttributeSchema name="acctnumber"
type=single
syntax=string
any=required|filter|display
i18nKey=u121
- Add values for the i18n Keys you created in Step 2 to the following file:
UNIX
IdentityServer_base/SUNWam/locale/amUser.properties
Windows
IdentityServer_base\locale\amUser.properties
Example:
iplanet-am-user-service-description=User
iwtUser-desc=Default User Profile
u101=UserId
u102=First Name
u103=Last Name
u104=Full Name
u105=Password
u106=Email Address
u107=Employee Number
u108=Telephone Number
u109=Manager
u110=Home Address
u111=User Status
u112=Account Expiration date (mm/dd/yyyy hh:mm)
u113=User Authentication Configuration
u114=User Alias List
u115=Preferred Locale
u116=Success URL
u117=Failure URL
u118=Federation Information Key
u119=Federation Information
u120=Company Name
u121=Account Number
- Load all XML files.
In the following directory:
IdentityServer_base/bin
execute the following command:
./amserveradmin -u "user_naming_attibute=amadmin,ou=people,root_suffix"
-w passwordIf you see any parsing errors, you should go back and double-check the changes you made in the previous steps. Also examine the syntax in the amUser.xml file, and make sure you’ve used the correct syntax. If you need to look at syntax examples, look at the other service XML files located in the following directory:
Loading Identity Server LDIF into Your DirectoryIdentity Server provides two different LDIF files to help you make the necessary modifications in your directory when you are enabling User Management services. You’ll need to follow instructions for both loading installExisting.ldif and install.ldif.
Figure illustrates the MadisonParc directory tree after enabling both User Management and Policy Management services. Both installExisting.ldif and install.ldif files were loaded into an existing directory.
Figure 3-6 The MadisonParc directory tree with both installExisting.ldif and install.ldif added.
installExisting.ldif
The installExisting.ldif file contains Identity Server-specific entries that are loaded into Directory Server during installation. Typically, you will not need to modify this file before it gets loaded during the installation process.
You can use the ldapmodify utility that comes with Directory Server to load installExisting.ldif. In the MadisonParc example, when you load the LDIF, the following occurs:
- Users and marker object classes required for Identity Server are added to dc=MadisonParc,dc=com and to dc=Customers and dc=Suppliers.
- Default roles for organization and help desk administrators are created at the top level.
- Default Access Control Instructions (ACIs) for those administrator entries are set up.
To Load the installExisting.ldif File
The Identity Server administration user amAdmin will be created under the ou=People,dc=MadisonParc,dc=com people container. This is the top level administrator for Identity Server. This administrator has read and write access to the entire dc=MadisonParc,dc=com root suffix. You can add one of your users to this top level administrator role after the Identity Server console is started.
install.ldif
To Load the install.ldif File
Results of Identity Server and Directory ModificationsAfter making the modifications in the previous steps, all entries in your existing directory will be manageable by Identity Server. The existing ACIs for the organization administrators do not have to be modified. Even though Identity Server uses roles and ACIs by default, your existing groups and ACIs will still work.
You can convert a groups-based directory tree to one that leverages roles and ACIs. If you choose to do this, you can use the Identity Server organization administrator roles and assign them to your existing organizationList administrators. For more information, see the Administrator’s Guide.