Tivoli Identity Manager

Tivoli Identity Manager Version 4.6 Active Directory Adapter Installation and Configuration Guide SC32-1376-09

Tivoli Identity Manager Version 4.6 Active Directory Adapter Installation and Configuration Guide SC32-1376-09

Note: Before using this information and the product it supports, read the information in Appendix D, Notices, on page 71. Ninth Edition (June 2005) This edition applies to version 4.6 of this adapter and to all subsequent releases and modifications until otherwise indicated in new editions. Copyright International Business Machines Corporation 2003, 2005. All rights reserved. US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

Contents Preface............... v Who should read this book.........v Publications and related information......v Tivoli Identity Manager library.......v Prerequisite Product Publications...... vii Related Publications.......... viii Accessing publications online....... viii Accessibility..............ix Support information...........ix Conventions used in this book........ix Typeface conventions..........ix Operating system differences........x Definitions for HOME and other directory variables...............x Chapter 1. Overview of the Active Directory adapter........... 1 Features of the adapter...........1 Chapter 2. Installing and configuring the Active Directory adapter........ 3 Prerequisites..............3 Installing the adapter...........3 Importing the adapter profile into the Tivoli Identity Manager Server.............4 Importing the adapter profile........5 Creating an Active Directory service......5 Configuring the adapter..........6 Chapter 3. Configuring the Active Directory adapter for IBM Tivoli Identity Manager.............. 9 Starting the adapter configuration tool......9 Viewing configuration settings........10 Changing protocol configuration settings....10 Configuring event notification........13 Setting event notification triggers......16 Modifying an event notification context....17 Changing the configuration key.......19 Changing activity logging settings.......19 Changing registry settings.........21 Modifying non-encrypted registry settings...22 Changing advanced settings.........25 Viewing statistics............26 Changing code page settings........26 Accessing help and additional options.....27 Chapter 4. Configuring SSL authentication for the Active Directory adapter.............. 29 Overview of SSL and digital certificates.....29 Private keys, public keys, and digital certificates 30 Self-signed certificates..........30 Certificate and key formats........31 The use of SSL authentication........31 Configuring certificates for SSL authentication...32 Configuring certificates for one-way SSL authentication............32 Configuring certificates for two-way SSL authentication............33 Configuring certificates when the adapter operates as an SSL client.........34 Managing SSL certificates using CertTool....35 Starting CertTool...........35 Generating a private key and certificate request 37 Installing the certificate.........38 Installing the certificate and key from a PKCS12 file................38 Viewing the installed certificate.......39 Installing a CA certificate.........39 Viewing CA certificates.........39 Deleting a CA certificate.........39 Viewing registered certificates.......40 Registering a certificate.........40 Unregistering a certificate........40 Exporting a certificate and key to PKCS12 file..41 Chapter 5. Customizing the Active Directory adapter.......... 43 Step 1: Extend the schema and add the extended attributes...............43 Step 2. Copy the ADProfile.jar file and extract the files.................44 Step 3. Modify the exschema.txt file......44 Step 4: Update the schema.dsml file......45 Step 5: Modify the CustomLabels.properties file..45 Step 6: Create a new JAR file and install the new attributes on the Tivoli Identity Manager Server..46 Step 7: Optionally modify the adapter form...46 Managing passwords when restoring accounts...46 Configuring the base point for the adapter....47 Chapter 6. Upgrading the Active Directory adapter or the ADK..... 49 Upgrading the Active Directory adapter.....49 Upgrading the ADK...........49 Log files..............50 Chapter 7. Uninstalling the Active Directory adapter.......... 51 Appendix A. Files.......... 53 xforms.xml file.............53 schema.dsml file.............53 Object identifier............54 Attribute definition...........55 Classes...............55 Copyright IBM Corp. 2003, 2005 iii

CustomLabels.properties file.........56 Appendix B. Adapter attributes.... 57 Attribute descriptions...........57 Active Directory Adapter attributes by action...64 System Login Add...........64 System Login Change..........64 System Login Delete..........64 System Login Suspend.........64 System Login Restore..........65 Reconciliation............65 Appendix C. Support information... 67 Searching knowledge bases.........67 Search the information center on your local system or network...........67 Search the Internet...........67 Obtaining fixes.............68 Contacting IBM Software Support.......68 Determine the business impact of your problem 69 Describe your problem and gather background information.............69 Submit your problem to IBM Software Support 69 Appendix D. Notices......... 71 Trademarks..............72 Index............... 75 iv IBM Tivoli Identity Manager: Active Directory Adapter Installation and Configuration Guide

Preface Who should read this book The IBM Tivoli Identity Manager Active Directory Adapter (Active Directory Adapter) enables connectivity between the IBM Tivoli Identity Manager Server and a network of systems running the Active Directory Server. Once the adapter is installed and configured, Tivoli Identity Manager manages access to Active Directory resources with your site s security system. This book describes how to install and configure the Active Directory Adapter. Note: The program that is used to connect the managed resource to the Tivoli Identity Manager Server is now called an adapter. The term adapter replaces the previously used term agent. The user interface used to configure the adapter still refers to an adapter as an agent. This book is intended for Microsoft Windows system and security administrators responsible for installing software on their site s computer systems. Readers are expected to understand Windows concepts. The person completing the installation procedure must also be familiar with their site s system standards and needs to have appropriate Active Directory experience and knowledge. Readers must be able to perform routine Windows system and security administration tasks. Publications and related information Read the descriptions of the Tivoli Identity Manager library. To determine which additional publications you might find helpful, read the Prerequisite Product Publications on page vii and the Related Publications on page viii. After you determine the publications you need, refer to the instructions in Accessing publications online on page viii. Tivoli Identity Manager library The publications in the Tivoli Identity Manager technical documentation library are organized into the following categories: v Release information v Online user assistance v Server installation and configuration v Problem determination v Technical supplements v Adapter installation and configuration Release Information: v IBM Tivoli Identity Manager Release Notes Provides software and hardware requirements for Tivoli Identity Manager, and additional fix, patch, and other support information. v IBM Tivoli Identity Manager Documentation Read This First Card Lists the Tivoli Identity Manager publications. Online user assistance: Copyright IBM Corp. 2003, 2005 v

Provides online help topics and an information center for all Tivoli Identity Manager administrative tasks. The information center includes information that was previously provided in the IBM Tivoli Identity Manager Configuration Guide and the IBM Tivoli Identity Manager Policy and Organization Administration Guide. Server installation and configuration: IBM Tivoli Identity Manager Server Installation and Configuration Guide for WebSphere Environments provides installation and configuration information for Tivoli Identity Manager. Configuration information that was previously provided in the IBM Tivoli Identity Manager Configuration Guide is now included in either the installation guide or in the IBM Tivoli Identity Manager Information Center. Problem determination: IBM Tivoli Identity Manager Problem Determination Guide provides problem determination, logging, and message information for the Tivoli Identity Manager product. Technical supplements: The following technical supplements are provided by developers or by other groups who are interested in this product: v IBM Tivoli Identity Manager Performance Tuning Guide Provides information needed to tune Tivoli Identity Manager Server for a production environment, available on the Web at: http://publib.boulder.ibm.com/tividd/td/tdprodlist.html Click the I character in the A-Z product list, and then, click the Tivoli Identity Manager link. Browse the information center for the Technical Supplements section. v Redbooks and white papers are available on the Web at: http://www.ibm.com/software/sysmgmt/products/support/ IBMTivoliIdentityManager.html Browse to the Self Help section, in the Learn category, and click the Redbooks link. v Technotes are available on the Web at: http://www.redbooks.ibm.com/redbooks.nsf/tips/ v Field guides are available on the Web at: http://www.ibm.com/software/sysmgmt/products/support/field_guides.html v For an extended list of other Tivoli Identity Manager resources, search the following IBM developerworks Web address: http://www.ibm.com/developerworks/ Adapter installation and configuration: The Tivoli Identity Manager Server technical documentation library also includes an evolving set of platform-specific installation documents for the adapter components of a Tivoli Identity Manager Server implementation. Locate adapters on the Web at: vi IBM Tivoli Identity Manager: Active Directory Adapter Installation and Configuration Guide

http://www.lotus.com/services/passport.nsf/webdocs/ Passport_Advantage_Home Click Support & downloads. Browse to the Downloads and drivers. Click the link for the current inventory of adapters. Skills and training: The following additional skills and technical training information were available at the time that this manual was published: v Virtual Skills Center for Tivoli Software on the Web at: http://www.cgselearning.com/tivoliskills/ v Tivoli Education Software Training Roadmaps on the Web at: http://www.ibm.com/software/tivoli/education/eduroad_prod.html v Tivoli Technical Exchange on the Web at: http://www.ibm.com/software/sysmgmt/products/support/ supp_tech_exch.html Prerequisite Product Publications To use the information in this book effectively, you must have knowledge of the products that are prerequisites for Tivoli Identity Manager Server. Publications are available from the following locations: v Active Directory Server Microsoft Windows 2000 Server running Active Directory http://www.microsoft.com/windows2000/en/server/help/ Microsoft Windows 2003 Server running Active Directory http://www.microsoft.com/resources/documentation/ WindowsServ/2003/standard/proddocs/en-us/default.asp Microsoft Windows XP Server running Active Directory http://www.microsoft.com/resources/documentation/ Windows/XP/all/reskit/enus/Default.asp?url=/resources/documentation/Windows/XP/all/reskit/enus/prcf_omn_gjjv.asp v Operating systems IBM AIX http://www16.boulder.ibm.com/pseries/en_us/infocenter/base/aix52.htm Sun Solaris http://docs.sun.com/db?q=solaris+9 Red Hat Linux http://www.redhat.com/docs/ Microsoft Windows Server 2003 http://www.microsoft.com/windowsserver2003/proddoc/default.mspx v Database servers IBM DB2 - Support: http://www.ibm.com/software/data/db2/udb/support.html - Information center: http://publib.boulder.ibm.com/infocenter/db2help/index.jsp - Documentation: http://www.ibm.com/cgi-bin/db2www/data/db2/udb/ winos2unix/support/v8pubs.d2w/en_main Preface vii

Related - DB2 product family: http://www.ibm.com/software/data/db2 - Fix packs: http://www.ibm.com/software/data/db2/udb/support/downloadv8.html - System requirements: http://www.ibm.com/software/data/db2/udb/sysreqs.html Oracle http://www.oracle.com/technology/documentation/index.html http://otn.oracle.com/tech/index.html http://otn.oracle.com/tech/linux/index.html Microsoft SQL Server 2000 http://www.msdn.com/library/ http://www.microsoft.com/sql/ v Directory server applications IBM Directory Server http://publib.boulder.ibm.com/tividd/td/ibmds/idsapinst52/ en_us/html/ldapinst.htm http://www.ibm.com/software/network/directory Sun ONE Directory Server http://docs.sun.com/app/docs/coll/s1_directoryserver_52 v WebSphere Application Server Additional information is available in the product directory or Web sites. http://publib.boulder.ibm.com/infocenter/ws51help/index.jsp http://www.redbooks.ibm.com/ v WebSphere embedded messaging http://www.ibm.com/software/integration/wmq/ v IBM HTTP Server http://www.ibm.com/software/webservers/httpservers/library.html Publications Information that is related to Tivoli Identity Manager Server is available in the following publications: v The Tivoli Software Library provides a variety of Tivoli publications such as white papers, datasheets, demonstrations, redbooks, and announcement letters. The Tivoli Software Library is available on the Web at: http://www.ibm.com/software/tivoli/literature/ v The Tivoli Software Glossary includes definitions for many of the technical terms related to Tivoli software. The Tivoli Software Glossary is available from the Glossary link of the Tivoli Software Library Web page at: http://publib.boulder.ibm.com/tividd/glossary/tivoliglossarymst.htm Accessing publications online IBM posts publications for this and all other Tivoli products, as they become available and whenever they are updated, to the Tivoli software information center Web site. Access the Tivoli software information center at the following Web address: http://publib.boulder.ibm.com/tividd/td/tdprodlist.html viii IBM Tivoli Identity Manager: Active Directory Adapter Installation and Configuration Guide

Click the I character in the A-Z list, and then click the Tivoli Identity Manager link to access the product library. Note: If you print PDF documents on other than letter-sized paper, set the option in the File Print window that allows Adobe Reader to print letter-sized pages on your paper. Accessibility The product documentation includes the following features to aid accessibility: v Documentation is available in convertible PDF format to give the maximum opportunity for users to apply screen-reader software. v All images in the documentation are provided with alternative text so that users with vision impairments can understand the contents of the images. Support information If you have a problem with your IBM software, you want to resolve it quickly. IBM provides the following ways for you to obtain the support you need: v Searching knowledge bases: You can search across a large collection of known problems and workarounds, Technotes, and other information. v Obtaining fixes: You can locate the latest fixes that are already available for your product. v Contacting IBM Software Support: If you still cannot solve your problem, and you need to work with someone from IBM, you can use a variety of ways to contact IBM Software Support. For more information about these ways to resolve problems, see Appendix C, Support information, on page 67. Conventions used in this book Typeface This reference uses several conventions for special terms and actions and for operating system-dependent commands and paths. conventions This guide uses the following typeface conventions: Bold Italic v Lowercase commands and mixed case commands that are otherwise difficult to distinguish from surrounding text v Interface controls (check boxes, push buttons, radio buttons, spin buttons, fields, folders, icons, list boxes, items inside list boxes, multicolumn lists, containers, menu choices, menu names, tabs, property sheets), labels (such as Tip:, and Operating system considerations:) v Keywords and parameters in text v Words defined in text v Emphasis of words (words as words) v New terms in text (except in a definition list) v Variables and values you must provide Monospace Preface ix

v Examples and code examples v File names, programming keywords, and other elements that are difficult to distinguish from surrounding text v Message text and prompts addressed to the user v Text that the user must type v Values for arguments or command options Operating system differences This guide uses the UNIX convention for specifying environment variables and for directory notation. When using the Windows command line, replace $variable with %variable% for environment variables and replace each forward slash (/) with a backslash (\) in directory paths. The names of environment variables are not always the same in Windows and UNIX. For example, %TEMP% in the Windows operating system is equivalent to $tmp in a UNIX operating system. Note: If you are using the bash shell on a Windows system, you can use the UNIX conventions. Definitions for HOME and other directory variables The following table contains the default definitions that are used in this guide to represent the HOME directory level for various product installation paths. You can customize the installation directory and HOME directory for your specific implementation. If this is the case, you need to make the appropriate substitution for the definition of each variable represented in this table. The value of path varies for these operating systems: v Windows: drive:\program Files v AIX: /usr v Other UNIX: /opt Path Variable Default Definition Description DB_INSTANCE_HOME Windows: path\ibm\sqllib UNIX: v AIX, Linux: /home/dbinstancename v Solaris: /export/home/dbinstancename The directory that contains the database for Tivoli Identity Manager. x IBM Tivoli Identity Manager: Active Directory Adapter Installation and Configuration Guide

Path Variable Default Definition Description LDAP_HOME v For IBM Directory Server Version 5.2 The directory that contains the Windows: directory server path\ibm\ldap code. UNIX: AIX, Linux: path/ldap Solaris: path/ibmldaps path/ibm/ldap v For IBM Directory Server Version 6.0 Windows: path\ibm\ldap\v6.0 UNIX: path/ibm/ldap/v6.0 AIX, Solaris Linux: opt/ibm/ldap/v6.0 v For Sun ONE Directory Server Windows: path\sun\mps UNIX: /var/sun/mps IDS_instance_HOME For IBM Directory Server Version 6.0 Windows: drive\ ibmslapd-instance_owner_name The directory that contains the IBM Directory Server Version 6.0 instance. The value of drive might be C:\ on Windows systems. An example of instance_owner_name might be ldapdb2. For example, the log file might be C:\idsslapd-ldapdb2\logs\ibmslapd.log. UNIX: INSTANCE_HOME/idsslapd-instance_name HTTP_HOME On Linux and AIX systems, the default home directory is the /home/instance_owner_name directory. On Solaris systems, for example, the directory is the /export/home/ldapdb2/idsslapdldapdb2 directory. Windows: path\ibmhttpserver UNIX: path/ibmhttpserver The directory that contains the IBM HTTP Server code. Preface xi

Path Variable Default Definition Description ITIM_HOME WAS_HOME WAS_MQ_HOME WAS_NDM_HOME Tivoli_Common_Directory Windows: path\ibm\itim UNIX: path/ibm/itim Windows: path\websphere\appserver UNIX: path/websphere/appserver Windows: path\ibm\websphere MQ UNIX: path/mqm Windows: path\websphere\deploymentmanager UNIX: path/websphere/deploymentmanager Windows: path\ibm\tivoli\common\ctgim UNIX: path/ibm/tivoli/common/ctgim The base directory that contains the Tivoli Identity Manager code, configuration, and documentation. The WebSphere Application Server home directory The directory that contains the WebSphere MQ code. The home directory on the deployment manager The central location for all serviceability-related files, such as logs and first-failure capture data xii IBM Tivoli Identity Manager: Active Directory Adapter Installation and Configuration Guide

Chapter 1. Overview of the Active Directory adapter Features of the adapter An adapter is a program that provides an interface between a managed resource and the Tivoli Identity Manager Server. Adapters might or might not reside on the managed resource and the Tivoli Identity Manager Server manages access to the resource by using your security system. Adapters function as trusted virtual administrators on the target platform, performing such tasks as creating login IDs, suspending IDs, and performing other functions administrators normally run manually. The adapter runs as a service, independent of whether or not a user is logged on to the Tivoli Identity Manager Server. The IBM Tivoli Identity Manager Active Directory Adapter enables connectivity between the Tivoli Identity Manager Server and a system running the Active Directory Server. This installation guide provides the basic information that you need to install and configure the Active Directory Adapter. This chapter provides an overview of the adapter and the features of the adapter. You can use the Active Directory Adapter to automate the following administrative tasks: v Creating an Active Directory account Use the adapter to create an Active Directory account on Windows 2000 and Windows 2003 domain servers. v Managing an Active Directory account Use the adapter to manage an Active Directory account on Windows 2000 and Windows 2003 domain servers. v Managing an Exchange Mailbox Use the adapter to manage Exchange 2000 and Exchange 2003 Mailboxes with the Active Directory domain. v Creating home directories Use the adapter to create home directories. The Active Directory Adapter does not create or manage local system accounts. Use the Windows Local Account Adapter for this purpose. The Active Directory Adapter requires administrator authority. Tivoli Identity Manager requests will fail if the adapter is not given sufficient authority to perform the requested task. The adapter must be installed on a Windows 2000, Windows 2003 or Windows XP workstation. The Active Directory Adapter can be installed within the domain being managed or in a different domain. If the adapter is installed in a different domain, both the domain being managed and the domain where the adapter is installed must have trusts configured. For more information on configuring trusts for domains, see the Microsoft documentation that corresponds to your operating system. Configure the Active Directory Adapter to support both sub-domains and multiple domains through the Base Point feature on the adapter service form. While the best deployment for your environment is based on the topology of your Windows Copyright IBM Corp. 2003, 2005 1

domain and Active Directory structure, the primary factor is the planned design of your Tivoli Identity Manager provisioning policies and approval workflow process. For more information on provisioning policies and approval workflow, see the Tivoli Identity Manager Information Center. 2 IBM Tivoli Identity Manager: Active Directory Adapter Installation and Configuration Guide

Chapter 2. Installing and configuring the Active Directory adapter Installing and configuring the Active Directory Adapter involves several steps that you must complete in the appropriate sequence. Review the prerequisites before you begin the installation process. You can also create an account on the managed resource for the adapter to use. Prerequisites Table 1 identifies hardware, software, and authorization prerequisites for installing the Active Directory Adapter. Verify that all of the prerequisites have been met before installing the Active Directory Adapter. Table 1. Prerequisites to install the adapter System v A 32-bit x86-based microprocessor. v A minimum of 256 MB of memory. v At least 300 MB of free disk space. Operating System v Windows 2000 v If you plan to manage Exchange Mailbox, the Exchange administration tools must be installed. v Windows 2003 v Windows XP Network Connectivity v TCP/IP network System Administrator Authority Tivoli Identity Manager Server Version 4.6 A Windows Server running Active Directory must be operational in the domain of the system where the adapter is installed. v For security purposes, the adapter must be installed on a Windows NT File System (NTFS). The person completing the Active Directory Adapter installation procedure must have system administrator authority to complete the steps in this chapter. Installing the adapter The Tivoli Identity Manager Active Directory Adapter installation program is available for download from the IBM Web site. Contact your IBM account representative for the Web address and download instructions. In order to install the adapter, complete the following steps: 1. Download the Active Directory Adapter compressed file from the IBM Web site. 2. Extract the contents of the compressed file into a temporary directory and navigate to that directory. 3. Start the installation program using the setup.exe file in the temporary directory. For example, select Run from the Start menu, and type C:\TEMP\setup.exe in the Open field. Copyright IBM Corp. 2003, 2005 3

4. On the Welcome window, click Next. 5. On the License Agreement window, review the license agreement and decide if you accept the terms of the license. If you do, select Accept and then click Next. 6. On the Select Destination Directory window, specify where you want to install the adapter in the Directory Name field. You can accept the default location, or click Browse to specify a different directory. Then, click Next. Figure 1. Select Destination Directory dialog window 7. On the Install Summary window, review the installation settings. Click Back to change any of these settings. Otherwise, click Next to begin the installation. 8. On the Install Completed window, click Finish to exit the program. Importing the adapter profile into the Tivoli Identity Manager Server Before you can add an adapter as a service to the Tivoli Identity Manager Server, the server must have an adapter profile to recognize the adapter as a service. The files that are packaged with the Active Directory Adapter include the adapter JAR file, ADProfile.jar. Using the Import feature of the Tivoli Identity Manager Server, you can import the adapter profile into the server as a service profile. The ADProfile.jar file includes all of the files that are needed to define the adapter schema, account form, service form, and profile properties. The ADProfile.jar file will be referenced in this document to make any changes to the schema or the profile. You will be required to extract the files from the JAR file, make changes to the necessary files, and repackage the JAR file with the updated files. For more information on how to update the JAR files, see Step 2. Copy the ADProfile.jar file and extract the files on page 44. 4 IBM Tivoli Identity Manager: Active Directory Adapter Installation and Configuration Guide

Importing the adapter profile An adapter profile defines the types of resources that the Tivoli Identity Manager Server can manage. You must import the adapter profile into the Tivoli Identity Manager Server before using the Active Directory Adapter. The profile is used to create a Active Directory Adapter service on the Tivoli Identity Manager Server and to communicate with the adapter. Before you begin to import the adapter profile, verify that the following conditions are met: v Before importing the adapter profile, the Tivoli Identity Manager Server must be installed and running. v In order to configure the Active Directory Adapter profile, you must have root or Administrator authority on the Tivoli Identity Manager Server. In order to import the adapter profile, complete the following steps: 1. Log into the Tivoli Identity Manager Server using an account that has the authority to perform administrative tasks. 2. On the Main Menu Navigation Bar, select the Configuration tab. 3. On the Configuration window, select Import/Export Import tabs. 4. On the Import window, in the File to Upload field, type the location of the ADProfile.jar file, or click Browse to locate the file. 5. Click the Import data into Identity Manager link to import the adapter profile into the Tivoli Identity Manager Server. v If the adapter profile import completes successfully, the following message is displayed: Profile installation complete. v If the adapter profile import fails, the following message is displayed: Profile installation failed. Creating an Active Directory service When you import the adapter profile, if you receive an error related to the schema, the trace.log file will contain information about that error. The trace.log file location is specified by the handler.file.filedir property that is defined in the Tivoli Identity Manager enrolelogging.properties file, which is installed in the Tivoli Identity Manager \data directory. After the adapter profile is imported into the Tivoli Identity Manager Server, you must create a provisioning service to allow Tivoli Identity Manager to communicate with the adapter. In order to create a provisioning service, complete the following steps: 1. Log into the Tivoli Identity Manager Server using an account that has the authority to perform administrative tasks. 2. On the Main Menu Navigation Bar, click the Provisioning tab. 3. On the Provisioning window, click the Manage Services tab. 4. On the Manage Services window, click Add. 5. From the list of service types, select AD Profile, and then click Continue. The Active Directory Adapter service form is displayed. The service form contains the following fields: Chapter 2. Installing and configuring the Active Directory adapter 5

Service Name Specify a name that defines this Active Directory service on the Tivoli Identity Manager Server. Service Name is a required field. Description Specify a description for this service. Description is an optional field. URL Specify the location and port number of the Active Directory Adapter. The port number is defined in the protocol configuration using the agentcfg program. For additional information about protocol configuration settings, see Changing protocol configuration settings on page 10. URL is a required field. User Configuring the adapter If https is specified as part of the URL, the adapter must be configured to use SSL authentication. If the adapter is not configured to use SSL authentication, specify http for the URL. For additional information about configuring the adapter to use SSL authentication, see Chapter 4, Configuring SSL authentication for the Active Directory adapter, on page 29. Id Specify the Directory Access Markup Language (DAML) protocol user name. The user name is defined in the protocol configuration using the agentcfg program. For additional information about the protocol configuration settings, see Changing protocol configuration settings on page 10. User Id is a required field. Password Specify the password for the DAML protocol user name. This password is defined in the protocol configuration using the agentcfg program. For additional information about the protocol configuration settings, see Changing protocol configuration settings on page 10. Password is a required field. Base Point DN Specify the DN of the domain name, extended to allow any base point, for example: v ou=users,dc=ibm,dc=com v ADServer/ou=user,dc=ibm,dc=com Base Point DN is an optional field. Administration User Account Specify the user ID that is used to connect to the Active Directory. Administration User Account is an optional field. Administration User Password Specify the password for the user ID that is used to connect to the Active Directory. Administration User Password is an optional field. 6. To verify the connection, press Test. 7. To create the service, press Submit. Once you have installed the Tivoli Identity Manager Active Directory Adapter, configuration is required to ensure that it functions properly. In order to configure the Active Directory Adapter, complete the following steps: 1. Start the Active Directory Adapter service using the Windows Services Tool. 6 IBM Tivoli Identity Manager: Active Directory Adapter Installation and Configuration Guide

2. Configure DAML to ensure communication with the Tivoli Identity Manager Server. For more information on configuring DAML, see Changing protocol configuration settings on page 10. 3. Configure the Active Directory Adapter to communicate with the Tivoli Identity Manager Server by configuring the adapter for event notification. For more information on configuring event notification, see Configuring event notification on page 13. 4. For secure communication, install a certificate on the machine where the adapter resides and on the Tivoli Identity Manager Server. For more information on installing certificates, see Chapter 4, Configuring SSL authentication for the Active Directory adapter, on page 29. 5. Add optional extended attributes to the schema of the adapter. For more information on extending the attributes, see Chapter 5, Customizing the Active Directory adapter, on page 43. 6. Install the adapter profile on the Tivoli Identity Manager Server. For more information on installing the adapter profile, see Importing the adapter profile into the Tivoli Identity Manager Server on page 4. 7. Configure the adapter service form. For more information on configuring the service form, see Creating an Active Directory service on page 5. 8. Use the agentcfg utility to modify the adapter parameters. For more information on parameter configuration, see Chapter 3, Configuring the Active Directory adapter for IBM Tivoli Identity Manager, on page 9. 9. Configure the adapter account form. For more information on configuring the account form, see Configuring the base point for the adapter on page 47. Chapter 2. Installing and configuring the Active Directory adapter 7

8 IBM Tivoli Identity Manager: Active Directory Adapter Installation and Configuration Guide

Chapter 3. Configuring the Active Directory adapter for IBM Tivoli Identity Manager Use the adapter configuration program, agentcfg, in order to view or modify the Active Directory Adapter parameters. All changes that you make to parameters with this tool take effect immediately. Starting the adapter configuration tool In order to start the adapter configuration tool, agentcfg, for Active Directory Adapter parameters, complete these steps: 1. From the Start Menu, select Programs Accessories Command Prompt. 2. At the command prompt, change to the \bin directory for the adapter. For example, type the following command, if the Active Directory Adapter is in the default location: cd \Tivoli\Agents\ADAgent\bin 3. Type the following command: agentcfg -agent ADAgent You can also use agentcfg to view or change configuration settings from a remote computer. See the table in Accessing help and additional options on page 27 for procedures on using additional arguments. 4. At the Enter configuration key for Agent ADAgent prompt, type the configuration key for the Active Directory Adapter. The default configuration key is agent. You must change the configuration key once installation completes, to prevent unauthorized access to the configuration of the adapter. See Changing protocol configuration settings on page 10 for procedures to change the configuration key. The Main Configuration Menu is displayed. ADAgent 4.6 Agent Main Configuration Menu ------------------------------------------- A. Configuration Settings. B. Protocol Configuration. C. Event Notification. D. Change Configuration Key. E. Activity Logging. F. Registry Settings. G. Advanced Settings. H. Statistics. I. Codepage Support. X. Done. Select menu option: From the Main Menu, you can configure the protocol, view statistics, and modify settings, including configuration, registry, and advanced settings. Table 2. Options for the main configuration menu Option Configuration task For more information A Viewing configuration settings See page 10. Copyright IBM Corp. 2003, 2005 9

Table 2. Options for the main configuration menu (continued) B Changing protocol configuration settings See page 10. C Configuring event notification See page 13. D Changing the configuration key See page 19. E Changing activity logging settings See page 19. F Changing registry settings See page 21. G Changing advanced settings See page 25. H Viewing statistics See page 26. I Changing code page settings See page 26. Viewing configuration settings The following procedure describes how to view the Active Directory Adapter configuration settings. 1. At the Agent Main Configuration Menu, type A. The configuration settings for the Active Directory Adapter are displayed. The following screen is an example of the Active Directory Adapter configuration settings. Configuration Settings ------------------------------------------- Name : ADAgent Version : 4.6 ADK Version : 4.65 ERM Version : 4.65 License : NONE Asynchronous ADD Requests : TRUE (Max.Threads:3) Asynchronous MOD Requests : TRUE (Max.Threads:3) Asynchronous DEL Requests : TRUE (Max.Threads:3) Asynchronous SEA Requests : TRUE (Max.Threads:3) Available Protocols : DAML Configured Protocols : DAML Logging Enabled : TRUE Logging Directory : C:\Tivoli\Agents\ADAgent\Log Log File Name : ADAgent.log Max. log files : 3 Max.log file size (Mbytes) : 1 Debug Logging Enabled : TRUE Detail Logging Enabled : FALSE Press any key to continue 2. Press any key to return to the Main Menu. Changing protocol configuration settings The Active Directory Adapter uses the DAML protocol to communicate with the Tivoli Identity Manager Server. By default, when the adapter is installed, the DAML protocol is configured to be used in nonsecure mode. In order to configure a secure environment, you must configure the DAML protocol to use SSL and install a certificate. Refer to Installing the certificate on page 38 for more information about installing certificates. In previous versions of this adapter, you could add and remove protocols. However, in the latest version of this adapter, the DAML protocol is the only supported protocol that you can use. Therefore, you will not need to add or remove a protocol. 10 IBM Tivoli Identity Manager: Active Directory Adapter Installation and Configuration Guide

In order to configure the DAML protocol for the Active Directory Adapter, complete the following steps: 1. At the Agent Main Configuration Menu, type B. The DAML protocol is configured and available by default for the Active Directory Adapter. Agent Protocol Configuration Menu ----------------------------------- Available Protocols: DAML Configured Protocols: DAML A. Add Protocol. B. Remove Protocol. C. Configure Protocol. X. Done Select menu option 2. At the Agent Protocol Configuration Menu, type C. The DAML Protocol Properties Menu is displayed. 3. At the DAML Protocol Properties Menu, type C. The protocol properties for the configured protocol are displayed. The properties on your menu might be different from the ones shown in the examples. The following screen is an example of the DAML protocol properties: DAML Protocol Properties -------------------------------------------------------------------- A. USERNAME ****** ;Authorized user name. B. PASSWORD ****** ;Authorized user password. C. MAX_CONNECTIONS 100 ;Max Connections. D. PORTNUMBER 45580 ;Protocol Server port number. E. USE_SSL FALSE ;Use SSL secure connection. F. SRV_NODENAME 9.38.215.20 ;Event Notif. Server name. G. SRV_PORTNUMBER 9443 ;Event Notif. Server port number. H. VALIDATE_CLIENT_CE FALSE ;Require client certificate. I. REQUIRE_CERT_REG FALSE ;Require registered certificate. X. Done Select menu option: 4. Type the letter of the menu option that you want to configure. See Table 3 below for additional information about the properties that you can configure for the DAML protocol. Table 3. Options for the DAML protocol menu Option Configuration task A The following prompt is displayed: Modify Property USERNAME : Type a user ID. This value is the user ID that the Tivoli Identity Manager Server uses to connect to the adapter. The default user ID is agent. Chapter 3. Configuring the Active Directory adapter for IBM Tivoli Identity Manager 11

Table 3. Options for the DAML protocol menu (continued) Option Configuration task B The following prompt is displayed: Modify Property PASSWORD : Type a password. This value is the password for the user ID that the Tivoli Identity Manager Server uses to connect to the adapter. The default password is agent. C The following prompt is displayed: Modify Property MAX_CONNECTIONS : Enter the maximum number of concurrent open connections that the adapter supports. The default number is 100. D The following prompt is displayed: Modify Property PORTNUMBER : Type a different port number. This value is the port number that the Tivoli Identity Manager Server uses to connect to the adapter. The default port number is 45580. E The following prompt is displayed: Modify Property USE_SSL : Enter TRUE or FALSE to specify whether a secure SSL connection will be used to connect to or from the adapter. The default value is FALSE. You must install a certificate when USE_SSL is set to TRUE. For more information on certificate installation, see Installing the certificate on page 38. F The following prompt is displayed: Modify Property SRV_NODENAME : Type a server name or an IP address, for example, 9.38.215.20. This value is the DNS name or IP address of the Tivoli Identity Manager Server that is used for event notification and asynchronous request processing. Note: If your platform supports Internet Protocol version 6 (IPv6) connections, you can specify an IPv6 server. G The following prompt is displayed: Modify Property SRV_PORTNUMBER : Type a different port number to access the Tivoli Identity Manager Server. This value is the port number that the adapter uses to connect to the Tivoli Identity Manager Server. The default port number is 9443. 12 IBM Tivoli Identity Manager: Active Directory Adapter Installation and Configuration Guide

Table 3. Options for the DAML protocol menu (continued) Option Configuration task H The following prompt is displayed: Modify Property VALIDATE_CLIENT_CE : Type TRUE to require the Tivoli Identity Manager Server to send a certificate when it communicates with the adapter. Type FALSE to allow the Tivoli Identity Manager Server to communicate with the adapter without a certificate. The default value is FALSE. Notes: 1. If you set this option to TRUE, you must configure options D through H. 2. The property name is actually VALIDATE_CLIENT_CERT. It is truncated by agentcfg to fit onto the screen. 3. You must use CertTool to install the appropriate CA certificates and optionally register the Tivoli Identity Manager Server certificate. For more information on using CertTool, see Managing SSL certificates using CertTool on page 35. I The following prompt is displayed: Modify Property REQUIRE_CERT_REG : This value only applies when option H is set to TRUE. Type TRUE to require the client certificate from the Tivoli Identity Manager Server to be registered with the adapter before it will accept an SSL connection. Type FALSE to require the client certificate only be verified against the list of CA certificates. The default value is FALSE. For more information on certificates, see Chapter 4, Configuring SSL authentication for the Active Directory adapter, on page 29. Configuring event notification 5. At the prompt, change the value, and press Enter. The Protocol Properties Menu is displayed with your new settings. If you do not want to change the value, just press Enter to return to the Protocol Properties Menu. 6. Repeat steps 4 and 5 to configure as many protocol properties as you need to. 7. At the Protocol Properties Menu, type X to exit the menu. Event notification is a feature of the Active Directory Adapter that updates the Tivoli Identity Manager Server at set intervals. Event notification detects changes that are made on the managed resource and updates the Tivoli Identity Manager Server with the changes. You can enable event notification if you want to have updated information from the managed resource sent back to the Tivoli Identity Manager Server between full reconciliations. Event notification is not intended to replace reconciliations on the Tivoli Identity Manager Server. When event notification is enabled, a database of the reconciliation data is kept on the machine where the adapter is installed. The database is updated with the changes that are requested by the Tivoli Identity Manager Server and will remain synchronized with the server. You can specify an interval for the event notification Chapter 3. Configuring the Active Directory adapter for IBM Tivoli Identity Manager 13

process to compare the database to data that currently exists on the managed resource. When the interval has elapsed, any differences between the managed resource and the database are forwarded to the Tivoli Identity Manager Server and updated in the local snapshot database. There are several steps to enabling event notification. These steps assume that the adapter is communicating successfully with the managed resource and the Tivoli Identity Manager Server. First, you must configure the host name, port number, and login information for the Tivoli Identity Manager Server. In order to identify the server for the DAML protocol to use, complete the following steps: 1. At the Agent Protocol Configuration Menu, select Configure Protocol. For more information on configuring a protocol, see Changing protocol configuration settings on page 10. 2. Type the letter of the menu option for the SRV_NODENAME property. 3. Specify the IP address or server name that identifies the Tivoli Identity Manager Server, and press Enter. The Protocol Properties Menu is displayed with your new settings. 4. Type the letter of the menu option for the SRV_PORTNUMBER property. 5. Specify the port number that the adapter uses to connect to the Tivoli Identity Manager Server for event notification and press Enter. The Protocol Properties Menu is displayed with your new settings. The example menu shows all of the options displayed when Event Notification is enabled. If Event Notification is disabled, not all of the options are displayed. In order to set Event Notification for the Tivoli Identity Manager Server, complete the following steps: 1. At the Agent Main Configuration Menu, type C. The Event Notification Menu is displayed. Event Notification Menu -------------------------------------------------------------- * Reconciliation interval : 1 day(s) * Next Reconciliation time : 23 hour(s) 56 min(s). 23 sec(s). * Configured Contexts : Jupiter, dd309 A. Enabled B. Time interval between reconciliations. C. Set Processing cache size. (currently: 50 Mbytes) D. Start event notification now. E. Set attributes to be reconciled. F. Reconciliation process priority. (current: 1) G. Add Event Notification Context. H. Modify Event Notification Context. I. Remove Event Notification Context. J. List Event Notification Contexts. X. Done Select menu option: Note: This menu shows all of the options that are displayed when Event Notification is enabled. If Event Notification is disabled, all of the options will not be displayed. 2. Type the letter of the menu option that you want to change. Option A must be enabled in order for the values of the other options to take effect. 14 IBM Tivoli Identity Manager: Active Directory Adapter Installation and Configuration Guide

Press Enter to return to the Agent Event Notification Menu without changing the value. Table 4. Options for the event notification menu Option Configuration task A If this option is enabled, the adapter updates the Tivoli Identity Manager Server with changes to the adapter at regular intervals. When the option is set to: v Disabled, pressing the A key changes the value to enabled v Enabled, pressing the A key changes the value to disabled Type A to toggle between the options. B The following prompt is displayed: Enter new interval ([ww:dd:hh:mm:ss]) Type a different reconciliation interval. For example, [00:01:00:00:00] Note: This value is the interval to wait once event notification completes before it is run again. The event notification process is resource intensive, therefore this value must not be set to run too frequently. C The following prompt is displayed: Enter new cache size[5]: Type a different value to change the processing cache size. D If this option is selected, event notification is started. E The Event Notification Entry Types Menu is displayed. See Setting event notification triggers on page 16 for more information. F The following prompt is displayed: Enter new thread priority [1-10]: Type a different thread value to change the event notification process priority. Setting the thread priority to a lower value reduces the impact that the event notification process has on the performance of the adapter. A lower value might also cause event notification to take longer. G The following prompt is displayed: Context name: Type the new context name, and press Enter. The new context is added. H A menu listing the available contexts is displayed. See Modifying an event notification context on page 17 for more information. I The Remove Context Menu is displayed. Select the context to remove. The following prompt is then displayed: Delete context context1? [no]: Press Enter to exit without deleting the context, or type Yes and press Enter to delete the context. Chapter 3. Configuring the Active Directory adapter for IBM Tivoli Identity Manager 15

Table 4. Options for the event notification menu (continued) Option Configuration task J The Event Notification Contexts are displayed in the following format: Context Name : Context1 Target DN : erservicename=context1,o=ibm, ou=ibm,dc=com --- Attributes for search request --- {search attributes listed} ----------------------------------------------- 3. If you changed the value for options B, C, E, or F, press Enter. The other options are automatically changed when you type the corresponding letter of the menu option. The Event Notification Menu is displayed with your new settings. Setting event notification triggers By default, all attributes are queried for value changes. Certain attributes that change frequently (for example, password age or last successful logon) must be omitted. 1. At the Event Notification Menu, type E. The Event Notification Entry Types Menu is displayed. Event Notification Entry Types ------------------------------------------- A. USER B. GROUP X. Done Select menu option: The USER and GROUP types will not appear in the above menu until the following conditions have been met: a. Event notification has been enabled b. A context has been created and configured c. A full reconciliation has been run 2. Type A for a list of the attributes returned during a user reconciliation, or type B for attributes returned during a group reconciliation. The Event Notification Attribute Listing for the selected reconciliation type is displayed. The default setting lists all attributes that the adapter supports. The example below lists example attributes, and might differ from the list that is displayed on your machine. Event Notification Attribute Listing ------------------------------------- (a) **eradealias (b) **eradallowdialin (c) **eradbadlogincount (d) **eradbasepoint (e) **ercompany (f) **eradcontainer (g) **eradcontainercn (h) **eradcontainerdn (i) **eradcontainerrdn (j) **eradcountycode (k) **eradedelegates (l) **erdepartment (m) **eraddisplayname (n) **eraddomainpassword (o) **eraddomainuser (p) **erdivision (q) **erademployeeid (r) **eradexpirationdate (p)rev page 1 of 3 (n)ext ----------------------------- X. Done Select menu option: 3. Type the letter option for the attribute to exclude from an event notification. 16 IBM Tivoli Identity Manager: Active Directory Adapter Installation and Configuration Guide

Attributes that are marked with two asterisks (**) are returned during the event notification. Attributes that are not marked with asterisks are not returned during the event notification. Modifying an event notification context An event notification context corresponds to a service on the Tivoli Identity Manager Server. Some adapters support multiple services. One Active Directory Adapter can have several Tivoli Identity Manager services, by specifying a different base point for each service. The base point for the Active Directory Adapter is the point in the directory server that is used as the root for the adapter. This point can be an organizational unit (OU) or domain container (DC) base point. Because the base point is an optional value, if a value is not specified, the adapter uses the default domain of the machine on which it is installed. You can have multiple event notification contexts, but you must have at least one adapter. In the example screen below, note that Context1, Context2, and Context3 are three different contexts, all having a different base point. In order to modify an event notification context, complete the following steps: 1. At the Event Notification Menu, type H. The Modify Context Menu is displayed. Modify Context Menu ------------------------------ A. Context1 B. Context2 C. Context3 X. Done Select menu option: 2. Type the letter of the menu option that you want to modify. The Modify Context Menu for the selected context is displayed. A. Set attributes for search B. Target DN: C. Delete Baseline Database X. Done Select menu option: Table 5. Options for the modify context menu Option Configuration task For more information A Adding search attributes for event notification See page 17. B Configuring the target DN for event notification contexts C Removing the baseline database for event notification contexts See page 18. See page 19. Adding search attributes for event notification For some adapters, you might need to specify an attribute-value pair for one or more contexts. These attribute-value pairs, which are defined by completing the steps below, serve multiple purposes: v When multiple services are supported by a single adapter, each service needs to specify one or more attributes to differentiate it from the other services. Chapter 3. Configuring the Active Directory adapter for IBM Tivoli Identity Manager 17

v The search attributes are passed to the event notification process, once the event notification interval has occurred or is started manually. For each context, a full search request is sent to the adapter. Additionally, the attributes specified for that context are passed to the adapter. v When the Tivoli Identity Manager Server initiates a reconciliation process, the adapter replaces the local database that represents this service with the new database. In order to add search attributes, complete the following steps: 1. At the Modify Context Menu for the context, type A. The Reconciliation Attribute Passed to Agent Menu is displayed. Reconciliation Attributes Passed to Agent for Context: Context1 ---------------------------------------------------- ---------------------------------------------------- A. Add new attribute B. Modify attribute value C. Remove attribute X. Done Select menu option: The valid attributes for the Active Directory Adapter are: v v eradbasepoint eraddomainuser v eraddomainpassword If you modify these attributes, the new value must be the same as what is entered on the adapter service form. If the field is blank on the service form, you do not have to specify an attribute value. 2. Type the letter of the menu option that you want to change. The supported attribute names will be displayed with two asterisks (**) in front of each name. When you type the letter of an attribute, it will toggle the asterisks on and off. Attributes without asterisks will not be updated during an event notification. The Reconciliation Attributes Passed to Agent Menu is displayed with the changes displayed. Configuring the target DN for event notification contexts The target DN field holds the unique name of the service that receives event notification updates. In order to configure the target DN, complete the following steps: 1. At the Modify Context Menu for the context, type B. 2. At the Enter Target DN prompt, type the target DN for the context, and press Enter. The target DN for the event notification context must be in the following format: erservicename=erservicename,o=organizationname,ou=tenantname,rootsuffix Each element of the DN is defined as follows: Table 6. DN elements and definitions Element Definition erservicename Specifies the name of the target service o Specifies the name of the organization 18 IBM Tivoli Identity Manager: Active Directory Adapter Installation and Configuration Guide

Table 6. DN elements and definitions (continued) Element Definition ou Specifies the name of the tenant in which the organization is in rootsuffix Specifies the root of the directory tree The Modify Context Menu is displayed with the new target DN listed. Removing the baseline database for event notification contexts This option is only available once a context is created and a reconciliation is run on the context to create a Baseline Database file. At the Modify Context Menu for the context, type C. The Modify Context Menu is displayed with the Delete Baseline Database option removed. Changing the configuration key You use the configuration key as a password to access the configuration tool for the adapter. In order to change the Active Directory Adapter configuration key, complete the following steps: 1. At the Main Menu prompt, type D. 2. Change the value of the configuration key, and press Enter. Press Enter to return to the Main Configuration Menu without changing the configuration key. The default configuration key is agent. Make sure that you choose passwords that cannot be easily guessed. The following message is displayed: Configuration key successfully changed. Changing activity logging settings The configuration program exits, and the Main Menu prompt is displayed. When you enable logging, Active Directory Adapter maintains a dated log file of all transactions, WinADAgent.log. By default, the log file is in the \log directory. In order to change the Active Directory Adapter activity logging settings, complete the following steps: 1. At the Main Menu prompt, type E. The Agent Activity Logging Menu is displayed. The following example shows the default activity logging settings. Chapter 3. Configuring the Active Directory adapter for IBM Tivoli Identity Manager 19

Agent Activity Logging Menu ------------------------------------- A. Activity Logging (Enabled). B. Logging Directory (current: C:\Tivoli\Agents\ADAgent\Log). C. Activity Log File Name (current: ADAgent.log). D. Activity Logging Max. File Size ( 1 mbytes) E. Activity Logging Max. Files ( 3 ) F. Debug Logging (Enabled). G. Detail Logging (Disabled). H. Base Logging (Disabled). I. Thread Logging (Disabled). X. Done Select menu option: 2. Type the letter of the menu option that you want to change. Option A must be enabled in order for the values of the other options to take effect. Press Enter to return to the Agent Activity Logging Menu without changing the value. Table 7. Options for the activity logging menu Option Configuration task A Set this option to enabled to have the adapter maintain a dated log file of all transactions. When the option is set to: v Disabled, pressing the A key changes to enabled v Enabled, pressing the A key changes to disabled Type A to toggle between the options. B The following prompt is displayed: Enter log file directory: Type a different value for the logging directory, for example, C:\Log. When the logging option is enabled, details about each access request are stored in the logging file that is in this directory. C The following prompt is displayed: Enter log file name: Type a different value for the log file name. When the logging option is enabled, details about each access request are stored in the logging file. D The following prompt is displayed: Enter maximum size of log files (mbytes): Type a new value, for example, 10. The oldest data is archived when the log file reaches the maximum file size. File size is measured in megabytes. It is possible for the activity log file size to exceed disk capacity. E The following prompt is displayed: Enter maximum number of log files to retain: Type a new value up to 100, for example, 5. The adapter automatically deletes the oldest activity logs beyond the specified limit. 20 IBM Tivoli Identity Manager: Active Directory Adapter Installation and Configuration Guide

Table 7. Options for the activity logging menu (continued) Option Configuration task F If this option is set to enabled, the adapter includes the debug statements in the log file of all transactions. When the option is set to: v Disabled, pressing the F key changes the value to enabled v Enabled, pressing the F key changes the value to disabled Type F to toggle between the options. G If this option is set to enabled, the adapter maintains a detailed log file of all transactions. The detail logging option must be used for diagnostic purposes only. Detailed logging enables more messages from the adapter and might increase the size of the logs. When the option is set to: v Disabled, pressing the G key changes the value to enabled v Enabled, pressing the G key changes the value to disabled Type G to toggle between the options. H If this option is set to enabled, the adapter maintains a log file of all transactions in the Adapter Development Kit (ADK) and library files. Base logging will substantially increase the size of the logs. When the option is set to: v Disabled, pressing the H key changes the value to enabled v Enabled, pressing the H key changes the value to disabled Type H to toggle between the options. I If this option is enabled, the log file will contain thread IDs, in addition to a date and timestamp on every line of the file. When the option is set to: v Disabled, pressing the I key changes the value to enabled v Enabled, pressing the I key changes the value to disabled Type I to toggle between the options. Changing registry settings 3. Press Enter if you changed the value for option B, C, D, or E. The other options are changed automatically when you type the corresponding letter of the menu option. The Agent Activity Logging Menu is displayed with your new settings. In order to change the Active Directory Adapter registry settings, complete the following steps: 1. At the Main Menu, type F. The Registry Menu is displayed. ADAgent 4.6 Agent Registry Menu ------------------------------------------- A. Modify Non-encrypted registry settings. B. Modify encrypted registry settings. C. Multi-instance settings. X. Done Select menu option: Chapter 3. Configuring the Active Directory adapter for IBM Tivoli Identity Manager 21

2. See the following procedures on modifying registry settings. Note: There are no encrypted registry settings for this adapter. Modifying non-encrypted registry settings In order to modify the non-encrypted registry settings, complete the following steps: 1. At the Agent Registry Menu, type A. The Non-encrypted Registry Settings Menu is displayed. Agent Registry Items ----------------------------------- 01. CreateUNCHomeDirectories FALSE 02. DeleteUNCHomeDirectories FALSE 03. ENROLE_VERSION 4.0 04. ForceRASServerLookup FALSE 05. ForceTerminalServerLookup FALSE 06. IsRUSRunning TRUE 07. ManageHomeDirectories FALSE 08. ReconHomeDirSecurity FALSE 09. UnlockOnPasswordReset FALSE ----------------------------------- Page 1 of 2 A. Add new attribute B. Modify attribute value C. Remove attribute D. Next Page X. Done Select menu option:d Agent Registry Items ------------------------------------ 10. WtsDisableSearch TRUE 11. WtsEnabled FALSE ------------------------------------- Page 2 of 2 A. Add new attribute B. Modify attribute value C. Remove attribute D. Prev Page X. Done Select menu option: 2. Type the letter of the menu option for the action that you want to perform on an attribute. Table 8. Attribute configuration option descriptions Option Configuration task A Add new attribute B Modify attribute value C Remove attribute 3. Type the registry item name, and press Enter. See Table 9 on page 23 for a description of each registry key. 4. If you selected option A or B, type the registry item value and press Enter. 22 IBM Tivoli Identity Manager: Active Directory Adapter Installation and Configuration Guide

The non-encrypted registry settings menu reappears and displays your new setting(s). Table 9 describes the registry keys and their available settings: Table 9. Registry key descriptions Key Description CreateUNCHomeDirectories If set to TRUE, this key enables creation of the UNC home directory. DeleteUNCHomeDirectories If set to TRUE, this key enables deletion of the UNC home directory on delete. ForceRASServerLookup If set to TRUE, the RASServer will always be found from the Domain information. When set to FALSE, one of these conditions exist: v If the target server is specified in the base point, the target server is used as the RAS server. v If the target server is not specified in the base point, the RAS server is found from the domain information. ForceTerminalServerLookup If set to TRUE, the terminal server will always be found from the domain information. When set to FALSE, one of these conditions exist: v If the target server is specified in the base point, the target server is used as the terminal server. v If the target server is not specified in the base point, the terminal server is found from the domain information. IsRUSRunning If set to FALSE, the msexchuseraccountcontrol and showinaddressbook enhancement attributes will be considered during account management. If set to TRUE, the enhancement attributes are not considered. The default value is TRUE. For more information on the Recipient Update Service (RUS) and how the adapter behaves when the IsRUSRunning attribute and RUS are set to TRUE or FALSE, see Table 10 on page 24. ManageHomeDirectories If set to TRUE, the adapter will perform Add and Delete operations for actual directories. If set to FALSE, the adapter will just update the Home directory information in the Active Directory. Chapter 3. Configuring the Active Directory adapter for IBM Tivoli Identity Manager 23

Table 9. Registry key descriptions (continued) Key Description ReconHomeDirSecurity If set to TRUE, the adapter brings the Home Security information (NTFS security, share name, and share security) during a reconciliation. UnlockOnPasswordReset If set to TRUE, the adapter will activate the user on a password change request. WtsDisableSearch This key takes effect only if WtsEnabled is set to TRUE. If set to FALSE, this key enables a reconciliation of the WTS attributes. If set to TRUE, the reconciliation is faster. WtsEnabled If set to TRUE, this key enables processing of Windows Terminal Server (WTS) attributes. The following tasks are performed when the RUS is turned on: v When an Exchange user ID is created, the entry is first created in the Active Directory. Initially, the user is inactive. The RUS will active the user ID, by setting the msexchuseraccountcontrol enhancement attribute to 0. v When a user, group or object is added to or modified in the Active Directory, the RUS will determine which of the available address lists it belongs to. The service will then add the updated address list to the showinaddressbook enhancement attribute for the user, group, or object. The Active Directory Adapter will consider the msexchuseraccountcontrol and showinaddressbook enhancement attributes and perform the above tasks when RUS is turned off and the IsRUSRunning attribute is set to FALSE. When you install the Active Directory Adapter, the default value of the IsRUSRunning flag is TRUE. Table 10 lists the adapter s behavior, depending on the value of the IsRUSRunning attribute and the status of the RUS: Table 10. Expected adapter behavior IsRUSRunning flag RUS running on the resource Behavior of the adapter TRUE TRUE The adapter will not manage the enhancement attributes. TRUE FALSE The adapter will create an entry in the log file and will not manage the enhancement attributes. FALSE TRUE The adapter will create an entry in the log file and will not manage the enhancement attributes. FALSE FALSE The adapter will manage the enhancement attributes. 24 IBM Tivoli Identity Manager: Active Directory Adapter Installation and Configuration Guide

Changing advanced settings You can change the Active Directory Adapter thread count settings for the following types of requests: v System Login Add v System Login Change v System Login Delete v Reconciliation These settings determine the maximum number of requests that the Active Directory Adapter processes concurrently. In order to change these settings, complete the following steps: 1. At the Main Menu prompt, type G. The Advanced Settings Menu is displayed. The following example shows the default thread count settings. ADAgent 4.6 Advanced Settings Menu ------------------------------------------- A. Single Thread Agent (current:true) B. ADD max. thread count. (current:3) C. MODIFY max. thread count. (current:3) D. DELETE max. thread count. (current:3) E. SEARCH max. thread count. (current:3) F. Allow User EXEC procedures (current:false) G. Archive Request Packets (current:false) H. UTF8 Conversion support (current:true) I. Pass search filter to agent (current:false) J. Thread Priority Level (1-10) (current:4) X. Done Select menu option: 2. Type the letter of the menu option that you want to change. For a description of each option, see Table 11. Table 11. Options for the advanced settings menu Option Description A Forces the adapter to allow only one request at a time. The default value is TRUE. B Controls how many simultaneous ADD requests can run at one time. The default value is 3. C Controls how many simultaneous MODIFY requests can run at one time. The default value is 3. D Controls how many simultaneous DELETE requests can run at one time. The default value is 3. E Controls how many simultaneous SEARCH requests can run at one time. The default value is 3. F Determines whether the adapter allows pre- and post-exec functions. Enabling this option is a potential security risk. The default value is FALSE. G This option is no longer supported. H This option is no longer supported. Chapter 3. Configuring the Active Directory adapter for IBM Tivoli Identity Manager 25

Table 11. Options for the advanced settings menu (continued) Option Description I Currently, this adapter does not support processing filters directly. This option must always be FALSE. J Sets the thread priority level for the adapter. The default value is 4. 3. Change the value, and press Enter. The Advanced Settings Menu is displayed with your new settings. Viewing statistics In order to view an event log for the Active Directory Adapter, complete the following steps: 1. At the Main Menu prompt, type H. The activity history for the adapter is displayed. ADAgent 4.6 Agent Request Statistics -------------------------------------------------------------------- Date Add Mod Del Ssp Res Rec ----------------------------------------------------------------- 11/15/02 000001 000000 000000 000000 000000 000001 ----------------------------------------------------------------- X. Done Changing code page settings 2. Type X to return to the Main Configuration Menu. In order to list the supported code page information for the Active Directory Adapter, the adapter must be running. Run the following command to view the code page information: agentcfg -agent [adapter_name] -codepages In order to change the code page settings for the Active Directory Adapter, complete the following steps: 1. At the Main Menu prompt, type I. The Code Page Support Menu for the adapter is displayed. ADAgent 4.6 Codepage Support Menu ------------------------------------------- * Configured codepage: US-ASCII ------------------------------------------- * ******************************************* * Restart Agent After Configuring Codepages ******************************************* A. Codepage Configure. X. Done Select menu option: 26 IBM Tivoli Identity Manager: Active Directory Adapter Installation and Configuration Guide

2. Type A to configure a code page. Note: The ADAgent code page uses unicode, therefore this option is not applicable. 3. Type X to return to the Main Configuration Menu. Accessing help and additional options In order to access the agentcfg help menu and use the help arguments, complete the following steps: 1. At the Main Menu prompt, type X. The command prompt is displayed, and you are in the \bin directory. 2. Type agentcfg -help at the prompt to view the help menu. The following list of possible commands is displayed: -version ; Show version -hostname < value> ; Target nodename to connect to (Default:Local host IP address) -findall ; Find all agents on target node -list ; List available agents on target node -agent <value> ; Name of agent -tail ; Display agent s activity log -schema ; Display agent s attribute schema -portnumber <value>; Specified agent s TCP/IP port number -netsearch <value> ; Lookup agents hosted on specified subnet -confidencetest ; Confidence test -setup ; Confidence test setup -help ; Display this help screen Table 12 describes each argument. Table 12. Arguments and descriptions for the agentcfg help menu Argument Description -version Use this argument to display the version of the agentcfg tool. -hostname <value> Use the -hostname argument with any of the following arguments to specify a different host: v v v v -findall -list -tail -agent Enter a host name or IP address as the value. -findall Use this argument to search and display all port addresses between 44970 and 44994 and their assigned adapter names. This option will timeout on unused port numbers, so it might take several minutes to complete. Add the -hostname argument to search a remote host. -list Use this argument to display the adapters that are installed on the local host of the Active Directory Adapter. By default, the first time you install an adapter, it is either assigned to port address 44970 or to the next available port number. All subsequently installed adapters are then assigned to the next available port address. Once an unused port is found, the listing stops. Use the -hostname argument to search a remote host. Chapter 3. Configuring the Active Directory adapter for IBM Tivoli Identity Manager 27

Table 12. Arguments and descriptions for the agentcfg help menu (continued) -agent <value> Use this argument to specify the adapter that you want to configure. Enter an adapter name as the value. Use this argument with the -hostname argument to modify the configuration setting from a remote host. You can also use this argument with the -tail argument. -tail Use this argument with the -agent argument to display the activity log for an adapter. Add the -hostname argument to display the log file for an adapter on a different host. -schema This option is no longer supported. -portnumber <value> Use this argument with the -agent argument to specify the port number that is used for connections for the agentcfg tool. -netsearch <value> Use this argument with the -findall argument to display all active adapters on the system. You must specify a subnet address as the value. -confidencetest Use this argument to run a test to add, modify, search, and delete a request to the adapter. The confidence test allows you to test the connection between the adapter and the Active Directory Server. This allows you to verify that the adapter can connect to Active Directory Server without the Tivoli Identity Manager Server. -setup Use this argument, along with the confidence argument, to configure the confidence test. -help Use this argument to display the Help information for the agentcfg command. 3. Type agentcfg and one or more of the supported arguments at the prompt. You must type agentcfg before every argument to run the adapter configuration tool. Type agentcfg -list to list all of the adapters on the local host IP address. Note that the port address for the Tivoli Identity Manager Server is 44970. The output is similar to the following output: Agent(s) installed on node 127.0.0.1 ----------------------- ADAgent (44970) Type agentcfg -agent ADAgent to display the Main Menu of the agentcfg tool, which is used to view or modify the Active Directory Adapter parameters. Type agentcfg -list -hostname 192.9.200.7 to list the adapters on a host whose IP address is 192.9.200.7. The output is similar to the following output: Agent(s) installed on node 192.9.200.7 ------------------ ADAgent (44970) Type agentcfg -agent ADAgent -hostname 192.9.200.7 to display the Main Menu of the agentcfg tool for a host whose IP address is 192.9.200.7. Use the menu options to view or modify the Active Directory Adapter parameters. 28 IBM Tivoli Identity Manager: Active Directory Adapter Installation and Configuration Guide

Chapter 4. Configuring SSL authentication for the Active Directory adapter In order to establish a secure connection between a Tivoli Identity Manager adapter and the Tivoli Identity Manager Server, you must configure the adapter and the server to use the Secure Sockets Layer (SSL) authentication with the default communication protocol, DAML. By configuring the adapter for SSL, you ensure that the Tivoli Identity Manager Server verifies the identity of the adapter before a secure connection is established. You can configure SSL authentication for connections that originate from the Tivoli Identity Manager Server or from the adapter. Typically, the Tivoli Identity Manager Server initiates a connection to the adapter in order to set or retrieve the value of a managed attribute on the adapter. However, depending on the security requirements of your environment, you might need to configure SSL authentication for connections that originate from the adapter. For example, if the adapter uses events to notify the Tivoli Identity Manager Server of changes to attributes on the adapter, you can configure SSL authentication for Web connections that originate from the adapter to the Web server used by the Tivoli Identity Manager Server. In a production environment, you need to enable SSL security; however, for testing purposes you might want to disable SSL. If an external application that communicates with the adapter (such as the Tivoli Identity Manager Server) is set to use server authentication, you must enable SSL on the adapter to verify the certificate that the application presents. This chapter presents an overview of SSL authentication, certificates, and how to enable SSL authentication using the CertTool utility. Overview of SSL and digital certificates When you deploy Tivoli Identity Manager in an enterprise network, you must secure communication between the Tivoli Identity Manager Server and the software products and components with which the server communicates. The industry-standard SSL protocol, which uses signed digital certificates from a certificate authority (CA) for authentication, is used to secure communication in a Tivoli Identity Manager deployment. Additionally, SSL provides encryption of the data exchanged between the applications. Encryption makes data transmitted over the network intelligible only to the intended recipient. Signed digital certificates enable two applications connecting in a network to authenticate each other s identity. An application acting as an SSL server presents its credentials in a signed digital certificate to verify to an SSL client that it is the entity it claims to be. An application acting as an SSL server can also be configured to require the application acting as an SSL client to present its credentials in a certificate, thereby completing a two-way exchange of certificates. Signed certificates are issued by a third-party certificate authority for a fee. Some utilities, such as those provided by OpenSSL, can also issue signed certificates. A certificate-authority certificate (CA certificate) must be installed to verify the origin of a signed digital certificate. When an application receives another application s signed certificate, it uses a CA certificate to verify the originator of Copyright IBM Corp. 2003, 2005 29

the certificate. A certificate authority can be well-known and widely used by other organizations, or it can be local to a specific region or company. Many applications, such as Web browsers, are configured with the CA certificates of well known certificate authorities to eliminate or reduce the task of distributing CA certificates throughout the security zones in a network. Private keys, public keys, and digital certificates Keys, digital certificates, and trusted certificate authorities are used to establish and verify the identities of applications. SSL uses public key encryption technology for authentication. In public key encryption, a public key and a private key are generated for an application. Data encrypted with the public key can only be decrypted using the corresponding private key. Similarly, the data encrypted with the private key can only be decrypted using the corresponding public key. The private key is password-protected in a key database file so that only the owner can access the private key to decrypt messages that are encrypted using the corresponding public key. A signed digital certificate is an industry-standard method of verifying the authenticity of an entity, such as a server, client, or application. In order to ensure maximum security, a certificate is issued by a third-party certificate authority. A certificate contains the following information to verify the identity of an entity: Organizational information Public This section of the certificate contains information that uniquely identifies the owner of the certificate, such as organizational name and address. You supply this information when you generate a certificate using a certificate management utility. key The receiver of the certificate uses the public key to decipher encrypted text sent by the certificate owner to verify its identity. A public key has a corresponding private key that encrypts the text. Certificate authority s distinguished name The issuer of the certificate identifies itself with this information. Digital Self-signed signature The issuer of the certificate signs it with a digital signature to verify its authenticity. This signature is compared to the signature on the corresponding CA certificate to verify that the certificate originated from a trusted certificate authority. Web browsers, servers, and other SSL-enabled applications generally accept as genuine any digital certificate that is signed by a trusted certificate authority and is otherwise valid. For example, a digital certificate can be invalidated because it has expired or the CA certificate used to verify it has expired, or because the distinguished name in the digital certificate of the server does not match the distinguished name specified by the client. certificates You can use self-signed certificates to test an SSL configuration before you create and install a signed certificate issued by a certificate authority. A self-signed certificate contains a public key, information about the owner of the certificate, and the owner s signature. It has an associated private key, but it does not verify the origin of the certificate through a third-party certificate authority. Once you 30 IBM Tivoli Identity Manager: Active Directory Adapter Installation and Configuration Guide

generate a self-signed certificate on an SSL server application, you must extract it and add it to the certificate registry of the SSL client application. This procedure is the equivalent of installing a CA certificate that corresponds to a server certificate. However, you do not include the private key in the file when you extract a self-signed certificate to use as the equivalent of a CA certificate. Use a key management utility to generate a self-signed certificate and a private key, to extract a self-signed certificate, and to add a self-signed certificate. Where and how you choose to use self-signed certificates depends on your security requirements. In order to achieve the highest level of authentication between critical software components, do not use self-signed certificates, or use them selectively. For example, you can choose to authenticate applications that protect server data with signed digital certificates, and use self-signed certificates to authenticate Web browsers or Tivoli Identity Manager adapters. If you are using self-signed certificates, in the following procedures you can substitute a self-signed certificate for a certificate and CA certificate pair. Certificate and key formats Certificates and keys are stored in files with the following formats:.pem format A privacy-enhanced mail (.pem ) format file begins and ends with the following lines:.arm.der -----BEGIN CERTIFICATE----- -----END CERTIFICATE----- The use of SSL authentication A.pem file format supports multiple digital certificates, including a certificate chain. If your organization uses certificate chaining, use this format to create CA certificates. format An.arm file contains a base-64 encoded ASCII representation of a certificate, including its public key, but not its private key. An.arm file format is generated and used by the IBM Key Management utility. format A.der file contains binary data. A.der file can only be used for a single certificate, unlike a.pem file, which can contain multiple certificates..pfx format (PKCS12) A PKCS12 file is a portable file that contains a certificate and a corresponding private key. This format is useful for converting from one type of SSL implementation to a different implementation. For example, you can create and export a PKCS12 file using the IBM Key Management utility, then import the file to another machine using the CertTool utility. When you start the adapter, the available connection protocols are loaded. The DAML protocol is the only available protocol that supports the use of SSL authentication. You can specify to use the DAML SSL implementation. The DAML SSL implementation uses a certificate registry to store private keys and certificates. The location of the certificate registry is managed internally by the Chapter 4. Configuring SSL authentication for the Active Directory adapter 31

CertTool key and certificate management tool; therefore, you do not specify the location of the registry when you perform certificate management tasks. For more information on the DAML protocol, see Changing protocol configuration settings on page 10. Configuring certificates for SSL authentication Use the following procedures to configure the adapter for one-way or two-way SSL authentication using signed certificates. In order to perform these procedures, use the CertTool utility. Configuring certificates for one-way SSL authentication In this scenario, the Tivoli Identity Manager Server and the Tivoli Identity Manager adapter are set to use SSL. Client authentication is not set on either application. The Tivoli Identity Manager Server operates as the SSL client and initiates the connection. The adapter operates as the SSL server and responds by sending its signed certificate to the Tivoli Identity Manager Server. The Tivoli Identity Manager Server uses the CA certificate that is installed to validate the certificate sent by the adapter. In Figure 2, Application A operates as the Tivoli Identity Manager Server, and Application B operates as the Tivoli Identity Manager adapter. Tivoli Identity Manager Server (SSL client) 1 Hello Tivoli Identity Manager adapter (SSL server) C Keystore CA Certificate A Verify Send Certificate B Certificate A Figure 2. One-way SSL authentication (server authentication) In order to configure one-way SSL, perform the following tasks for each application: 1. On the adapter, complete these steps: a. Start the CertTool utility. b. In order to configure the SSL-server application with a signed certificate issued by a certificate authority: 1) Create a certificate signing request (CSR) and private key. This step creates the certificate with an embedded public key and a separate private key and places the private key in the PENDING_KEY registry value. 2) Submit the CSR to the certificate authority using the instructions supplied by the CA. When you submit the CSR, specify that you want the root CA certificate returned with the server certificate. 2. On the Tivoli Identity Manager Server, complete one of these steps: 32 IBM Tivoli Identity Manager: Active Directory Adapter Installation and Configuration Guide

v If you are configuring the use of a signed certificate issued by a well-known CA, ensure that the Tivoli Identity Manager Server has stored the root certificate of the CA (CA certificate) in its keystore. If the keystore does not contain the CA certificate, extract the CA certificate from the adapter and add it to the keystore of the server. v If you are configuring the use of self-signed certificates: If you generated the self-signed certificate on the Tivoli Identity Manager Server, the certificate is already installed in its keystore. If you generated the self-signed certificate using the key management utility of another application, extract the certificate from that application s keystore and add it to the keystore of the Tivoli Identity Manager Server. Configuring certificates for two-way SSL authentication In this scenario, the Tivoli Identity Manager Server and the Tivoli Identity Manager adapter are set to use SSL and the adapter is set to use client authentication. Once sending its certificate to the Tivoli Identity Manager Server, the adapter requests identity verification from the server, which sends its signed certificate to the adapter. Both applications are configured with signed certificates and corresponding CA certificates. In Figure 3, the Tivoli Identity Manager Server operates as Application A, and the Tivoli Identity Manager adapter operates as Application B. Tivoli Identity Manager Server (SSL client) Keystore CA Certificate A Verify Hello Send Certificate A Tivoli Identity Manager adapter (SSL Cserver) Certificate A C Send Certificate A Certificate B Verify CA Certificate B Send Certificate B Figure 3. Two-way SSL authentication (client authentication) The following procedure assumes that you have already configured the adapter and Tivoli Identity Manager Server for one-way SSL authentication using the procedure described in Configuring certificates for one-way SSL authentication on page 32. Therefore, if you are using signed certificates from a CA: v The adapter is configured with a private key and a signed certificate that was issued by a CA. v The Tivoli Identity Manager Server is configured with the CA certificate of the CA that issued the signed certificate of the adapter. In order to complete the certificate configuration for two-way SSL, perform the following tasks: Chapter 4. Configuring SSL authentication for the Active Directory adapter 33

1. On the Tivoli Identity Manager Server, create a CSR and private key, obtain a certificate from a CA, install the CA certificate, install the newly signed certificate, and extract the CA certificate to a temporary file. 2. On the adapter, add the CA certificate that was extracted from the keystore of the Tivoli Identity Manager Server to the adapter. When you have finished the two-way certificate configuration, each application has its own certificate and private key and the CA certificate of the CA that issued the certificates for each application. Configuring certificates when the adapter operates as an SSL client In this scenario, the adapter operates as an SSL client in addition to operating as an SSL server. This scenario applies if the adapter initiates a connection to the Web server (used by the Tivoli Identity Manager Server) to send an event notification. For example, the adapter initiates the connection and the Web server responds by presenting its certificate to the adapter. Figure 4 illustrates how a Tivoli Identity Manager adapter operates as an SSL sever and an SSL client. When communicating with the Tivoli Identity Manager Server, the adapter sends its certificate for authentication. When communicating with the Web server, the adapter receives the certificate of the Web server. Certificate A CA Certificate C CA Certificate A Tivoli Identity Manager Adapter A Hello Certificate A Tivoli Identity Manager Server B Certificate C Hello Web server Certificate C C Figure 4. Tivoli Identity Manager adapter operating as an SSL server and an SSL client If the Web Server is configured for two-way SSL authentication, it verifies the identity of the adapter, which sends its signed certificate to the Web server (not shown in the illustration). In order to enable two-way SSL authentication between the adapter and Web server, use the following procedure: 1. Configure the Web server to use client authentication. 2. Follow the procedure for creating and installing a signed certificate on the Web server. 3. Install the CA certificate on the adapter using the CertTool utility. 4. Add the CA certificate corresponding to the signed certificate of the adapter to the Web server. 34 IBM Tivoli Identity Manager: Active Directory Adapter Installation and Configuration Guide

For more information on configuring certificates when the adapter initiates a connection to the Web server (used by the Tivoli Identity Manager Server) to send an event notification, see the Tivoli Identity Manager Information Center. Managing SSL certificates using CertTool Starting The procedures in this section describe how to use the CertTool utility to manage private keys and certificates. This section includes instructions for performing the following tasks: v Starting CertTool. v Generating a private key and certificate request on page 37. v Installing the certificate on page 38. v Installing the certificate and key from a PKCS12 file on page 38. v Viewing the installed certificate on page 39. v Viewing CA certificates on page 39. v Installing a CA certificate on page 39. v Deleting a CA certificate on page 39. v Viewing registered certificates on page 40. v Registering a certificate on page 40. v Unregistering a certificate on page 40. CertTool In order to start the certificate configuration tool, CertTool, for the Active Directory Adapter, complete these steps: 1. Select Programs from the Start menu, select Accessories, and then select Command Prompt. 2. In the Microsoft Windows DOS Command Prompt window, change to the bin directory for the adapter. For example, if the Active Directory Adapter directory is in the default location, type the following command: cd C:\Tivoli\Agents\ADAgent\bin 3. Type CertTool -agent ADAgent at the prompt. The Main Menu is displayed: Main menu - Configuring agent: ADAgent ------------------------------ A. Generate private key and certificate request B. Install certificate from file C. Install certificate and key from PKCS12 file D. View current installed certificate E. List CA certificates F. Install a CA certificate G. Delete a CA certificate H. List registered certificates I. Register certificate J. Unregister a certificate K. Export certificate and key to PKCS12 file X. Quit Choice: Chapter 4. Configuring SSL authentication for the Active Directory adapter 35

From the Main Menu, you can generate a private key and certificate request, install and delete certificates, register and unregister certificates, and list certificates. The following sections summarize the purpose of each group of options. The first set of options (A through D) allows you to generate a CSR and install the returned signed certificate on the adapter. A. Generate private key and certificate request Generate a CSR and the associated private key that is sent to the certificate authority. For more information on option A, see Generating a private key and certificate request on page 37. B. Install certificate from file Install a certificate from a file. This file must be the signed certificate returned by the CA in response to the CSR that is generated by option A. For more information on option B, see Installing the certificate on page 38. C. Install certificate and key from a PKCS12 file Install a certificate from a PKCS12 format file that includes both the public certificate and a private key. If options A and B are not used to obtain a certificate, the certificate that you use must be in PKCS12 format. For more information on option C, see Installing the certificate and key from a PKCS12 file on page 38. D. View current installed certificate View the certificate that is installed on the system. For more information on option D, see Viewing the installed certificate on page 39. The second set of options enable you to install root CA certificates on the adapter. A CA certificate is used by the Tivoli Identity Manager adapter to validate the corresponding certificate presented by a client, such as the Tivoli Identity Manager Server. E. List CA certificates Show the installed CA certificates. The adapter only communicates with Tivoli Identity Manager Servers whose certificates are validated by one of the installed CA certificates. F. Install a CA certificate Install a new CA certificate so that certificates generated by this CA can be validated. The CA certificate file can either be in X.509 or PEM encoded formats. For more information on how to install a CA certificate, see Installing a CA certificate on page 39. G. Delete a CA certificate Remove one of the installed CA certificates. For more information on how to delete a CA certificate, see Deleting a CA certificate on page 39. The remaining options (H through K) apply to adapters that must authenticate the application (for example, the Tivoli Identity Manager Server or the Web server) to which the adapter is sending information. These options enable you to register certificates on the adapter. For Tivoli Identity Manager Version 4.5 or earlier, the signed certificate of the Tivoli Identity Manager Server must be registered with an adapter to enable client authentication on the adapter. If you do not intend to upgrade an existing adapter to use CA certificates for client authentication, the signed certificate presented by the Tivoli Identity Manager Server must be registered with the adapter. 36 IBM Tivoli Identity Manager: Active Directory Adapter Installation and Configuration Guide

If you configure the adapter to use event notification, or client authentication is enabled in DAML, then you must install the CA certificate corresponding to the signed certificate of the Tivoli Identity Manager Server using the Install a CA certificate option, option F. H. List registered certificates List all registered certificates that will be accepted for communications. For more information on listing registered certificates, see Viewing registered certificates on page 40. I. Register a certificate Register a new certificate. The certificate to be registered be in Base 64 encoded X.509 format or PEM. For more information on registering certificates, see Registering a certificate on page 40. J. Unregister a certificate Unregister (remove) a certificate from the registered list. For more information on unregistering certificates, see Unregistering a certificate on page 40. K. Export certificate and key to PKCS12 file Export a previously installed certificate and private key. You will be prompted for the filename and a password for encryption. For more information on exporting a certificate and key to a PKCS12 file, see Exporting a certificate and key to PKCS12 file on page 41. Generating a private key and certificate request A certificate signing request is an unsigned certificate that is a text file. When you submit an unsigned certificate to a certificate authority, the CA signs the certificate with the private digital signature that is included in their corresponding CA certificate. When the CSR is signed, it becomes a valid certificate. A CSR contains information about your organization, such as the organization name, country, and the public key for your Web server. In order to generate a CSR file, complete these steps: 1. At the Main Menu of the CertTool, type A. The following message and prompt are displayed: Enter values for certificate request (press enter to skip value) ------------------------------------------------------------------------- 2. At the Organization prompt, type your organization name, and press Enter. 3. At the Organizational Unit prompt, type the organizational unit, and press Enter. 4. At the Agent Name prompt, type the name of the adapter you are requesting a certificate for, and press Enter. 5. At the Email prompt, type the e-mail address for the contact person for this request, and press Enter. 6. At the State prompt, type the state in which the adapter resides (if the adapter is in the United States), and press Enter. Some certificate authorities do not accept two letter abbreviations for states, so you must type the full name of the state. 7. At the Country prompt, type the country in which the adapter resides, and press Enter. 8. At the Locality prompt, type the name of the city in which the adapter resides, and press Enter. Chapter 4. Configuring SSL authentication for the Active Directory adapter 37

9. At the Accept these values prompt, type Y to accept the values displayed, or type N to re-enter the values, and press Enter. The private key and certificate request are generated once the values are accepted. 10. At the Enter name of file to store PEM cert request prompt, type the name of the file that you want to use to store the values you specified during the previous steps, and press Enter. 11. Press Enter to continue. The certificate request and input values are written to the file you specified, and the Main Menu is displayed again. You can now request a certificate from a trusted CA by sending the.pem file that you just generated to a certificate authority vendor. Example of certificate signing request Your CSR file will look similar to the following example: -----BEGIN CERTIFICATE REQUEST----- MIIB1jCCAT8CAQAwgZUxEjAQBgNVBAoTCWFjY2VzczM2MDEUMBIGA1UECxMLZW5n aw5lzxjpbmcxedaobgnvbamtb250ywdlbnqxjdaibgkqhkig9w0bcqewfw50ywdl bnraywnjzxnzmzywlmnvbtelmakga1uebhmcvvmxezarbgnvbagtcknhbglmb3ju awexdzanbgnvbactbklydmluztcbnzanbgkqhkig9w0baqefaaobjqawgykcgyea mr6acpnwf6hllc72bmukawaxcebtxcocnnth9uc8vumhpbimagjuc4s91hprilg7 UtlbOfy6X3R3kbeR8apRR9uLYrPIvQ1b4NK0whsytij6syCySaFQIB6V7RPBatFr 6XQ9hpsARdkGytZmGTgGTJ1hSS/jA6mbxpgmttz9HPECAwEAAaAAMA0GCSqGSIb3 DQEBAgUAA4GBADxA1cDkvXhgZntHkwT9tCTqUNV9sim8N/U15HgMRh177jVaHJqb N1Er46vQSsOOOk4z2i/XwOmFkNNTXRVl9TLZZ/D+9mGZcDobcO+lbAKlePwyufxK Xqdpu3d433H7xfJJSNYLYBFkrQJesITqKft0Q45gIjywIrbctVUCepL2 -----END CERTIFICATE REQUEST----- Installing the certificate Once you receive your certificate from your trusted CA, you install it in the registry of the adapter. In order to install the certificate, complete these steps: 1. If you received the certificate as part of an e-mail message, copy the text of the certificate to a text file, and copy that file to the bin directory for the adapter. For example, C:\Tivoli\Agents\ADAgent\bin 2. At the Main Menu of the CertTool, type B. The following prompt is displayed: Enter name of certificate file: ------------------------------------------------------------------------- 3. At the Enter name of certificate file prompt, type the full path to the certificate file, and press Enter. The certificate is installed in the registry for the adapter, and the Main Menu is displayed again. Installing the certificate and key from a PKCS12 file If you do not use the CertTool utility to generate a CSR to obtain a certificate, you must install both the certificate and private key, which must be stored in a PKCS12 file. The CA might send a password protected file, or PKCS12 file (a file with the.pfx extension), which includes both the certificate and private key. In order to install the certificate from this PKCS12 file, complete these steps: 1. Copy the PKCS12 file to the bin directory for the adapter. For example, C:\Tivoli\Agents\ADAgent\bin 2. At the Main Menu for the CertTool, type C. The following prompt is displayed: Enter name of PKCS12 file: ------------------------------------------------------------------------- 38 IBM Tivoli Identity Manager: Active Directory Adapter Installation and Configuration Guide

3. At the Enter name of PKCS12 file prompt, type the name of the PKCS12 file that has the certificate and private key information, and press Enter. For example, DamlSrvr.pfx. 4. At the Enter password prompt, type the password to access the file, and press Enter. The certificate and private key are installed in the adapter registry, and the Main Menu is displayed. Viewing the installed certificate In order to list the certificate that is installed on your system, at the Main Menu of CertTool, type D. The installed certificate is listed, and the Main Menu is displayed. The following example lists an installed certificate: The following certificate is currently installed. Subject: c=us,st=california,l=irvine,o=daml,cn=daml Server Installing a CA certificate If you are using client authentication, you need to install a CA certificate. The CA certificate you install is issued by a certificate authority vendor. In order to install a CA certificate that was extracted into a temporary file, complete the following steps: 1. At the Main Menu prompt, type F (Install a CA certificate). The following prompt is displayed: Enter name of certificate file: 2. At the Enter name of certificate file prompt, type the name of the certificate file, such as DamlCACerts.pem, and press Enter. The certificate file is opened, and the following prompt is displayed: e=admin@ibm.com,c=us,st=california,l=irvine,o=ibm,ou=engineering,cn=eng Install the CA? (Y/N) 3. At the Install the CA prompt, type Y to install the certificate, and press Enter. The certificate file is installed in the CACerts.pem file. Viewing CA certificates CertTool only installs one certificate and one private key. In order to list the CA certificate that is installed on the adapter, type E at the Main Menu prompt. The installed CA certificates are displayed and the Main Menu is displayed. The following example lists an installed CA certificate: Subject: o=ibm,ou=samplecacert,cn=testca Valid To: Wed Jul 26 23:59:59 2006 Deleting a CA certificate In order to delete a CA certificate from the adapter directories, complete the following steps: 1. At the Main Menu prompt, type G. A list of all CA certificates installed on the adapter is displayed. 0 - e=admin@ibm.com,c=us,st=california,l=irvine,o=ibm,ou=engineering,cn=eng 1 - e=support@ibm.com,c=us,st=california,l=irvine,o=ibm,ou=support,cn=support Enter number of CA certificate to remove: Chapter 4. Configuring SSL authentication for the Active Directory adapter 39

2. At the Enter number of CA certificate to remove prompt, type the number of the CA certificate that you want to remove, and press Enter. The CA certificate is deleted from the CACerts.pem file, and the Main Menu is displayed. Viewing registered certificates Only requests that present a registered certificate will be accepted by the adapter when client validation is enabled. In order to view a list of all registered certificates available to the adapter, at the Main Menu prompt, type H. The registered certificates are displayed and the Main Menu is displayed. The following example lists registered certificates: 0 - e=admin@ibm.com,c=us,st=california,l=irvine,o=ibm,ou=engineering,cn=eng 1 - e=support@ibm.com,c=us,st=california,l=irvine,o=ibm,ou=support,cn=support Registering a certificate In order to register a certificate for the adapter, complete the following steps: 1. At the Main Menu prompt, type I. The following prompt is displayed: Enter name of certificate file: 2. At the Enter name of certificate file prompt, type the name of the certificate file that you want to register, and press Enter. The subject of the certificate is displayed, and a prompt is displayed, for example: e=admin@ibm.com,c=us,st=california,l=irvine,o=ibm,ou=engineering,cn=eng Register this CA? (Y/N) 3. At the Register this CA prompt, type Y to register the certificate, and press Enter. The certificate is registered to the adapter, and the Main Menu is displayed. Unregistering a certificate In order to unregister a certificate for the adapter, complete the following steps: 1. At the Main Menu prompt, type J. The registered certificates are displayed. The following example lists registered certificates: 0 - e=admin@ibm.com,c=us,st=california,l=irvine,o=ibm,ou=engineering,cn=eng 1 - e=support@ibm.com,c=us,st=california,l=irvine,o=ibm,ou=support,cn=support 2. Type the number of the certificate file that you want to unregister, and press Enter. The subject of the selected certificate is displayed, and a prompt is displayed, for example: e=admin@ibm.com,c=us,st=california,l=irvine,o=ibm,ou=engineering,cn=eng Unregister this CA? (Y/N) 3. At the Unregister this CA prompt, type Y to unregister the certificate, and press Enter. The certificate is removed from the registered certificate list for the adapter, and the Main Menu is displayed. 40 IBM Tivoli Identity Manager: Active Directory Adapter Installation and Configuration Guide

Exporting a certificate and key to PKCS12 file In order to export a certificate and key to a PKCS12 file for the adapter, complete the following steps: 1. At the Main Menu prompt, type K. The following prompt is displayed: Enter name of PKCS12 file: 2. At the Enter name of PKCS12 file prompt, type the name of the PKCS12 file for the installed certificate or private key, and press Enter. 3. At the Enter Password prompt, type the password for the PKCS12 file, and press Enter. 4. At the Confirm Password prompt, type the password again, and press Enter. The certificate or private key is exported to the PKCS12 file, and the Main Menu is displayed. Chapter 4. Configuring SSL authentication for the Active Directory adapter 41

42 IBM Tivoli Identity Manager: Active Directory Adapter Installation and Configuration Guide

Chapter 5. Customizing the Active Directory adapter Active Directory can support custom attributes for the user class. The Active Directory Adapter only supports standard Windows attributes by default. However, you can customize the adapter to support custom (extended) attributes. Complete these steps to customize the Active Directory Adapter to support the extended attributes in the Active Directory: 1. Extend the Active Directory Adapter schema and add the custom attributes to the Active Directory Server. For more information on extending the schema, see Step 1: Extend the schema and add the extended attributes. 2. Copy the JAR file to a temporary directory and extract the files. For more information on extracting the files, see Step 2. Copy the ADProfile.jar file and extract the files on page 44. 3. Add the extended attributes to the exschema.txt file. For more information on extending the attributes, see Step 3. Modify the exschema.txt file on page 44. 4. Update the schema.dsml file on the Tivoli Identity Manager Server. For more information on updating this file, see Step 4: Update the schema.dsml file on page 45. 5. Update the customlabels.properties file on the host machine. For more information on updating this file, see Step 5: Modify the CustomLabels.properties file on page 45. 6. Install the new attributes on the Tivoli Identity Manager Server. For more information on updating this file, see Step 6: Create a new JAR file and install the new attributes on the Tivoli Identity Manager Server on page 46. 7. Modify the form for the account. For more information on updating the form, see Step 7: Optionally modify the adapter form on page 46. For information on the files that you can modify, in order to customize the Active Directory Adapter, see Appendix A, Files, on page 53. Step 1: Extend the schema and add the extended attributes Extend the Windows Active Directory schema and add the custom attributes to the Active Directory Server using the tools provided by Windows. Refer to the Microsoft Windows Server documentation for more information about adding new attributes to the Active Directory. The Active Directory Adapter supports the following types of custom attributes: v v Boolean Integer v Case insensitive string v UTC coded time Consider prefixing the attribute names with erad in order to easily identify the attributes that are used with Tivoli Identity Manager. Note: If IBM Tivoli Directory Server is being used as the directory server application, the name of the attribute must be unique within the first 16 characters. Copyright IBM Corp. 2003, 2005 43

Step 2. Copy the ADProfile.jar file and extract the files The profile JAR file, ADProfile.jar, is included in the Active Directory Adapter compressed file that you downloaded from the IBM Web site. The ADProfile.jar file contains the following files: v v v v v CustomLabels.properties eradaccount.xml eraddamlservice.xml resource.def schema.dsml v xforms.xml You can modify these files to customize your environment. When you finish updating the profile JAR file, install it on the Tivoli Identity Manager Server. For more information on the profile installation, see Importing the adapter profile into the Tivoli Identity Manager Server on page 4. In order to modify the ADProfile.jar file, complete the following steps: 1. Log into the system where the Active Directory Adapter is installed. 2. On the Start menu, click Programs Accessories Command Prompt. 3. Copy the ADProfile.jar file into a temporary directory. 4. Extract the contents of` the ADProfile.jar file into the temporary directory by running the following command: cd c:\temp jar -xvf ADProfile.jar The jar command will create the c:\temp\adprofile directory. 5. Edit the appropriate file by completing the remaining steps below. Step 3. Modify the exschema.txt file The exschema.txt file lists all extended attributes in the Active Directory Server. Modify this file to allow the Active Directory Adapter to recognize an extended attribute in the Windows Active Directory Server. In order to modify the exschema.txt file, complete the following steps: 1. Change to the \data directory for the adapter. 2. Create or open the exschema.txt file in a text editor. 3. Add the extended attributes to the file. List only 1 attribute per line. For example: eradstring1 eradinteger eraddate eradboolean eradmultivaluestring 4. Save the changes, and close the file. 5. Start the adapter again. Start the adapter by using the Windows Services Console. 44 IBM Tivoli Identity Manager: Active Directory Adapter Installation and Configuration Guide

Step 4: Update the schema.dsml file The Active Directory Adapter schema.dsml file identifies all of the standard Windows account attributes. Modify this file to identify the new extended attributes in the Active Directory Server. For more information about the attributes in this file, see schema.dsml file on page 53. In order to update the schema.dsml file, complete the following steps: 1. Change to the \ADProfile directory, where the schema.dsml file has been created. 2. Edit the schema.dsml file to add an attribute definition for each extended attribute. The Object Identifier (OID) be incremented by 1, based on the last entry in the file. For example, if the last attribute in the file uses the OID 1.3.6.1.4.1.6054.3.125.2.67, the first new attribute use the OID 1.3.6.1.4.1.6054.3.125.2.68. Consider starting a new range of numbers for your custom attributes. For example, start custom attributes with OID 1.3.6.1.4.1.6054.3.125.2.100. This prevents duplicate OIDs if the adapter is upgraded to support new attributes that are standard for newer versions of Windows. 3. Add each of the new attributes to the account class. For example, add the following attribute definition under the eradaccount section of the schema.dsml file: <attribute ref="eraddate" required="false"/> Step 5: Modify the CustomLabels.properties file Once you add the extended attributes to the schema.dsml file, the attributes are available for use on the Active Directory Adapter form. The attributes appear in the attribute list by their directory server name. You can modify the attribute names that appear in the attribute list. For more information about the attributes that appear on the adapter form, see CustomLabels.properties file on page 56. In order to add the attribute and its corresponding label to the CustomLabels.properties file, complete the following steps: 1. Change to the ADProfile directory where the CustomLabels.properties file has been created. 2. Edit the CustomLabels.properties file to add the attribute and its corresponding label using the following format: attribute=label Note: The attribute name must be in lower case. For example: # # ADAgent Labels definitions # eradstring1=adstring1 eradinteger=adinteger eraddate=addate eradboolean=adboolean eradmultivaluestring=admultivaluestring Chapter 5. Customizing the Active Directory adapter 45

Step 6: Create a new JAR file and install the new attributes on the Tivoli Identity Manager Server Once you modify the schema.dsml and CustomLabels.properties files, you must import these files, and any other files that were modified for the adapter, into the Tivoli Identity Manager Server for the changes to take effect. In order to install the new attributes, complete the following steps: 1. Create a new JAR file using the files in the \temp directory by running the following commands: cd c:\temp jar -cvf ADProfile.jar ADProfile 2. Import the ADProfile.jar file into the Tivoli Identity Manager Application Server. For more information on importing the file, see Importing the adapter profile on page 5. 3. Stop and start the directory server. 4. Stop and start the Active Directory Adapter service for the changes to take effect. Step 7: Optionally modify the adapter form Once the changes are available in the Tivoli Identity Manager Server, you can modify the Active Directory Adapter forms to use the new extended attributes. The attributes do not need to be added to the Active Directory Adapter form unless you want them to be available. The attributes will be returned during reconciliations unless you explicitly exclude them. For more information on how to modify the adapter form, see the Tivoli Identity Manager Information Center. Managing passwords when restoring accounts When a person s accounts are restored from being previously suspended, you are prompted to supply a new password for the reinstated accounts. However, there are circumstances when you might want to circumvent this behavior. The password requirement to restore an account on Active Directory Server falls into two categories: allowed and required. How each restore action interacts with its corresponding managed resource depends on either the managed resource, or the business processes that you implement. Certain resources will reject a password when a request is made to restore an account. In this case, you can configure Tivoli Identity Manager to forego the new password requirement. You can set the Active Directory Adapter to require a new password when the account is restored, if your company has a business process in place that dictates that the account restoration process must be accompanied by resetting the password. In the resource.def file, you can define whether or not a password is required as a new protocol option. When you import the adapter profile, if an option is not specified, the adapter profile importer determines the correct restoration password behavior from the schema.dsml and xforms.xml files. Adapter profile components also enable remote services to find out if you discard a password that is entered by the user in a situation where multiple accounts on disparate resources are being restored. In this scenario, only some of the accounts being restored might require a 46 IBM Tivoli Identity Manager: Active Directory Adapter Installation and Configuration Guide

password. Remote services will discard the password from the restore action for those managed resources that do not require them. In order to configure the Active Directory Adapter to not prompt for a new password when restoring accounts: 1. Stop the Tivoli Identity Manager Server. 2. Extract the files from the ADProfile.jar file. For more information on customizing the adapter profile file, see Step 2. Copy the ADProfile.jar file and extract the files on page 44. 3. Change to the \ADProfile directory, where the resource.def file has been created. 4. Edit the resource.def file to add the new protocol options, for example: <Property Name = "com.ibm.itim.remoteservices.resourceproperties. PASSWORD_NOT_REQUIRED_ON_RESTORE" Value = "TRUE"/> <Property Name = "com.ibm.itim.remoteservices.resourceproperties. PASSWORD_NOT_ALLOWED_ON_RESTORE" Value = "FALSE"/> By adding the two options in the example above, you are ensuring that you will not be prompted for a password when an account is restored. 5. Create a new ADProfile.jar file using the resource.def file and import the adapter profile file into the Tivoli Identity Manager Server. For more information, see Step 6: Create a new JAR file and install the new attributes on the Tivoli Identity Manager Server on page 46. 6. Start the Tivoli Identity Manager Server again. Note: If you are upgrading an existing adapter profile, the new adapter profile schema will not be reflected immediately. You need to stop and start the Tivoli Identity Manager Server in order to refresh the cache and therefore the adapter schema. For more information on upgrading an existing adapter, see Upgrading the Active Directory adapter on page 49. Configuring the base point for the adapter You can configure the Active Directory Adapter to support both sub-domains and multiple domains through the base point feature on the adapter service form. For more information on configuring the service form, see the Tivoli Identity Manager Information Center. The base point for the Active Directory Adapter is the point in the directory server that is used as the root for the adapter. This point can be an OU or DC point. Because the base point is an optional value, if a value is not specified, the adapter uses the default domain of the machine on which it is installed. The following definition is an example of a base point defined from the root of the directory server: dc=irvine,dc=ibm,dc=com The following definition is an example of a base point defined from an organizational unit level: ou=engineering,dc=irvine,dc=ibm,dc=com The syntax of the base point also allows for an optional machine name to prefix the base point DN, for example server1/dc=ibm,dc=com. This causes the adapter Chapter 5. Customizing the Active Directory adapter 47

to bind to a specific server instead of connecting to the first available server when responding to an active directory bind request. Also on the service form are the Admin User Account and Admin User Password values. These optional values are only required if an administrator account is defined for the base point of the adapter, and you want to use this account for logging purposes. If these values are not defined, the adapter will use the account assigned to the adapter service. Note: Do not create services that overlap in scope in the directory tree. This could result in duplicate account creation during reconciliation. 48 IBM Tivoli Identity Manager: Active Directory Adapter Installation and Configuration Guide

Chapter 6. Upgrading the Active Directory adapter or the ADK You can either upgrade the Active Directory Adapter or the Adapter Development Kit (ADK). The ADK is the base component of the adapter. While all adapters have the same ADK, the remaining adapter functionality is specific to the managed resource. You can perform an adapter upgrade to migrate your current adapter installation to a newer version, for example version 4.4 to version 4.6. Upgrading the adapter, as opposed to reinstalling it, will allow you to keep your configuration settings. Additionally, you will not have to uninstall the current adapter and install the newer version. However, if a code fix has been made to the ADK, instead of upgrading the entire adapter, you can upgrade just the ADK to the newer version. Upgrading the Active Directory adapter Upgrading the ADK During an upgrade, in order to maintain all of your current configuration settings, as well as the certificate and private key, do not uninstall the old version of the adapter before installing the new version. During the install, specify the same installation directory where the previous adapter was installed. For more information on how to install the adapter, see Chapter 2, Installing and configuring the Active Directory adapter, on page 3. If you currently have version 4.4 or 4.5 of the Active Directory Adapter installed, and you want version 4.6, an upgrade of the adapter is necessary. Upgrading the adapter involves several steps that you must complete in the appropriate sequence. In order to upgrade an existing adapter, complete the following steps: 1. Stop the Active Directory Adapter service. 2. Install the new version of the adapter. When the upgraded adapter starts for the first time, new log files will be created, replacing the old files. The ADK consists of the runtime library, filtering and event notification functionality, protocol settings, and logging information. The remainder of the adapter is comprised of the Add, Modify, Delete, and Search functions. While all adapters have the same ADK, the remaining functionality is specific to the managed resource. You can use the ADK upgrade program to update the ADK portion of the adapters that are currently installed on a machine. This allows you to install just the ADK, and not the entire adapter. As part of the ADK upgrade, the ADK library and the DAML protocol library are updated. In addition, the agentcfg and CertTool binaries are updated. Copyright IBM Corp. 2003, 2005 49

Prior to upgrading the ADK files, the upgrade program checks the current version of the ADK. If the current level is higher than what you are attempting to install, a warning message is displayed. In order to upgrade the Active Directory Adapter ADK, complete the following steps: 1. Download the ADK upgrade program compressed file from the IBM Web site. 2. Extract the contents of the compressed file into a temporary directory. 3. Stop the Active Directory Adapter service. 4. Start the upgrade program using the adkinst_win32.exe file in the temporary directory. For example, select Run from the Start menu, and type C:\TEMP\adkinst_win32.exe in the Open field. If no adapter is installed, you will receive the following error message, and the program exits: No Agent Installed - Cannot Install ADK. 5. On the Welcome window, click Next. 6. On the Software License Agreement window, review the license agreement and decide if you accept the terms of the license. If you do, click Accept. 7. On the Installation Information window, click Next to begin the installation. 8. On the Install Completed window, click Finish to exit the program. Log files Logging entries are stored in the <ADKVersion>Installer.log and <ADKVersion>Installeropt.log files, where <ADKVersion> is the version of the ADK. For example, ADK46Installer.log and ADK46Installeropt.log. These files are created in the folder where you run the installation program. 50 IBM Tivoli Identity Manager: Active Directory Adapter Installation and Configuration Guide

Chapter 7. Uninstalling the Active Directory adapter Before you remove the adapter, inform your users that the Active Directory Adapter will be unavailable and removed from the system. If the server is taken offline, Active Directory Adapter requests that are not completed will not be recoverable when the server is back online. In order to remove the Active Directory Adapter, complete these steps: 1. Stop the Active Directory Adapter service. 2. Open Windows Explorer and run <adapter_directory>\_uninst\uninstaller.exe, where adapter_directory is the directory where the adapter was installed. 3. In the Welcome window, click Next. 4. In the Active Directory Adapter uninstallation summary window, click Next. 5. Click Finish. Inspect the adapter directory for Active Directory Adapter directories, subdirectories, and files to verify that the uninstallation is complete. The instance of the Active Directory Adapter that was uninstalled should no longer appear in the Services window. Copyright IBM Corp. 2003, 2005 51

52 IBM Tivoli Identity Manager: Active Directory Adapter Installation and Configuration Guide

Appendix A. Files You can configure several adapter-specific files. This appendix includes information about the files that are associated with the Active Directory Adapter: v xforms.xml file v schema.dsml file v CustomLabels.properties file on page 56 xforms.xml file The xforms.xml file identifies the attributes that are required for the service form, for each request from the server. The xforms.xml file is installed on the Tivoli Identity Manager Server as part of the adapter profile installation. Use the xforms.xml file to specify a different name for an attribute on the Tivoli Identity Manager Server from the corresponding attribute on the Active Directory Server. If you want to create an xforms.xml file, you must map all of the names of the existing attributes, as well as any new attributes in the file. The value of existing attributes will not change. schema.dsml file The schema.dsml file contains all of the attributes that are common to all adapters. This common file also contains Tivoli Identity Manager Server attributes that can be used by any adapter. The schema.dsml file defines all of the classes used by the adapter. The classes are used to declare accounts, services, and supporting data. The schema.dsml file defines the attributes and objects that the adapter supports and uses to communicate with the Tivoli Identity Manager Server. All attributes must be unique, therefore they are assigned an OID. The OID is defined using the <object-identifier>...</object-identifier> tags. The schema.dsml file has the following format: SCHEMA.DSML File <?xml version="1.0" encoding="utf-8"?> <!-- edited with XML Spy v3.5 NT (http://www.xmlspy.com) by IBM --> <dsml> <!-- ******************************************************** --> <!-- Schema supported by the Windows adapter. --> <!-- ******************************************************** --> <directory-schema>... <!-- ******************************************************** --> <!-- eraadstring1--> <!-- ******************************************************** --> <attribute-type single-value="true"> <name>eradstring1</name> <description/> <object-identifier>1.3.6.1.4.1.6054.3.125.2.100</object-identifier> <syntax>1.3.6.1.4.1.1466.115.121.1.15</syntax> </attribute-type> <!-- ******************************************************** --> <!-- eradinteger--> <!-- ******************************************************** --> <attribute-type single-value="true"> <name>eradinteger</name> <description/> <object-identifier>1.3.6.1.4.1.6054.3.125.2.101</object-identifier> <syntax>1.3.6.1.4.1.1466.115.121.1.27</syntax> Copyright IBM Corp. 2003, 2005 53

Object </attribute-type> <!-- ******************************************************** --> <!-- eraddate--> <!-- ******************************************************** --> <attribute-type single-value="true"> <name>eraddate</name> <description/> <object-identifier>1.3.6.1.4.1.6054.3.125.2.102</object-identifier> <syntax>1.3.6.1.4.1.1466.115.121.1.24</syntax> </attribute-type> <!-- ******************************************************** --> <!-- eradboolean--> <!-- ******************************************************** --> <attribute-type single-value="true"> <name>eradboolean</name> <description/> <object-identifier>1.3.6.1.4.1.6054.3.125.2.103</object-identifier> <syntax>1.3.6.1.4.1.1466.115.121.1.7</syntax> </attribute-type> <!-- ******************************************************** --> <!-- eradmultivaluestring--> <!-- ******************************************************** --> <attribute-type> <name>eradmultivaluestring</name> <description>list of string values</description> <object-identifier>1.3.6.1.4.1.6054.3.125.2.104</object-identifier> <syntax>1.3.6.1.4.1.1466.115.121.1.15</syntax> </attribute-type>... <!-- ******************************************************** --> <!-- eradaccount Class --> <!-- ******************************************************** --> <class superior="top"> <name>eradaccount</name> <description>windows account.</description> <object-identifier>1.3.6.1.4.1.6054.3.125.1.1</object-identifier>... <attribute ref="eradboolean" required="false"/> <attribute ref="eraddate" required="false"/> <attribute ref="eradinteger" required="false"/> <attribute ref="eradmultivaluestring" required="false"/> <attribute ref="eradstring1" required="false"/> </class>... </directory-schema> </dsml> Each of the sections of this schema file are described in the following sections. identifier The Tivoli Identity Manager Server uses LDAP directory services to add, delete, modify, and search Tivoli Identity Manager data. Each data item in an LDAP directory server must have a unique OID. Therefore, each attribute and class that is defined in the schema.dsml file in Tivoli Identity Manager has an OID. OIDs have the following syntax: enterprise ID.product ID.adapter ID.object ID.instance ID The enterprise ID is always 1.3.6.1.4.1.6054 for IBM. The product ID is always 3 because these schema.dsml files are used with adapters. The adapter ID is 125 for the Active Directory Adapter. The object ID is 2. An attribute uses 2 as the object ID. The instance ID is a sequential number of the object. 54 IBM Tivoli Identity Manager: Active Directory Adapter Installation and Configuration Guide

Attribute definition Before defining unique attributes for the adapter, ensure that the attribute does not exist in the common schema.dsml file. The following example defines an attribute: <!-- *********************************************** --> <!-- ersamplehome --> <!-- *********************************************** --> <attribute-type single-value = "true" > <name>ersamplehome</name> <description>user home directory</description> <object-identifier>1.3.6.1.4.1.6054.3.125.2.100</object-identifier> <syntax>1.3.6.1.4.1.1466.115.121.1.15</syntax> </attribute-type> Comment lines are denoted by the <!... > markers. The attribute type is defined as single-value or multi-value. A single-value attribute is denoted by the line: <attribute-type single-value ="true">. In order to denote a multi-valued attribute, change the true value to false. The name of the attribute that is used by the Tivoli Identity Manager Server is defined in the schema. In order to simplify the tracking of new Active Directory Adapter attributes, use erad as the preface for all new attributes, so that they can be easily identified in your Windows Active Directory. When attributes have already been defined in the Windows Active Directory, and they do not conflict with existing attributes, they can be used without changing their names. The description of the attribute is denoted by the <description>...</description> tags. The OID is defined using the <object-identifier>...</object-identifier> tags. Because OIDs are already assigned to the existing, standard attributes, the OID can be copied from the last attribute in the list. However, the last number must be incremented by one for each new attribute that you add to the schema.dsml file. The data type is defined using the <syntax>...</syntax> tags. The following table lists various data types and the value you specify in the syntax tags. Table 13. Data types and values for syntax tags Data Type Value Bit string 1.3.6.1.4.1.1466.115.121.1.6 Boolean 1.3.6.1.4.1.1466.115.121.1.7 Directory String 1.3.6.1.4.1.1466.115.121.1.15 UTC Coded Time 1.3.6.1.4.1.1466.115.121.1.24 Integer 1.3.6.1.4.1.1466.115.121.1.27 Classes At least one account class and one service class must be defined in the schema.dsml file. Each class requires at least one attribute to identify the class: a name attribute. Additional attributes might be required depending on the class defined. Appendix A. Files 55

CustomLabels.properties The following syntax defines a class: <class superior="top"> <name>... </name> <description>... </description> <object-identifier>... </object-identifier> <attribute ref = "..." required = "true" /> <attribute ref = "..." required = "true" /> </class> In order to make an attribute optional for a class, change required = "true" to required = "false" in the <attribute ref> tag. An account class defines the attributes that are used to describe an account. An account class must be defined in the schema.dsml file. The following example defines an account class: <class superior="top" > <name>ersampleaccount</name> <description>sample Account</description> <object-identifier>1.3.6.1.4.1.6054.3.125.1.101</object-identifier> <attribute ref = "eruid" required = "true" /> <attribute ref = "eraccountstatus" required = "false" /> <attribute ref = "ersamplegroups" required = "false" /> <attribute ref = "ersamplehome" required = "false" /> <attribute ref = "ersampledesc" required = "false" /> <attribute ref = "erpassword" required = "false" /> </class> In this example, the class name is ersampleaccount and the only required attribute is eruid. However, note that eraccountstatus is a required attribute to suspend or restore accounts. file The CustomLabels.properties file is a text file that defines the labels on the form for the adapter. The syntax for the information in the file is: attribute=text where attribute is the same attribute defined in the xforms.xml file and text is the label that appears on the form in the Tivoli Identity Manager user interface for the account. The attribute must be in lowercase. This requirement comes from the Tivoli Identity Manager Server. 56 IBM Tivoli Identity Manager: Active Directory Adapter Installation and Configuration Guide

Appendix B. Adapter attributes As part of the adapter implementation, a dedicated account for Tivoli Identity Manager to access the Active Directory Server is created on the Active Directory Server. The Active Directory Adapter consists of files and directories that are owned by the Tivoli Identity Manager account. These files establish communication with the Tivoli Identity Manager Server. Attribute descriptions The Tivoli Identity Manager Server communicates with the Active Directory Adapter using attributes that are included in transmission packets that are sent over a network. The combination of attributes, included in the packets, depends on the type of action that the Tivoli Identity Manager Server requests from the Active Directory Adapter. Table 14 is an alphabetical listing of the attributes that are used by the Active Directory Adapter. The table gives a brief description and the data type for the value of the attribute. Table 14. Attributes, descriptions, and corresponding data types Directory server attribute Description Data type eradealias Specifies the alias for the Exchange Mailbox String eradallowdialin Specifies whether the user is allowed dial in access Boolean eradallowencryptedpassword Specifies whether encrypted passwords are allowed Boolean eradeautogenemailaddrs Specifies whether the recipient update services updates the e-mail address eradbadlogincount Specifies the number of invalid login attempts that are allowed since the last reset eradbasepoint Specifies the DN of the domain name, extended to allow any base point eradcallbacknumber Specifies the callback number for remote access services that is used when DialinCallBack is set to fixed eradcannotbedelegated Specifies that this account cannot be assigned for delegation by another account Boolean Long String String Boolean ercompany Specifies the name of the company that the user works for String eradcontainer Specifies the Relative Distinguished Name (RDN) of a container object in which to create the user account. The container is relative to the domain. Integer eradcontainercn Specifies the short name for the container object String eradcontainerdn Specifies the full DN for the container object String eradcontainerrdn Specifies the container RDN String eradcountycode Specifies the country where the user resides Integer eradedaysbeforegarbage Specifies the number of days that deleted mail is retained before it is permanently deleted eradedelegates Specifies the list of all users that have access to the Exchange Mailbox Integer String Copyright IBM Corp. 2003, 2005 57

Table 14. Attributes, descriptions, and corresponding data types (continued) Directory server attribute Description Data type erdepartment Specifies the department within the company to which the user belongs String description Specifies the description for the user String eraddialincallback Sets the Dial in Callback for the user. 1 No Callback 2 Fixed callback using eradcallbacknumber 3 This option is not used 4 User supplied callback Integer eraddisplayname Specifies the Active Directory displayname attribute String eraddomainpassword Specifies the password for the user ID that is used to connect to the Active Directory eraddomainuser Specifies the user ID that is used when connecting to the active directory erdivision Specifies the division within a company (organization) that the employee belongs to eraddistinguishedname Specifies the distinguished name of the account on the Active Directory String String String String erademployeeid Specifies the user s employee identifier String eradeenablestoredeflts Specifies whether to use only default store values for storage limits, or to use other properties pertaining to the Mailbox eradexpirationdate Specifies the date and time once the user cannot log in Date Boolean eradeextension1 Specifies a user defined extension attribute String eradeextension10 Specifies a user defined extension attribute String eradeextension11 Specifies a user defined extension attribute String eradeextension12 Specifies a user defined extension attribute String eradeextension13 Specifies a user defined extension attribute String eradeextension14 Specifies a user defined extension attribute String eradeextension15 Specifies a user defined extension attribute String eradeextension2 Specifies a user defined extension attribute String eradeextension3 Specifies a user defined extension attribute String eradeextension4 Specifies a user defined extension attribute String eradeextension5 Specifies a user defined extension attribute String eradeextension6 Specifies a user defined extension attribute String eradeextension7 Specifies a user defined extension attribute String eradeextension8 Specifies a user defined extension attribute String eradeextension9 Specifies a user defined extension attribute String eradfax Specifies the fax numbers of the user String givenname Specifies the user s first name String eradeforwardingstyle Specifies whether e-mail is also delivered to an alternative e-mail address String 58 IBM Tivoli Identity Manager: Active Directory Adapter Installation and Configuration Guide

Table 14. Attributes, descriptions, and corresponding data types (continued) Directory server attribute Description Data type eradeforwardto Specifies the URL where e mail is to be forwarded String cn Specifies the user s full name (first and last name) String eradegarbageafterbckp Specifies whether deleted messages can be permanently deleted once the Mailbox has been backed up Boolean ergroup Specifies names of groups String eradgroupcn Specifies the short name for the group object String eradgroupdn Specifies the full DN for the group object String eradegrouptype Specifies the group object String eradehardlimit Specifies the maximum Mailbox size in KB when sending and receiving e mail is disabled eradehidefromaddrsbk Specifies whether the address is displayed in the address book eradhomedir Specifies a null-terminated string containing the path of the user s home directory. This string can specify a local path or a UNC path. For example: \\machine\share\path eradhomedirdrive Specifies the drive letter to assign to a UNC based home directory eradhomedirntfsaccess Specifies the NTFS security level for the user s home directory eradhomedirshare Specifies the name of the share to create for home directory. Append a dollar sign ($) to create a hidden share. Integer Boolean String String String String eradhomediraccessshare Specifies the user access level on the share String eradehomemdb Specifies the URL of the store for the recipient String eradhomepage Specifies the URL for the user s home page String eradeincominglimit Specifies the maximum size in KB of a message sent to the recipient Integer eradinitial Specifies the middle initials of the user s name String eradisaccountlocked Specifies whether the account is locked because of intruder detection Boolean eradelanguages Specifies an array of language names for the user String eradlastfailedlogin Specifies the date and time of the last failed network login Date eradlastlogon Specifies the date and time of the last successful network login eradlastlogoff Specifies the date and time of the last network logoff Date sn Specifies the user s last name String erlogontimes Specifies the time periods for each day of the week during which logins are permitted for the user. Represented as a table of Boolean values for the week, each indicating if that time slot is a valid login time. Date Byte array eradloginscript Specifies the login script path String Login time (LT) Appendix B. Adapter attributes 59

Table 14. Attributes, descriptions, and corresponding data types (continued) Directory server attribute Description Data type eradloginworkstations Specifies a comma separated list of addresses or names of workstations from which the user can log into String mail Specifies the user s e-mail address String erademailboxstore Specifies the name of the mail store that will hold user Mailbox Binary erademailstorecn Specifies the mail store common name (CN) String erademailstoredn Specifies the mail store DN Binary erademailstoregn Specifies the mail store group name String erademailstorerdn Specifies the mail store object relative directory name (RDN) attribute erademailstoresn Specifies the Mailbox store single name includes server name (server - mailstore ) Binary String eradmanager Specifies the user ID for the user s manager String ermaxstorage Specifies the maximum amount of disk space, in KB, that the user can have eradnameprefix Specifies the user s title, for example Ms. or Mr. String eradnamesuffix Specifies the user s name suffix, for example Jr., or III String eradnochangepassword Specifies whether the user can change their password Boolean eradofficelocations Specifies the office location String eradothername Specifies an additional name, for example, the middle name, for the user eradeoutgoinglimit Specifies the maximum size in KB of a message sent from the recipient eradeoverquotalimit Specifies the maximum size of a Mailbox in KB before sending messages is suspended eradeoverridegarbage Specifies whether the store will be prevented from permanently deleting messages erpasswordexpireson Specifies the date and time that the password expires Date Long String Integer Integer Boolean eradpasswordforcechange Specifies whether to force a password change on next login Boolean eradpasswordlastchange Specifies the last time that the password was changed Date eradpasswordminimumlength Specifies the minimum length of the password Long eradpasswordneverexpires Specifies whether a password can never expire Boolean eradpasswordrequired Specifies whether the password is required Boolean l Specifies the user s city or location (shown as the lowercase letter 'l' ) String postofficebox Specifies the user s Post Office Box String st Specifies the state where the user resides String street Specifies the street address where the user resides String postalcode Specifies the user s postal code for their address String eradprimarygroup Specifies the primary group ID String eradprimarygrptkn Specifies the ID of the group that is used to set primary group String erprofile Specifies the path to the user s profile String 60 IBM Tivoli Identity Manager: Active Directory Adapter Installation and Configuration Guide

Table 14. Attributes, descriptions, and corresponding data types (continued) Directory server attribute Description Data type eradeproxyaddresses Specifies a list of proxy addresses for the recipient String eraderecipientlimit Specifies the maximum number of people to whom the recipient can send e-mail eradrequireuniquepassword Specifies whether a new password must be different from those known through a password history eraderstrctadrsfg Specifies the flag to accept or reject the list of e-mail addresses that are listed in the eraderstrctadrsls attribute Integer Boolean Integer eraderstrctadrsls Specifies a list of e-mail addresses to accept or reject String eradeservername Specifies the name of the Microsoft Exchange Server String eradeshowinaddrbook Specifies the list of address books that the user is a member of String eradsmartcardrequired Specifies whether a smart card is required for login Boolean eradesmtpemail Specifies the primary SMTP address that is used for the recipient eradestorequota Specifies a limit when the recipient will get a warning for exceeding their mail file storage allocation String Integer eradetargetaddress Specifies the external e mail address to be used by the user String homephone Specifies the user s home telephone number String mobile Specifies the user s mobile telephone number String pager Specifies the user s pager number String telephonenumber Specifies the user s work telephone number String title Specifies the user s title String eradtrustedfordelegation Specifies that the user has the ability to assign responsibility for management and administration of a portion of the domain namespace to another user, group or organization Boolean eruid Specifies the user ID String erpassword Specifies the password for the user account String eradupn Specifies the principal name for the user account String eradwtsallowlogon Specifies whether the user account is permitted to log on to a terminal server eradwtsbrokentimeout Specifies what happens when the connection or idle timers expire or when a connection is lost due to a connection error eradwtscallbacknumber Citrix ICA clients must specify a null-terminated string containing the phone number to use for callback connections Boolean Boolean Long String Appendix B. Adapter attributes 61

Table 14. Attributes, descriptions, and corresponding data types (continued) Directory server attribute Description Data type eradwtscallbacksettings Citrix ICA clients must specify a value that indicates the configuration for dialup connections in which the terminal server hangs up and then calls back the client to establish the connection. Valid values indicate: 1 - The server prompts the user to enter a phone number, and calls the user back at that phone number. You can use the WtsCallbackNumber value to specify a default phone number. 2 - The server automatically calls the user back at the phone number specified by the WtsCallbackNumber value. eradwtsclientdefaultprinter RDP 5.0 clients and Citrix ICA clients must specify whether the client printer is the default printer eradwtsclientdrives Citrix ICA clients must specify whether the terminal server automatically establishes client drive mappings at login eradwtsclientprinters RDP 5.0 clients and Citrix ICA clients must specify whether the terminal server automatically establishes client printer mappings at login eradwtshomedir Specifies a null-terminated string for the path of the user s home directory for terminal server login. This string can specify a local path or a UNC path (\\machine\share\path) eradwtshomediraccessshare Specifies the user access level to the share on the WTS home directory eradwtshomedirdrive Specifies a null-terminated string for a drive letter to which the UNC path specified in the WtsHomeDir string is mapped Integer Boolean Boolean Boolean String Integer String eradwtshomedirntfsaccess Specifies the NTFS access to the home directory String eradwtshomedirshare Specifies the name of a share to create the WTS home directory. Append a dollar sign ($) to create a hidden share. eradwtsinheritinitialprog Specifies whether the client can specify the initial program. If not set, WtsInitialProgram is the only program the user can run. The terminal server logs off the user when the user exits that program. eradwtsinitialprogram Specifies a null-terminated string for the path of the initial program that Terminal Services runs when the user logs into. If the WtsInheritInitialProgram value is 1, the initial program can be any program specified by the client. eradwtsprofilepath Specifies a null-terminated string for the path of the user s profile for terminal server login String Boolean String String 62 IBM Tivoli Identity Manager: Active Directory Adapter Installation and Configuration Guide

Table 14. Attributes, descriptions, and corresponding data types (continued) Directory server attribute Description Data type eradwtsreconnectsettings Specifies a value that indicates how a disconnected session for a user can be reconnected. Valid values indicate: 0 - The user can login to any client computer to reconnect to a disconnected session. Note that sessions started at clients other than the system console cannot be connected to the system console, and sessions started at the system console cannot be disconnected. 1 - The user can reconnect to a disconnected session by logging on to the client computer used to establish the disconnected session. If the user logs on from a different client computer, the user gets a new login session. Integer eradwtsremotehomedir Specifies the user s home directory on the Windows Server String eradwtsservername Specifies the name of the WTS where the user is configured String eradwtsshadowsettings RDP 5.0 clients and Citrix ICA clients must specify a value that indicates whether the user session can be shadowed. Shadowing allows a user to remotely monitor the on-screen operations of another user. eradwtstimeoutconnections Specifies a value that specifies the maximum connection duration, in milliseconds. One minute before the connection timeout interval expires, the user is notified of the pending disconnection. The user s session is disconnected or terminated depending on the WtsBrokenTimeout value. Every time the user logs on, the timer is reset. A value of zero indicates the connection timer is disabled. eradwtstimeoutdisconnections Specifies the maximum duration, in milliseconds, that a WTS retains a disconnected session before the login is terminated. A value of zero indicates the disconnection timer is disabled. eradwtstimeoutidle Specifies the maximum idle time, in milliseconds. If there is no keyboard or mouse activity for the specified interval, the user s session is disconnected or terminated depending on the WtsBrokenTimeout value. A value of zero indicates the idle timer is disabled. eradwtsworkingdir Specifies a null-terminated string for the path of the working directory for the initial program eradex400email Specifies the primary X.400 address that is used for the recipient eradedelmailboxstorage Specifies whether the user has delete Mailbox storage permission Integer Integer Integer Integer String String Integer eradereadpermissions Specifies whether the user has read Mailbox permission Integer eradechgpermissions Specifies whether to change the user s Mailbox permission Integer eradetakeownership Specifies whether the user has take Mailbox ownership permission eradefullmailboxaccess Specifies whether the user has full Mailbox access permission eradeassociatedextacc Specifies whether the user has associated external account permission Integer Integer Integer Appendix B. Adapter attributes 63

Table 14. Attributes, descriptions, and corresponding data types (continued) Directory server attribute Description Data type eradeapplyontoallow Specifies the scope of ACCESS_ALLOWED permissions Integer eradeallowpermto1level Specifies the value to use for applying these permission to objects and containers within this container for ACCESS_ALLOWED Boolean eradeapplyontodeny Specifies the scope of ACCESS_DENIED permissions Integer eradedenypermto1level Specifies the value to use for applying these permission to objects and containers within this container for ACCESS_DENIED Boolean Active Directory Adapter attributes by action The following lists are typical Active Directory Adapter actions by their functional transaction group. The lists include more information about required and optional attributes sent to the Active Directory Adapter to complete that action. System Login Add A System Login Add is a request to create a new user account in the domain with the specified attributes. Table 15. Add request attributes Required attribute Optional attribute eruid All other supported attributes System Login Change A System Login Change is a request to change one or more attributes for the specified users. Table 16. Change request attributes Required attribute Optional attribute eruid All supported attributes System Login Delete A System Login Delete is a request to remove the specified user from the Active Directory. Table 17. Delete request attributes Required attribute Optional attribute eruid eradbasepoint eraddomainuser eraddomainpassword System Login Suspend A System Login Suspend is a request to disable a user account. The user is neither removed nor are their attributes modified. 64 IBM Tivoli Identity Manager: Active Directory Adapter Installation and Configuration Guide

Table 18. Suspend request attributes Required attribute Optional attribute eruid eradbasepoint eraccountstatus eraddomainuser eraddomainpassword System Login Restore A System Login Restore is a request to activate a user account that was previously suspended. Once an account is restored, the user can access the system with the same attributes as those before the Suspend function was called. Table 19. Restore request attributes Required attribute Optional attribute eruid eradbasepoint eraccountstatus eraddomainuser eraddomainpassword Reconciliation The Reconciliation function synchronizes user account information between Tivoli Identity Manager and the adapter. Table 20. Reconciliation attributes Required attribute Optional attribute None eradbasepoint eraddomainuser eraddomainpassword Appendix B. Adapter attributes 65

66 IBM Tivoli Identity Manager: Active Directory Adapter Installation and Configuration Guide

Appendix C. Support information This section describes the following options for obtaining support for IBM products: v Searching knowledge bases v Obtaining fixes on page 68 Searching knowledge bases v Contacting IBM Software Support on page 68 If you have a problem with your IBM software, you want it resolved quickly. Begin by searching the available knowledge bases to determine whether the resolution to your problem is already documented. Search the information center on your local system or network IBM provides extensive documentation that can be installed on your local computer or on an intranet server. You can use the search function of this information center to query conceptual information, instructions for completing tasks, reference information, and support documents. Search the Internet If you cannot find an answer to your question in the information center, search the Internet for the latest, most complete information that might help you resolve your problem. To locate Internet resources for your product, open one of the following Web sites: v IBM Tivoli Identity Manager Performance Tuning Guide Provides information needed to tune Tivoli Identity Manager Server for a production environment, available on the Web at: http://publib.boulder.ibm.com/tividd/td/tdprodlist.html Click the I character in the A-Z product list, and then, click the Tivoli Identity Manager link. Browse the information center for the Technical Supplements section. v Redbooks and white papers are available on the Web at: http://www.ibm.com/software/sysmgmt/products/support/ IBMTivoliIdentityManager.html Browse to the Self Help section, in the Learn category, and click the Redbooks link. v Technotes are available on the Web at: http://www.redbooks.ibm.com/redbooks.nsf/tips/ v Field guides are available on the Web at: http://www.ibm.com/software/sysmgmt/products/support/field_guides.html v For an extended list of other Tivoli Identity Manager resources, search the following IBM developerworks Web address: http://www.ibm.com/developerworks/ Copyright IBM Corp. 2003, 2005 67

Obtaining fixes A product fix might be available to resolve your problem. You can determine what fixes are available for your IBM software product by checking the product support Web site: 1. Go to the IBM Software Support Web site (http://www.ibm.com/software/support). 2. Under Products support pages A to Z, select the letter for your product name. 3. In the list of specific products, click IBM Tivoli Identity Manager. 4. Under Self help, you find a list of fixes, fix packs, and other service updates for your product. 5. Click the name of a fix to read the description and optionally download the fix. To receive weekly e-mail notifications about fixes and other news about IBM products, follow these steps: 1. From the support page for any IBM product, click My support in the upper-left corner of the page. 2. If you have already registered, skip to the next step. If you have not registered, click register in the upper-right corner of the support page to establish your user ID and password. 3. Sign in to My support. 4. On the My support page, click Edit profiles in the left navigation pane, and scroll to Select Mail Preferences. Select a product family and check the appropriate boxes for the type of information you want. 5. Click Submit. 6. For e-mail notification for other products, repeat Steps 4 and 5. For more information about types of fixes, see the Software Support Handbook (http://techsupport.services.ibm.com/guides/handbook.html). Contacting IBM Software Support IBM Software Support provides assistance with product defects. Before contacting IBM Software Support, your company must have an active IBM software maintenance contract, and you must be authorized to submit problems to IBM. The type of software maintenance contract that you need depends on the type of product you have: v For IBM distributed software products (including, but not limited to, Tivoli, Lotus, and Rational products, as well as DB2 and WebSphere products that run on Windows or UNIX operating systems), enroll in Passport Advantage in one of the following ways: Online: Go to the Passport Advantage Web page (http://www.lotus.com/services/passport.nsf/webdocs/ Passport_Advantage_Home) and click How to Enroll By phone: For the phone number to call in your country, go to the IBM Software Support Web site (http://techsupport.services.ibm.com/guides/contacts.html) and click the name of your geographic region. v For IBM eserver software products (including, but not limited to, DB2 and WebSphere products that run in zseries, pseries, and iseries environments), you can purchase a software maintenance agreement by working directly with an IBM sales representative or an IBM Business Partner. For more information 68 IBM Tivoli Identity Manager: Active Directory Adapter Installation and Configuration Guide

about support for eserver software products, go to the IBM Technical Support Advantage Web page (http://www.ibm.com/servers/eserver/techsupport.html). If you are not sure what type of software maintenance contract you need, call 1-800-IBMSERV (1-800-426-7378) in the United States or, from other countries, go to the contacts page of the IBM Software Support Handbook on the Web (http://techsupport.services.ibm.com/guides/contacts.html) and click the name of your geographic region for phone numbers of people who provide support for your location. Follow the steps in this topic to contact IBM Software Support: 1. Determine the business impact of your problem. 2. Describe your problem and gather background information. 3. Submit your problem to IBM Software Support. Determine the business impact of your problem When you report a problem to IBM, you are asked to supply a severity level. Therefore, you need to understand and assess the business impact of the problem you are reporting. Use the following criteria: Severity 1 Critical business impact: You are unable to use the program, resulting in a critical impact on operations. This condition requires an immediate solution. Severity 2 Significant business impact: The program is usable but is severely limited. Severity 3 Some business impact: The program is usable with less significant features (not critical to operations) unavailable. Severity 4 Minimal business impact: The problem causes little impact on operations, or a reasonable circumvention to the problem has been implemented. Describe your problem and gather background information When explaining a problem to IBM, be as specific as possible. Include all relevant background information so that IBM Software Support specialists can help you solve the problem efficiently. To save time, know the answers to these questions: v What software versions were you running when the problem occurred? v Do you have logs, traces, and messages that are related to the problem symptoms? IBM Software Support is likely to ask for this information. v Can the problem be re-created? If so, what steps led to the failure? v Have any changes been made to the system? (For example, hardware, operating system, networking software, and so on.) v Are you currently using a workaround for this problem? If so, please be prepared to explain it when you report the problem. Submit your problem to IBM Software Support You can submit your problem in one of two ways: v Online: Go to the Submit and track problems page on the IBM Software Support site (http://www.ibm.com/software/support/probsub.html). Enter your information into the appropriate problem submission tool. Appendix C. Support information 69

v By phone: For the phone number to call in your country, go to the contacts page of the IBM Software Support Handbook on the Web (http://techsupport.services.ibm.com/guides/contacts.html) and click the name of your geographic region. If the problem you submit is for a software defect or for missing or inaccurate documentation, IBM Software Support creates an Authorized Program Analysis Report (APAR). The APAR describes the problem in detail. Whenever possible, IBM Software Support provides a workaround for you to implement until the APAR is resolved and a fix is delivered. IBM publishes resolved APARs on the IBM product support Web pages daily, so that other users who experience the same problem can benefit from the same resolutions. For more information about problem resolution, see Searching knowledge bases and Obtaining fixes. 70 IBM Tivoli Identity Manager: Active Directory Adapter Installation and Configuration Guide

Appendix D. Notices This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user s responsibility to evaluate and verify the operation of any non-ibm product, program, or service. IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not give you any license to these patents. You can send license inquiries, in writing, to: IBM Director of Licensing IBM Corporation North Castle Drive Armonk, NY 10504-1785 U.S.A. For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to: IBM World Trade Asia Corporation Licensing 2-31 Roppongi 3-chome, Minato-ku Tokyo 106-0032, Japan The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION AS IS WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you. This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice. Any references in this information to non-ibm Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk. IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you. Copyright IBM Corp. 2003, 2005 71

Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged should contact: IBM Corporation 2ZA4/101 11400 Burnet Road Austin, TX 78758 U.S.A. Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee. The licensed program described in this information and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement, or any equivalent agreement between us. Any performance data contained herein was determined in a controlled environment. Therefore, the results obtained in other operating environments may vary significantly. Some measurements may have been made on development-level systems and there is no guarantee that these measurements will be the same on generally available systems. Furthermore, some measurements may have been estimated through extrapolation. Actual results may vary. Users of this document should verify the applicable data for their specific environment. Information concerning non-ibm products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-ibm products. Questions on the capabilities of non-ibm products should be addressed to the suppliers of those products. Trademarks The following terms are trademarks or registered trademarks of International Business Machines Corporation in the United States, other countries, or both: IBM IBM logo AIX DB2 Novell SecureWay Tivoli Tivoli logo Universal Database WebSphere Lotus is a registered trademark of Lotus Development Corporation and/or IBM Corporation. Domino is a trademark of International Business Machines Corporation and Lotus Development Corporation in the United States, other countries, or both. 72 IBM Tivoli Identity Manager: Active Directory Adapter Installation and Configuration Guide

Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both. Intel, Intel Inside (logos), MMX and Pentium are trademarks of Intel Corporation in the United States, other countries, or both. UNIX is a registered trademark of The Open Group in the United States and other countries. Linux is a trademark of Linus Torvalds in the U.S., other countries, or both. Sun, Sun Microsystems, and the Sun Logo are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries. Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both. Other company, product, and service names may be trademarks or service marks of others. Appendix D. Notices 73

74 IBM Tivoli Identity Manager: Active Directory Adapter Installation and Configuration Guide

Index A accessibility pdf format, for screen-reader software ix statement for documentation ix text, alternative for document images ix activity logging 19 adapter ADK upgrade 49 attributes by adapter action 64 descriptions 57 base point configuration 47 configuration steps 6 customization steps 43 extend attributes 43 features 1 installation 3 installation overview 1 installation prerequisites 3 profile purpose 4 removal 51 upgrade 49 adapter configuration tool See agentcfg adapter overview 1 add request attributes 64 ADK46Installer.log file 50 ADK46Installeropt.log file 50 administrator authority prerequisites 3 agentcfg arguments 27 changing adapter parameters configuration key 19 protocol settings 11 registry settings 21 request processing 25 menus activity logging 19 advanced settings 25 event notification 14 help 27 Main Configuration 9 Protocol Configuration 10 registry 21 viewing configuration settings 10 attributes by Active Directory Adapter action add 64 change 64 delete 64 restore 65 suspend 64 descriptions 57 extension 43 reconciliation 65 B books see publications viii C certificate authority definition 29 certificate signing request (CSR) 38 certificates CA available functions 36 deleting 39 installing 39 viewing installed 39 certificate management tools See CertTool definition 29 examples certificate signing request (CSR) 38 install 38 installation from file 38 sample 38 key formats 31 overview 29 private keys and digital certificates 30 protocol configuration tool See CertTool register 36 registered registering 40 removing 40 viewing 40 request 37 self-signed 30 viewing installed 39 registered 40 viewing installed 39 viewing registered 40 CertTool CA certificate deleting 39 installing 39 viewing 39 certificate install 38 register 36 request 37 viewing installed 39 viewing registered 40 changing adapter parameters accessing 31, 35 options 36 client authentication 36 install certificate 38 private key, generating 37 registered certificate registering 40 removing 40 viewing 40 change request attributes 64 character sets, supported 25 client authentication 33 client validation, SSL 34 Copyright IBM Corp. 2003, 2005 75

configuration base point 47 key changing with agentcfg 19 default value 9, 19 purpose 9 settings changing with agentcfg 9 default value 10 viewing with agentcfg 10 SSL 32 context baseline database 19 deleting 15 listing 16 modifying 17 search attributes 17 target DN 18 conventions HOME directory Tivoli_Common_Directory xii DB_INSTANCE_HOME x HTTP_HOME xi ITIM_HOME xii LDAP_HOME xi WAS_HOME xii WAS_MQ_HOME xii WAS_NDM_HOME xii typeface ix UNIX variable, directory notation x used in this document ix CSR definition 37 file, generating 37 customer support see Software Support 68 CustomLabels.properties file 56 updating 45 D DAML protocol configuring with agentcfg 11 encryption default value 11 type 11 options 11 properties, changing with agentcfg options 11 password 12 portnumber 12 require_cert_reg 13 srv_nodename 12 srv_portnumber 12 username 11 validate_client_ce 13 SSL authentication 31 DB_INSTANCE_HOME DB2 UDB installation directory x definition x debug log default value 20 enable/disable with agentcfg 19 purpose 21 delete request attributes 64 detail log default value 20 detail log (continued) enable/disable with agentcfg 19 purpose 21 directory DB_INSTANCE_HOME x HTTP_HOME xi installation DB2 UDB x IBM Directory Server xi IBM HTTP Server xi WebSphere Application Server base product xii WebSphere Application Server Network Deployment product xii WebSphere MQ xii installation for Sun ONE Directory Server xi ITIM_HOME xii LDAP_HOME xi names, UNIX notation x WAS_HOME xii WAS_MQ_HOME xii WAS_NDM_HOME xii disabilities, using documentation ix disk space prerequisites 3 documents related viii Tivoli Identity Manager library v E enable/disable with agentcfg 19 encrypted registry settings 21 encryption DAML protocol default value 11 type 11 SSL 29, 30 environment variable UNIX notation x event notification cache size 15 changing with agentcfg 14 context baseline database 19 deleting 15 listing 16 modifying 17 search attributes 17 target DN 18 enable/disable 15 reconciliation attributes 15 context 15 intervals 15 modifying 15 process priority 15 starting manually 15 Exchange Mailbox prerequisites 3 exschema.txt file 44 F files adapter-specific 53 CustomLabels.properties file 56 updating 45 76 IBM Tivoli Identity Manager: Active Directory Adapter Installation and Configuration Guide

files (continued) examples schema.dsml file 53 exschema.txt file 44 schema.dsml file 53 classes 55 object identifier 54 updating 45 xforms.xml file 53 fixes, obtaining 68 H help menu for agentcfg 27 accessing with -help command 27 home directories DB_INSTANCE_HOME x HTTP_HOME xi ITIM_HOME xii LDAP_HOME xi WAS_HOME xii WAS_MQ_HOME xii WAS_NDM_HOME xii HTTP_HOME definition xi IBM HTTP Server installation directory xi I import adapter profile 4, 46 PKCS12 file 31 information centers, searching to find software problem resolution 67 installation adapter 3 certificate 38 directory DB2 UDB x IBM Directory Server xi IBM HTTP Server xi Sun ONE Directory Server xi WebSphere Application Server base product xii WebSphere Application Server Network Deployment product xii WebSphere MQ xii prerequisites 3 profile 4 uninstall 51 installation prerequisites administrator authority 3 network connectivity 3 operating system 3 Tivoli Identity Manager Server 3 Internet, searching to find software problem resolution 67, 68 ITIM_HOME definition xii directory xii K knowledge bases, searching to find software problem resolution 67 L LDAP_HOME definition xi IBM Directory Server installation directory xi Sun ONE Directory Server installation directory xi logs activity settings, changing 10 ADK46Installer.log file 50 ADK46Installeropt.log file 50 debug 19 detail 19 directory, changing with agentcfg 20 display using agentcfg 28 enable/disable, changing with agentcfg 20 file name, changing with agentcfg 19 settings, changing with adaptercfg 20 settings, changing with agentcfg log file name 20 max file size 20 settings, default values 19 statistics 26 trace.log file 5 view events 10 viewing statistics 26 M manuals see publications viii memory prerequisites 3 N network connectivity prerequisites 3 non-encrypted registry settings 21, 22 O online publications accessing viii operating system prerequisites 3 P password protected file See PKCS12 file passwords changing configuration key 19 configuration key, default value 9, 19 passwords, changing with agentcfg DAML protocol 12 path names, notation x pdf format, for screen-reader software ix PKCS12 file certificate and key installation 38 export certificate and key 41 portnumber changing with agentcfg 11 portnumber, changing with agentcfg 12 private key definition 29 private key, generating 37 problem determination describing problem for IBM Software Support 69 determining business impact for IBM Software Support 69 Index 77

problem determination (continued) submitting problem to IBM Software Support 69 properties, changing with agentcfg 11 protocol DAML configuring with agentcfg 11 encryption default value 11 encryption type 11 properties, changing with agentcfg 11 SSL overview 29 server-to-adapter configuration 32 two-way configuration 33, 34 public key 30 publications accessing online viii related viii Tivoli Identity Manager library v R reconciliation attributes 15 context 15 intervals 15 modifying 15 process priority 15 reconciliation attributes 65 registry settings encrypted 21 non-encrypted 21, 22 request attributes add 64 change 64 delete 64 restore 65 suspend 64 require_cert_reg, changing with agentcfg 13 restore request attributes 65 restoring accounts password requirements 46 S schema.dsml file 53 updating 45 self-signed certificate 30 Software Support contacting 68 describing problem for IBM Software Support 69 determining business impact for IBM Software Support 69 submitting problem to IBM Software Support 69 srv_nodename, changing with agentcfg 12 srv_portnumber, changing with agentcfg 12 SSL certificate installation 29 certificate signing request 37 encryption 29 key formats 31 overview 29 private keys and digital certificates 30 self-signed certificates 30 server-to-adapter configuration 32 two-way configuration 33, 34 SSL implementations, DAML protocol 31 suspend request attributes 64 system prerequisites 3 T text, alternative for document images ix thread count settings changing with agentcfg 25 default values 25 maximum concurrent requests 25 reconciliation requests 25 system login add requests 25 system login change requests 25 system login delete requests 25 Tivoli Identity Manager Adapter communication with the server 33, 34 SSL communication 33, 34 Tivoli Identity Manager Server communication with the adapter 32 configuring event notification 14 importing adapter profile 4 SSL communication 32 Tivoli Identity Manager Server prerequisites 3 Tivoli software information center viii Tivoli_Common_Directory definition xii trace.log file 5 two-way configuration SSL client 33 client and server 34 typeface conventions ix U uninstallation 51 updating adapter form 46 adapter profile 43 upgrade adapter 49 adapter profile 5 ADK 49 username, changing with agentcfg 11 UTF8 support 25 V validate_client_ce, changing with agentcfg 13 W WAS_HOME definition xii WebSphere Application Server base installation directory xii WAS_MQ_HOME definition xii WebSphere MQ installation directory xii WAS_NDM_HOME definition xii WebSphere Application Server Network Deployment installation directory xii western European character set, support 25 Windows Local Account Adapter 1 78 IBM Tivoli Identity Manager: Active Directory Adapter Installation and Configuration Guide

X xforms.xml file 53 Index 79

80 IBM Tivoli Identity Manager: Active Directory Adapter Installation and Configuration Guide

Printed in USA SC32-1376-09