| Sun ONE Identity Server 6.0 Installation and Configuration Guide |
Chapter 5
Installing Identity Server Against an Existing Directory ServerThis chapter provides instructions for installing Identity Server against an existing directory that contains 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 Directory Server and directory entries. The number and scope of changes you must make will depend upon how your existing DIT is structured, and how you plan to use Identity Server.
Topics in this chapter include:
Overview of Installation TasksTo install Identity Server against an existing DIT, you must first run the Installation program and then manually configure both Directory Server and Identity Server.
Running the Identity Server Installation Program
Detailed instructions for each of the following steps are provided in this chapter. It is important to follow the steps in the this exact sequence in order to avoid making unwanted changes to your directory.
- Install Identity Server schema.
In this step you run the Identity Server Installation program and select the “Configure Existing Directory Server” option. For detailed instructions, see "Installing Identity Server Schema" 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 "Manually Configuring the Directory Server" in this chapter.
- Install Identity Server user and policy management services.
In this step you run the Identity Server Installation program a second time. For detailed installation instructions, see "Installing User and Policy Management Services" in this chapter.
Note that during Installation, you’ll be asked whether you want to automatically or manually enable User and Policy Management services. For more information, see "Choosing a Procedure for Enabling Services".
- Enable one of three Identity Server modes:
- Policy Management only
- User Management only (after Policy Management is enabled)
- Both User Management and Policy Management at the same time
If during Installation you chose to automatically enable Policy Management services, you can skip Step 4 and go on to Step 5. For more information, see "Automatically Enabling Policy Management Services".
If during Installation you chosen to manually enable User or Policy Management services, in this step you must manually enable the services. This requires some post-installation configuration. For a quick overview, see the next section “Post-Installation Configuration.” For detailed instructions, see "Manually Enabling Policy and User Management Services" in this chapter.
- Start Identity Server.
For detailed instructions, see "Starting Identity Server and Logging In" in this chapter.
Post-Installation Configuration
If your existing DIT 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 DIT for MadisonParc, a fictitious company. The directory entries in the MadisonParc example include two custom object classes. These are object classes that are not already defined in the default Directory Server schema nor in the default Identity Server schema. If your existing DIT contains custom object classes or attributes, you’ll need to make similar changes in your directory and in your Identity Server XML files.
Existing DIT Examples in This Chapter
Figure 5-1 illustrates the Directory Server console view of the DIT 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 5-1 The existing DIT for MadisonParc.
Adding Marker Object Classes to Existing Directory Entries
Before Identity Server can recognize the data in an existing directory, an you must add special object classes to entries for all organizations, groups and users that will be managed by Identity Server. Detailed steps and examples based on the MadisonParc DIT are provided in this chapter. See "Adding Identity Server Object Classes to Existing Directory Entries". Sample scripts are bundled in the product to help you automatically add these object classes to your directory.
Adding Custom Object Classes to Identity Server Schema
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 5-1 summarizes the custom objects and their uses in the MadisonParc DIT.
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:
Detailed steps and examples are provided in this chapter. See "Adding Custom Object Classes to Identity Server Schema".
Before You BeginYou must resolve the following issues before you can install Identity Server against an existing Directory Server that is provisioned with users.
Directory Server Issues
Refer to the documentation for Sun ONE Directory Server for detailed information about the following issues.
Migrating Pre-5.1 SP1 Versions of Directory Server
If you are using a pre-5.1 SP1 version of Directory Server, you must upgrade your existing Directory Server to version 5.1 SP1, and then migrate your existing data to the upgraded directory. For detailed instructions, see the Directory Server documentation at the following URL: http://docs.sun.com/source/816-5610-10/upgrade.htm#997630.
Backing Up Directory Server 5.1 SP1
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 Installation Guide at:
http://docs.sun.com/db/doc/816-5602-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.
Migrating Pre-6.0 Versions of Identity Server
If you have iPlanet Directory Server-Access Management Edition (DSAME) 5.0 or 5.1 already installed, you must migrate the data from DSAME 5.1 to Identity Server 6.0. For detailed instructions, see Appendix A, "Migrating Data from DSAME 5.1 to Identity Server 6.0".
Using Appropriate Administrator Privileges
Displaying the Installation Wizard on UNIX
To use the Installation wizard on UNIX, your DISPLAY variable must be set for the computer system where you are installing Identity Server or its components. Also be sure that your have authorization to connect to the computer system where you are installing Identity Server or its components. If you cannot set either of these appropriately, you should use the command-line version of the Installation program.
Using Java 1.3.1_06
Be sure you are using Java 1.3.1_06. If you are using an older version of the JDK, during Identity Server Installation you will be asked to install version that comes with Identity Server, or to provide a path to Java 1.3.1_06.
Setting the Domain Name
Be sure the domain name and host name of the computer system where you will install Identity Server are set, and that the computer system is configured for host name lookup.
To Set the Domain Name On UNIX
- View your host name setting by running the following command:
# uname -n
The short format of the host name is returned.
- To set the domain name, do one of the following:
- If the file /etc/resolv.conf exists, then enter the domain name in the domain configuration entry. Example: domain madisonparc.com
- If the file /etc/resolv.conf does not exist, then enter the following command:
# domainname domainname
Example:
# domainname madisonparc.com
where madisonparc.com is the domain to which this computer system belongs.
- To verify that the host name and domain name are set properly, you can enter the following command:
# ping hostname.domainname
If the host name is not returned, contact your network Administrator.
To Set the Domain Name on Windows 2000
- On the Windows desktop, right-click My Computer and then click Properties.
- In the System Properties window, click Network Identification.
- Click Properties.
- In the Computer Name field, if there is no name, enter a name for the host.
- Click More.
- In the Primary DNS Suffix of this computer field, enter the name of the domain to which this computer belongs.
The Primary DNS Suffix combined with the computer name forms the fully-qualified domain name for this computer. Example:
hostname.madisonparc.com
Removing Old Instances of Identity Server
Be sure that Identity Server packages or schema are not already installed in another directory on the computer system. To check for an existing packages, you can use the following command:
pkginfo
If packages beginning with SUNWam exist, Identity Server may have been previously installed on the computer system. If possible, uninstall Identity Server using its Uninstallation program. See "Uninstalling Identity Server" and "Uninstalling Identity Server On Windows" of this manual.
If Identity Server was not properly uninstalled, then you should manually remove the Identity Server packages and files now. Follow these steps:
- Remove all Identity Server packages.
First find all Identity Server packages installed on the computer system, run the following command:
pkginfo | grep SUNWam
Then use the pkgrm command to remove each package identified with either of the following:
- Remove the following files located in the directory /var/sadm/install if they exist:
- If the directory /var/sadm/pkg exists, remove all Identity Server packages from it.
Choosing a Procedure for Enabling Services
During Installation, you’ll be asked whether you want to automatically install the Identity Server schema and XML files, or to manually install them. Your choice should be based upon which one of the following you want to achieve:
To help you determine which procedure is best for your needs, Figure 5-2 on the next page provides a flowchart of the post-installation steps associated with each of these goals. For detailed information, see "Automatically Enabling Policy Management Services" and "Manually Enabling Policy and User Management Services" in this chapter.
Figure 5-2 Automatically vs. manually enabling Policy Management.
Installing Identity Server SchemaTo install the Identity Server schema, you must run the Installation program. When you install the Identity Server schema this way, the SUNWamdsc package is installed in the Identity Server root directory. No new Directory Server is installed; no existing directory data is overwritten.
To Install Identity Server Schema
- Log in to the host computer where Directory Server is installed.
- Locate the Identity Server Installation program.
If you’re installing Identity Server schema from the product CD, insert the CD into the drive of the system on which you want to install the software. You’ll find the Installation program in the following directory:
If you’ve downloaded the compressed product binaries, in a temporary directory, unpack the product binaries. On UNIX, be sure to use the Solaris tar utility. To unpack the binaries, enter the following command:
where binaryfile is the name of the file you have downloaded. You’ll find the Installation program in the directory where you unpacked the product binaries.
- Start the Installation program.
To run the Installation wizard, in the directory that contains the Installation program, enter the following command:
To run the Installation program from the command line, in the directory that contains the Installation program, enter the following command:
- In the Welcome window, click Next.
- To accept the terms of the License Agreement, click “I Accept.”
- In the Installation Directory window, enter the path to the directory where you want to install the Identity Server schema, and then click Next.
- In the Components to be Installed/Uninstalled window, click “Configure an Existing Directory Server,” and then click Next.
Figure 5-3 Components to be Installed/Uninstalled Panel
- In Sun ONE Directory Server Information window, provide the following information, and then click Next:
Host: Enter the fully qualified domain name of the computer where Directory Server is installed.
Port: Enter the Directory Server port number.The default port is 389.
Directory Manager: Enter the DN of the user who has unrestricted access to Directory Server. This DN was specified when Directory Server was installed. Example: cn=Directory Manager
Password: Enter the password that was entered for the Directory Manager when Directory Server was installed.
- In the Currently Selected Settings window, review the settings you have selected, and then click Next.
- In the Ready to Install window, click “Install Now.”
- When the program is finished, in the Installation Summary window, click Close.
Note that once you’ve successfully installed Identity Server or any of its components on the local host, you can use the command line to automatically to install the Identity Server schema on an additional Directory Server instance. For more information, see "Installing and Uninstalling Identity Server Schema from the Command Line".
Manually 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, expand the root suffix, and then click the database that contains the directory entries you want to use in Identity Server.
- Click the Indexes tab.
- In the Indexes tab, click "Add attribute..."
- In the Select Attributes window, select the attribute nsroledn, and then click OK.
- In the Indexes tab, 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.
Installing User and Policy Management ServicesAfter you’ve installed the Identity Server schema and manually configured the Directory Server, you must run the Installation program a second time. This time, the following components will be installed:
To Install User and Policy Management Services
Important: During installation, you must indicate which procedure you want to use for enabling these services after the Installation program is finished. For detailed information, see "Choosing a Procedure for Enabling Services".
- Start the Installation program.
To run the Installation wizard, in the directory that contains the Installation program, enter the following command:
To run the Installation program from the command line, in the directory that contains the Installation program, enter the following command:
- In the Welcome window, click Next.
- To accept the terms of the License Agreement, click “I Accept.”
- In the Installation Directory panel, provide the following information, and then click Next:
Install Sun ONE Identity Server in this directory: Enter the path to the directory where Identity Server Services will be installed. You must have write and execute permissions in this directory.
- In the Components to Be Installed/Uninstalled window, select “Sun ONE Identity Server Management and Policy Services,” and then click Next.
Figure 5-4 Components to Be Installed/Uninstalled Panel
- In the Java SDK Configuration window, provide the following information, and then click Next:
Do you want to use custom JDK? Java support in the Web Server requires Java SDK 1.3.1_06, which is provided with Identity Server 6.0. If you want to install the Java SDK available with Identity Server, select No. If you want to use a JDK (version 1.3.1_06 or higher), that you already have, select Yes and then Enter the full path to its location.
- In the Sun ONE Web Server Information panel, provide the following information about the Web Server that will run Identity Server services, and then click Next:
Administrator: Enter the user name for the administrator who will access and manage the Web Server.
Port: Enter the port number. Typically, the default is 58888.
Password: Enter the Administrator’s password. The password must be a minimum of eight characters in length.
Confirm Password: To confirm the Administrator password, enter it again.
Enter user to run server as: Enter the user account the Web Server will run as. Example: nobody
Enter group to run this server as: Enter the group the above user belongs to. Example: nobody
- In the “Web Server that Runs Sun ONE Identity Server Services” window, provide the following information, and then click
NextHost: Enter the fully qualified host name of the computer where the Identity Server components and a dedicated web server will be installed together. Make sure that the domain name of the computer is set and you have entered it correctly in the field. See the section "Setting the Domain Name" for instructions on setting the domain name.
Port: Enter the port number of the Web Server that runs the Identity Server services. The default port is 58080.
Services Deployment URI: The Universal Resource Identifier (URI) prefix tells the Web Server where to look for HTML pages associated with a service and also for web application-specific information such as classes and jars.
The default URI prefix is amserver. You can enter a different name.
Common Domain Deployment URI: The URI for accessing the common domain services on the Web Server. The default URI is common. You can enter a different name.
Deploy console with this service? By default, this box is checked to indicate that the console will be installed with the Identity Server services. However, if you have an existing console and do not want to deploy the console now, click the check box to clear the selection. In this case, the installation program will display another panel to seek more information about the existing console. See the next step for details.
Console Deployment URI: This URI prefix tells the Web Server where to look for HTML pages associated with the Identity Server console and also for other web application-specific information like classes and jars. The default URI prefix is amconsole. You can enter a different name. This field is not available, if you cleared the check box “Deploy Console with this Service?”
- If, in the previous step, you chose to deploy the console with this server, skip to Step 10.
If, in the previous step, you chose not to deploy the console with this service, you must provide the following information about the existing console. In the Web Server that Runs Sun ONE Identity Server Console window, provide the following information, and then click Next:
Host: Enter the fully qualified domain name of the computer where the Identity Server Console is installed.
Port: Enter the port number of the Web Server that runs the Identity Server services. The default port is 58080.
Console Deployment URI: This URI prefix tells the Web Server where to look for HTML pages associated with the Identity Server console and also for other web application-specific information like classes and jars. The default URI prefix is amconsole. You can Enter a different name.
- In the Directory Schema panel, choose Use an existing Sun ONE Directory Server with an existing DIT, and then click Next.
Use an existing Sun ONE Directory Server without existing DIT: Choose this option only if your existing Directory Server is not provisioned with users. This option is useful, for example, when you want to install Directory Server on a separate computer system for enhanced performance.
Use an existing Sun ONE Directory Server with an existing DIT: Choose this option if you want to install Identity Server against a local Directory Server, and you plan to use its user management functionality.
Do not choose the “Install a new Sun ONE Directory Server” option.
- In the Directory Root Suffix panel, provide the following information, and then click Next:
Sun ONE Identity Server Root in the Directory Server: Enter a distinguished name (DN) that you want to set as the root suffix. It should have at least one type=value pair.
Examples:
o=EdisonWatson
dc=MadisonParc,dc=com
- In the Sun ONE Directory Server Information panel, provide the following information, and then click Next:
Host: Enter the fully qualified domain name of the computer where Directory Server is installed.
Port: Enter the Directory Server port number.The default port is 389.
Directory Manager: Enter the DN of the user who will have restricted access to Directory Server. Example: cn=Directory Manager
Password: Enter the password for Directory Manager. The password must be a minimum of eight characters in length.
If the information you provide in any of these fields is inaccurate, the installation program will display an error message. Check the values you have provided and correct them to proceed.
- The following message displays:
- If you click Yes, then the Identity Server schema and LDIF files are automatically loaded into Directory Server for you. Use this option if you want to enable only Policy Management services at this time, and if you are not concerned with reviewing changes to the directory immediately after each file is loaded. When you choose “Yes,” the Policy Management services are automatically enabled for you, but User Management services are not.For more information, see "Automatically Enabling Policy Management Services".
If you want to enable User management services at a later time, you must follow the instructions in "Enabling User Management Only".
- If you click No, then after installation, you must manually load the schema and LDIF files required to enable either Policy Management or User Management services. At that time, you will have the opportunity to review changes to the directory immediately after each file is loaded. For more information, see "Manually Enabling Policy and User Management Services".
- In the Existing DIT and Schema Information window, provide the following information, and then click Next:
Marker object class for organizations: Enter the object class defined for the organization in your existing DIT. The default is organization. In the dc=MadisonParc, dc=com example used in this chapter, the object class defined for the organization is domain.
Naming attribute for organizations: Enter the naming attribute used to define organizations in your existing DIT. If your existing DIT uses o=organization, you can accept the default value o. In the dc=MadisonParc, dc=com example used in this chapter, the naming attribute for organizations is dc.
Marker object class for users: Enter the object class defined for users in your DIT.
Naming attribute for users: Enter the naming attribute used for users in your existing DIT. If the DIT does not use uid, you may overwrite the default value displayed in the field.
- In the Sun ONE Identity Server Internal LDAP Authentication User Information window, provide the following information, and then click Next.
Username: This is the bind DN user for LDAP, Membership, and Policy services. This user will have read and search access to all Directory Server entries. The user name amldapuser is hard-coded and you cannot change it.
Password: Enter the password for the amldapuser. This password must be different from the Top Level Administrator password which you will provide in the next Installation window. The amldapuser password is the Shared Secret between Identity Server and Agents.
Confirm Password: Re-enter the password to confirm.
- In the Sun ONE Identity Server Top Level Administrator panel, provide the following information, and then click Next:
Username: The Top Level Administrator has unlimited access to all entries managed by Identity Server. The username for the Top Level Administrator is amAdmin; this username is hardcoded. This ensures that the Identity Server administrator role and its privileges are created and mapped properly in the Directory Server so that you can log onto Identity Server immediately after installation. Since this is an administrator role, you can add other users to this role after installation.
Password: Enter the password for the user amAdmin. The password must be a minimum of 8 characters in length.
Confirm Password: To confirm the amAdmin password, enter it again.
Start the Server after installation: Click this option if you want to automatically start the Identity Server after installation. If you do not select this, you must start the server manually after installation. For steps to do this, see "Starting Identity Server and Logging In".
- In the Currently Selected Settings panel, review the choices you have made in the previous panels. If you want to revisit any of the panels, click Back. When you are ready to proceed with the installation, click Next.
- When the Installation program is finished, click Next.
Automatically Enabling Policy Management ServicesYou can automatically enable Policy Management services if you want to use Identity Server to manage policies, but not to create or manage user entries.
Policy Management is automatically enabled for you only if, during Installation, you answer “Yes” to the following question:
When the Policy Management services are automatically installed against your existing DIT, immediately after Installation you’ll see the Identity Server object classes, roles, users, and services in your Directory Server console view. Figure 5-5. illustrates the existing DIT for the MadisonParc examples used in this chapter.
Figure 5-5 Policy Management services installed against the existing MadisonParc DIT.
For instructions on starting Identity Server and logging in, see "Starting Identity Server and Logging In".
When you log into Identity Server for the first time, you will see the root suffix and organizations you specified during installation. For the MadisonParc example used in the beginning of this chapter, you would see the root suffix MadisonParc.com, and the two organizations Customers and Suppliers.You will not be able to see the rest of your existing directory entries unless you manually enable User Management services. See "Enabling User Management Only".
When you see the Identity Server interface (see Figure 5-6), you can immediately begin creating policies. See the Identity Server Administration Guide for more information.
Figure 5-6 Identity Server interface at first-time login for MadisonParc
.
Manually Enabling Policy and User Management ServicesYou can manually enable Policy and User Management services if you want to use Identity Server to create and manage user entries in your directory, or if you want to visually inspect changes to your directory after each step in the enablement procedures.
You must manually enable either User or Policy Management services if, during Installation, you answer “No” to the following question:
If you answer “Yes” to this question, you have the option to manually enable Use Management service. (Policy Management service is automatically enabled.)
Manually enablement entails reconciling the Identity Server schema with your existing directory entries. Enablement procedures vary depending upon which of the following you want to achieve:
Enabling User Management Only
Follow these steps after automatically enabling Policy Management, and only if both of these are true:
To enable User Management only:
- 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.
- Remove the DAI service. In the following directory:
Identity_Server_root/bin
execute the following command:
./amadmin -u "user_naming_attibute=amadmin,ou=people,root_suffix"
-w password -r DAIFor more information about the DAI service, see "The DAI Service" of this chapter.
- Modify the Identity Server ums.xml file.
See "Adding Identity Server Object Classes to Existing Directory Entries" in this chapter for more information. The section provides detailed instructions on performing the following steps:
- Reload the DAI service by entering the following command:
Identity_Server_root/bin/amadmin -u
"user_naming_attibute=amadmin,ou=people,root_suffix"
-w password -s ums.xml- Load the install.ldif file.
For detailed information, see "install.ldif".
- Restart Identity Server.
In the following directory:
Identity_Server_root/bin
execute the following command:
./amserver start
- Log in to Identity Server console as amAdmin.
You will not see your existing groups and users from your existing DIT 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 5-7 Identity Server with data from existing MadisonParc DIT
Enabling Policy Management Service Only
Follow these steps only if all of these are true:
To enable Policy Management only:
- Load the installExisting.ldif file into your existing directory.
For detailed instructions, see "Adding Identity Server Object Classes to Existing Directory Entries" of this chapter.
- In the following file:
Identity_Server_root/config/ums/amserveradmin
change the filename ums.xml to umsExisitng.xml.
- To load all XML files, enter the following command:
Identity_Server_root/config/ums/amserveradmin
"user_naming_attibute=amadmin,ou=people,root_suffix" password- Restart Identity Server.
In the following directory:
Identity_Server_root/bin
execute the following command:
./amserver start
You can now log in to the Identity Server console to perform policy management tasks. See the Administration Guide for more information.If you want to enable user management later, follow steps in the next section.
Enabling Both User and Policy Management Services
Follow these steps only if all of these are true:
To enable both User and Policy Management:
- 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.
In the following directory:
Identity_Server_root/bin
execute the following command:
./amserver start
- Log in to Identity Server as amAdmin.
- In the to Service Configuration view, click Administrator.
- Check the "Enable User Management" box, and 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 5-8 Identity Server with data from existing MadisonParc DIT
Starting Identity Server and Logging InAfter you’ve installed Identity Server and configured Directory Server appropriately, you can check the installation. Start Identity Server 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 on UNIX
To start Identity Server manually, at the command line enter the following command:
/Identity_Server_root/SUNWam/bin/amserver start
To start Identity Server on Windows
You can start Identity Server using the command line, or using the Start Menu.
From the command line
Enter the following commands in a Command Prompt window:
cd Identity_Server_root\bin
amserver start
From the Start Menu
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.
When you log into Identity Server for the first time, 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 5-9 First-time login for MadisonParc
.
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 DIT for a fictitious company named MadisonParc. Figure 5-10 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=Identity_Server_root\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/db/prod/s1dirsrv.
Figure 5-10 The existing MadisonParc DIT
Sample Migration Scripts
The sample scripts included with Identity Server require Perl 5.x or later. Table Table 5-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 DIT 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 DIT
You can use one of two approaches for modifying the DIT. One option is to make all the necessary modifications to your DIT 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:
Directory_Server_root/shared/bin
- Set the $base variable to the base suffix of the DIT 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 5-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:
Directory_Server_root/shared/bin
- Be sure the $base variable is set to the base suffix of the DIT 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 5-2, bold indicates the change in the search scope.
Code Example 5-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 5-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:
Directory_Server_root/shared/bin
- Set the $base variable to the base suffix of the DIT 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 5-4, marker object class for the organizational units under dc=MadisonParc,dc=com is indicated in bold.
Code Example 5-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:
Directory_Server_root/shared/bin
- Be sure the $base variable is set to the base suffix of the DIT 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 DIT.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 5-5, the user marker object class is indicated in bold.
Code Example 5-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:
Directory_Server_root/shared/bin
- Set the $base variable to the base suffix of the DIT 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 5-6, marker object class for static groups is indicated in bold
Code Example 5-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:
Directory_Server_root/shared/bin
- Set the $base variable to the base suffix of the DIT 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 5-7, marker object class for a filtered group is indicated in bold.
Code Example 5-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)(obje ctc
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:
Directory_Server_root/shared/bin
- Set the $base variable to the base suffix of the DIT 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:
Directory_Server_root/shared/bin
- Be sure the $base variable is set to the base suffix of the DIT 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 5-8, the script changes are indicated in bold.
Code Example 5-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 5-9, marker object class for a group under dc=Customers is indicated in bold.
Code Example 5-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 DIT 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 DIT 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 DIT 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 DIT 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:
Identity_Server_root/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:
Identity_Server_root/bin
execute the following command:
./amadmin -u "user_naming_attibute=amadmin,ou=people,root_suffix" -w
password -s umsExisting.xmlTo Modify the Creation Templates
- Remove the DAI service. In the following directory:
Identity_Server_root/bin
execute the following command:
./amadmin -u "user_naming_attibute=amadmin,ou=people,root_suffix" -w
password -r DAI- Locate the following file:
- Modify any custom naming attributes. For example, the MadisonParc DIT 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 5-10, bold indicates the changed value. Note that three lines down, the naming attribute dc was changed by Identity Server during installation.
Code Example 5-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>
Code Example 5-11
<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:
Identity_Server_root/bin
execute the following command:
./amadmin -u "user_naming_attibute=amadmin,ou=people,root_suffix" -w password -s
Identity_Server_root/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 DIT 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:
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.
- In the following file:
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:
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.:
- Add values for the i18n Keys you created in Step 2 to the following file:
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:
Identity_Server_root/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. To determine which file and instructions you should use, follow these guidelines:
Figure illustrates the MadisonParc DIT after enabling both User Management and Policy Management services. Both installExisting.ldif and install.ldif files were loaded into an existing directory.
Figure 5-11 The MadisonParc DIT 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 DIT 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.
