Post on 12-Sep-2020
IBM Security Privileged Identity Manager
Cisco Unified CommunicationsManager Adapter Installation andConfiguration Guide
IBM
IBM Security Privileged Identity Manager
Cisco Unified CommunicationsManager Adapter Installation andConfiguration Guide
IBM
ii Cisco Unified Communications Manager Adapter Installation and Configuration Guide
Contents
Figures . . . . . . . . . . . . . . . v
Tables . . . . . . . . . . . . . . . vii
Chapter 1. Overview . . . . . . . . . 1Features of the adapter . . . . . . . . . . . 1Architecture of the adapter . . . . . . . . . 1Supported configurations . . . . . . . . . . 2
Chapter 2. Planning. . . . . . . . . . 5Roadmap for IBM Tivoli Directory Integrator basedadapters, for IBM Security Privileged IdentityManager . . . . . . . . . . . . . . . . 5Prerequisites . . . . . . . . . . . . . . 6Software downloads . . . . . . . . . . . . 7Installation worksheet . . . . . . . . . . . 8
Chapter 3. Installing . . . . . . . . . 9Installing the dispatcher . . . . . . . . . . 9Installing the adapter binaries or connector . . . . 9Verifying the adapter installation . . . . . . . 10Restarting the adapter service . . . . . . . . 10Importing the adapter profile . . . . . . . . 10Creating an adapter service/target. . . . . . . 11Service/Target form details . . . . . . . . . 12Verifying that the adapter is working correctly . . 15
Chapter 4. Upgrading . . . . . . . . 17Upgrading the adapter binaries or connector . . . 17Upgrading the adapter profile . . . . . . . . 17
Chapter 5. Configuring . . . . . . . . 19Customizing the adapter profile . . . . . . . 19Editing the adapter profile on the UNIX or Linuxoperating system . . . . . . . . . . . . 20Password management for account restoration . . 21Enabling SSL communication . . . . . . . . 21
SSL terminology for adapters . . . . . . . 22Configuring certificates for SSL authentication . . 23Tasks done on the SSL server . . . . . . . 25Tasks performed on the SSL client (IBM SecurityIdentity Manager and WebSphere ApplicationServer workstation). . . . . . . . . . . 29
Chapter 6. Troubleshooting . . . . . . 33Techniques for troubleshooting problems . . . . 33Error messages and problem solving . . . . . . 35
Chapter 7. Uninstalling . . . . . . . . 37Removing the adapter binaries or connector . . . 37Deleting the adapter profile . . . . . . . . . 37
Chapter 8. Reference . . . . . . . . 39Adapter attributes and object classes . . . . . . 39
Index . . . . . . . . . . . . . . . 43
iii
iv Cisco Unified Communications Manager Adapter Installation and Configuration Guide
Figures
1. The architecture of the Cisco UnifiedCommunications Manager Adapter . . . . . 2
2. Example of a single server configuration . . . 33. Example of multiple server configuration 3
4. One-way SSL communication (servercommunication) . . . . . . . . . . . 23
5. Two-way SSL communication (clientcommunication) . . . . . . . . . . . 24
v
vi Cisco Unified Communications Manager Adapter Installation and Configuration Guide
Tables
1. Prerequisites to install the adapter . . . . . 72. Required information to install the adapter 83. Operating system and JAR file path . . . . 104. Messages and corrective action . . . . . . 35
5. Required attributes for the erCUCMAccountobject class . . . . . . . . . . . . . 39
6. Optional attributes for the erCUCMAccountobject class . . . . . . . . . . . . . 39
vii
viii Cisco Unified Communications Manager Adapter Installation and Configuration Guide
Chapter 1. Overview
An adapter is an interface between a managed resource and the IBM® SecurityIdentity server.
The Security Identity Manager server manages access to the resource by using yoursecurity system. Adapters function as trusted virtual administrators on the targetplatform. They perform tasks, such as creating, modifying, and deleting useraccounts, and other manual functions. The adapter runs as a service,independently of whether you are logged on to the Security Identity Managerserver.
The Cisco Unified Communications Manager Adapter enables communicationbetween the Security Identity Manager server and the Cisco UnifiedCommunications Manager server.
Features of the adapterThe adapter automates several administrative and management tasks.
The adapter automates the following user account management tasks:
Managing user accountsUse the adapter to add, modify, or delete user accounts.
Changing the user account password or personal identification number (PIN)Use the adapter to change the password or PIN or both for a user.
Adding users to groups Use the adapter to add and to remove users from groups.
Associating users with phones, phone profiles, and extensionsUse the adapter to associate the user with multiple phones, phone profiles,and a single primary extension.
Reconciling user account information Use the adapter to reconcile information from the managed resource toSecurity Identity Manager server for synchronization.
Reconciling support dataUse the adapter to reconcile support data information, such as phones,phone profiles, lines, and groups.
Managing remote destination profilesUse the adapter to add and delete remote destination profiles with defaultvalues.
Note: The managed resource does not support the Suspend and Restoreuser operations.
Architecture of the adapterSeveral components are involved in running and using the adapter. Install all thesecomponents so that the adapter can function correctly.
1
Security Identity Manager communicates with the Cisco Unified CommunicationsManager Adapter to administer users on the Cisco Unified CommunicationsManager resource.
You must install the following components for the adapter to function correctly:v The Dispatcherv The Tivoli Directory Integrator connectorv IBM Security Identity Adapter profile
You must install the Dispatcher and the adapter profile, however, the TivoliDirectory Integrator connector might already be installed with the base TivoliDirectory Integrator product.
Figure 1 describes the components that work together to complete the user accountmanagement tasks in a Tivoli Directory Integrator environment.
For more information about Tivoli Directory Integrator, see the Quick Start Guide athttp://www-01.ibm.com/support/knowledgecenter/SSRMWJ_6.0.0/com.ibm.isim.doc_6.0/ic-homepage.htm.
Supported configurationsThe adapter supports both single and multiple server configurations.
The fundamental components in each environment are:v The IBM Security Identity serverv The Tivoli Directory Integrator serverv The managed resourcev The adapter
The adapter must reside directly on the server running the Tivoli DirectoryIntegrator server.
Single server configurationIn a single server configuration, install the IBM Security Identity server, theTivoli Directory Integrator server, and the Cisco Unified CommunicationsManager Adapter on one server to establish communication with the CiscoUnified Communications Manager server. Install the Cisco UnifiedCommunications Manager server on a different server as describedFigure 2 on page 3.
RMI callsIBM SecurityIdentityServer
DispatcherService(an instanceof the IBMTivoliDirectoryIntegrator)
Adapterresource
Figure 1. The architecture of the Cisco Unified Communications Manager Adapter
2 Cisco Unified Communications Manager Adapter Installation and Configuration Guide
Multiple server configurationIn multiple server configuration, install the IBM Security Identity server,the Tivoli Directory Integrator server, the Cisco Unified CommunicationsManager Adapter, and the Cisco Unified Communications Manager serveron different servers. Install the Tivoli Directory Integrator server and theCisco Unified Communications Manager Adapter on the same server asdescribed Figure 3.
IBM SecurityIdentity Server
Tivoli DirectoryIntegrator Server
Adapter
Managedresource
Figure 2. Example of a single server configuration
IBM SecurityIdentity Managerserver
Security DirectoryIntegrator server Managed
resource
Adapter
Figure 3. Example of multiple server configuration
Chapter 1. Overview 3
4 Cisco Unified Communications Manager Adapter Installation and Configuration Guide
Chapter 2. Planning
Installing and configuring the adapter involves several steps that you mustcomplete in a specific sequence. Follow the roadmap for the main tasks.
Roadmap for IBM Tivoli Directory Integrator based adapters, for IBMSecurity Privileged Identity Manager
Follow this section when using the guide to install, configure, troubleshoot, oruninstall the adapter.
Pre-installation
Complete these tasks.1. Verify that your environment meets the software and hardware requirements
for the adapter. See Prerequisites.2. Obtain the installation software. See Software downloads.3. Obtain the necessary information for the installation and configuration. See
Installation worksheet.
Installation
Complete these tasks.1. Install the dispatcher.2. Install the adapter binaries or connector.3. Install 3rd party client libraries.4. Set up the adapter environment.5. Restart the adapter service.6. Import the adapter profile.7. Create an adapter service/target.8. Install the adapter language package.9. Verify that the adapter is working correctly.
Upgrade
To upgrade the adapter, do a complete re-installation of the adapter. Follow theInstallation roadmap.
Configuration
Complete these tasks.1. Configure secure communication between the IBM Security Identity server and
the adapter.a. Configure 1-way authentication.b. Configure 2-way authentication.
2. Configure secure communication between the adapter and the managed target.a. Configure 1-way authentication.b. Configure 2-way authentication.
5
3. Configure the adapter.4. Modify the adapter profiles.5. Customize the adapter.
Troubleshooting
See the following topics.v Techniques for troubleshooting problemsv Configure debuggingv Logsv Error messages and problem solving
Uninstallation
Complete these tasks.1. Stop the adapter service.2. Remove the adapter binaries or connector.3. Remove 3rd party client libraries.4. Delete the adapter service/target.5. Delete the adapter profile.
Reference
See the following topics.v Adapter attributes and object classesv Adapter attributes by operationsv Special attributes
PrerequisitesVerify that your environment meets the software and hardware requirements forthe adapter.
Table 1 on page 7 identifies the software and operating system prerequisites for theadapter installation.
Ensure that you install the adapter on the same workstation as the Tivoli DirectoryIntegrator server.
6 Cisco Unified Communications Manager Adapter Installation and Configuration Guide
Table 1. Prerequisites to install the adapter
Prerequisite Description
Directory Integrator v IBM Tivoli® Directory Integrator Version7.1.1 + 7.1.1-TIV-TDI-FP0004 +7.2.0-ISS-SDI-LA0008
v IBM Security Directory Integrator Version7.2
Note:
v Earlier versions of IBM Tivoli DirectoryIntegrator that are still supported mightfunction properly. However, to resolveany communication errors, you mustupgrade your Directory Integrator releaseto the versions that the adapter officiallysupports.
v The adapter supports IBM SecurityDirectory Integrator 7.2, which is availableonly to customers who have the correctentitlement. Contact your IBMrepresentative to find out whether youhave the entitlement to download IBMSecurity Directory Integrator 7.2.
IBM Security Identity server The following servers are supported:
v IBM Security Identity Manager serverVersion 6.0
v IBM Security Identity Manager serverVersion 7.0
v IBM Security Privileged Identity ManagerVersion 2.0
v IBM Security Identity Governance andIntelligence server Version 5.2.2
Cisco Unified Communications Manager Version 6.0.1
System Administrator AuthorityTo complete the adapter installationprocedure, you must have systemadministrator authority.
Tivoli Directory Integrator adapters solutiondirectory
A Tivoli Directory Integrator adapterssolution directory is a Tivoli DirectoryIntegrator work directory for adapters. Seethe Dispatcher Installation and ConfigurationGuide.
For information about the prerequisites and supported operating systems for TivoliDirectory Integrator, see the IBM Tivoli Directory Integrator 7.1: Administrator Guide.
Software downloadsDownload the software through your account at the IBM Passport Advantage®
website.
Go to IBM Passport Advantage.
Chapter 2. Planning 7
See the corresponding IBM Security Identity server Download Document forinstructions.
Note:
You can also obtain additional adapter information from IBM Support.
Installation worksheetThe installation worksheet lists the information that is required to install andconfigure the adapter. Complete this worksheet before you start the installationprocedure for ease of reference. Make a copy of the worksheet for each adapterinstance you install.
Table 2 identifies the information that you need before installing the adapter.
Table 2. Required information to install the adapter
Required information Description Value
Tivoli DirectoryIntegrator HomeDirectory
The ITDI_HOME directory containsthe jars/connectors subdirectory.This subdirectory contains adapterjars.
If Tivoli DirectoryIntegrator is automaticallyinstalled with the IBMSecurity Identity server, thedefault directory path forTivoli Directory Integratoris as follows:
Windows:
v for version 7.1:
drive:\ProgramFiles\IBM\TDI\V7.1
UNIX:
v for version 7.1:
/opt/IBM/TDI/V7.1
Adapters solutiondirectory
This is the default directory. Whenyou install the dispatcher, theadapter prompts you to specify a filepath for the adapter solutiondirectory. For more informationabout the adapter solution directory,see theDispatcher Installation andConfiguration Guide.
Windows:
v for version 7.1:
drive:\ProgramFiles\IBM\TDI\V7.1\timsol
UNIX:
v for version 7.1:
/opt/IBM/TDI/V7.1/timsol
8 Cisco Unified Communications Manager Adapter Installation and Configuration Guide
Chapter 3. Installing
Installing the adapter mainly involves importing the adapter profile and creatingan adapter service. Depending on the adapter, several other tasks can be involvedto completely install it.
All IBM Tivoli Directory Integrator based adapters require the Dispatcher for theadapters to function correctly. If the Dispatcher is installed from a previousinstallation, do not reinstall it unless the Dispatcher is upgraded. See DispatcherInstallation Verification.
Depending on your adapter, the Tivoli Directory Integrator connector mightalready be installed as part of the Tivoli Directory Integrator product and nofurther action is required. If the connector is not pre-installed, install it after theDispatcher.
Installing the dispatcherIf this is the first Tivoli Directory Integrator-based adapter installation, you mustinstall the RMI Dispatcher before you install the adapter. Install the RMIDispatcher on the same Tivoli Directory Integrator server where you want to installthe adapter.
If you already installed the RMI Dispatcher for another adapter, you do not needto reinstall it.
If you have not yet installed the RMI Dispatcher in the Tivoli Directory Integratorenvironment, download the Dispatcher installer from the IBM Passport Advantagewebsite. For more information about the installation, see the Dispatcher Installationand Configuration Guide.
Installing the adapter binaries or connectorThe connector might or might not be available with the base Tivoli DirectoryIntegrator or Security Directory Integrator product. The connector is required toestablish communication between the adapter and the Dispatcher.
Before you beginv The Dispatcher must be installed.
About this task
If you are running on a 64-bit operating system, you must use the Tivoli DirectoryIntegrator-supplied JVM. The JVM is in ITDI_HOME/jvm/jre/bin/, whereITDI_HOME is the directory where Tivoli Directory Integrator is installed.
Procedure1. Create a temporary directory on the workstation where you want to install the
adapter.2. Extract the contents of the compressed file in the temporary directory.3. Install the adapter JAR files. Copy the CiscoUniComMgr.jar file from the
adapter package to the ITDI_HOME/jars/connectors directory.
9
4. Optional: Enable Unicode See the JVM information in the IBM SecurityDispatcher Installation and Configuration Guide.
5. Restart the adapter service.
Verifying the adapter installationTo ensure that the adapter is successfully installed, verify that the adapter JAR fileis in its expected location. Additionally, check for any log errors and verify theversion number of the connector.
Table 3 lists the location where the CiscoUniComMgrConnector.jar file is createdafter you installed the adapter.
Table 3. Operating system and JAR file path
Operating system JAR file path
Windows drive:\Program Files\IBM\TDI\V7.1\jars\connectors\
UNIX /opt/IBM/TDI/V7.1/jars/connectors/
Review the installer log file, CiscoUniComMgrAdapter_Installer.log, that is in theadapter installer directory for any errors.
If this installation is to upgrade a connector, then send a request from SecurityIdentity Manager. Verify that the version number in the ibmdi.log matches theversion of the connector that you installed. The ibmdi.log file is atITDI_Home\adapter solution directory\logs.
Restarting the adapter serviceVarious installation and configuration tasks might require the adapter to berestarted to apply the changes. For example, you must restart the adapter if thereare changes in the adapter profile, connector, or assembly lines. To restart theadapter, restart the Dispatcher.
The adapter does not exist as an independent service or a process. The adapter isadded to the Dispatcher instance, which runs all the adapters that are installed onthe same Security Directory Integrator instance.
See the topic about starting, stopping, and restarting the Dispatcher service in theDispatcher Installation and Configuration Guide.
Importing the adapter profileAn adapter profile defines the types of resources that the IBM Security Identityserver can manage. It is packaged with the IBM Security Identity Adapter. Use theadapter profile to create an adapter service on IBM Security Identity server andestablish communication with the adapter.
Before you beginv The IBM Security Privileged Identity Manager is installed and running.v You have root or administrator authority on the IBM Security Privileged Identity
Manager.v The file to be imported must be a Java archive (JAR) file. The
<Adapter>Profile.jar file includes all the files that are required to define the
10 Cisco Unified Communications Manager Adapter Installation and Configuration Guide
adapter schema, account form, service/target form, and profile properties. Ifnecessary, you can extract the files from the JAR file, modify the files, andrepackage the JAR file with the updated files.The JAR file for IBM SecurityPrivileged Identity Manager is located in the top level folder of the installationpackage.
About this task
Service definition files are also called adapter profile files.
If the adapter profile is not installed correctly, the adapter cannot functioncorrectly. You cannot create a service with the adapter profile or open an accounton the service. You must import the adapter profile again.
Procedure1. Log on to the IBM Security Privileged Identity Manager by using an account
that has the authority to perform administrative tasks.2. From the navigation tree, select Configure System > Manage Service Types.
The Manage Service Types page is displayed.3. On the Manage Service Types page, click Import. The Import Service Type page
is displayed.4. On the Import Service Type page, complete these steps:
a. In the Service Definition File field, type the directory location of the<Adapter>Profile.jar file, or click Browse to locate the file. For example, ifyou are installing the IBM Security Identity Adapter for a Windows serverthat runs Active Directory, locate and import the ADProfileJAR file.
b. Click OK to import the file.
Results
A message indicates that you successfully submitted a request to import a servicetype.
What to do nextv The import occurs asynchronously, which means it might take some time for the
service type to load into the IBM Security Identity server from the propertiesfiles and to be available in other pages. On the Manage Service Types page, clickRefresh to see the new service type. If the service type status is Failed, checkthe log files to determine why the import failed.
v If you receive a schema-related error, see the trace.log file for informationabout it. The trace.log file location is specified by the handler.file.fileDirproperty that is defined in the enRoleLogging.properties file. TheenRoleLogging.properties file is in the IBM Security Identity serverHOME\datadirectory. .
Creating an adapter service/targetAfter you import the adapter profile on the IBM Security Identity server, create aservice/target so that IBM Security Identity server can communicate with themanaged resource.
Before you begin
Complete “Importing the adapter profile” on page 10.
Chapter 3. Installing 11
About this task
You must create an administrative user account for the adapter on the managedresource. You can provide the account information such as administrator name andpassword when you create the adapter service. Ensure that the account hassufficient privileges to administer the users. For information about creating anadministrative account, see the documentation for the managed resource.
To create or change a service, you must use the service form to provideinformation for the service. Service forms might vary depending on the adapter.The service name and description that you provide for each service are displayedon the console. Therefore, it is important to provide values that make sense to yourusers and administrators.
Procedure1. From the navigation tree, click Manage Services.2. On the Services table, click Create. The Create a Service wizard is displayed.3. On the Select the Type of Service page, click Search to locate a business unit.
The Business Unit page is displayed.4. On the Business Unit page, complete these steps:
a. Type information about the business unit in the Search information field.b. Select a business type from the Search by list, and then click Search. A list
of business units that matches the search criteria is displayed.If the table contains multiple pages, you can do the following tasks:v Click the arrow to go to the next page.v Type the number of the page that you want to view and click Go.
c. In the Business Units table, select business unit in which you want to createthe service, and then click OK. The Select the Type of Service page isdisplayed, and the business unit that you specified is displayed in theBusiness unit field.
5. On the Select the Type of Service page, select a service type, and then clickNext.
6. On the Service Information page, specify the appropriate values for the serviceinstance. The content of the Service Information page depends on the type ofservice that you are creating.
7. Click Finish.
Results
A message is displayed, indicating that you successfully created the serviceinstance for a specific service type.
Service/Target form detailsComplete the service/target form fields.
On the Cisco Unified Call Manager Profile tab:
Service Name Specify a name that defines the adapter service on the IBMSecurity Identity server.
Note: Do not use forward (/) or backward slashes (\) in theservice name.
12 Cisco Unified Communications Manager Adapter Installation and Configuration Guide
Description Optional: Specify a description that identifies the service for yourenvironment.
Tivoli Directory Integrator URL
Specify the URL for the IBM Tivoli Directory Integrator instance.The valid syntax for the URL is rmi://ip-address:port/ITDIDispatcher, where ip-address is the IBM Tivoli DirectoryIntegrator host and port is the port number for the RMI Dispatcher.
The default URL for the default SDI1 instance isrmi://localhost:1099/ITDIDispatcher.
On the CiscoUniComMgr Connection tab:
Cisco Server IP AddressSpecify the IP address of the Cisco Unified CommunicationsManager server.
Cisco Server IP PortSpecify the port number of the Cisco Unified CommunicationsManager server.
Administrator NameSpecify the administrator user that is used to log on to the resourceand perform user management operations.
Administrator PasswordSpecify the password for the administrator.
SOAP Server IP Address (If Different From Cisco Server IP Address)Optional: Specify the IP Address of the Cisco UnifiedCommunications Manager SOAP server.
SOAP Server Port (If Different From Cisco Server Port)Optional: Specify the port number of Cisco UnifiedCommunications Manager SOAP server.
On the Dispatcher Attributes tab:
Disable AL CachingSelect the check box to disable the assembly line (test, add, modify,delete) caching in the dispatcher for the service.
AL FileSystem PathSpecify the file path from where the dispatcher loads the assemblylines. If you do not specify a file path, the dispatcher loads theassembly lines received from IBM Security Identity server. Forexample, you can specify the following file path to load theassembly lines from the profiles directory of the Windowsoperating system: c:\Files\IBM\TDI\V7.1\profiles or you canspecify the following file path to load the assembly lines from theprofiles directory of the UNIX and Linux operating:system:/opt/IBM/TDI/V7.1/profiles
Max Connection CountSpecify the maximum number of assembly lines that the dispatchercan run simultaneously for the service. For example, enter 10 whenyou want the dispatcher to run maximum 10 assembly linessimultaneously for the service. If you enter 0 in the MaxConnection Count field, the dispatcher does not limit the numberof assembly line that run simultaneously for the service.
Chapter 3. Installing 13
On the Status and information tabThis page contains read only information about the adapter and managedresource. These fields are examples. The actual fields vary depending onthe type of adapter and how the service form is configured. The adaptermust be running to obtain the information. Click Test Connection topopulate the fields.
Last status update: DateSpecifies the most recent date when the Status and information tabwas updated.
Last status update: TimeSpecifies the most recent time of the date when the Status andinformation tab was updated.
Managed resource status Specifies the status of the managed resource that the adapter isconnected to.
Adapter version Specifies the version of the adapter that the service uses toprovision request to the managed resource.
Profile version Specifies the version of the profile that is installed in the IBMSecurity Identity server.
TDI version Specifies the version of the Tivoli Directory Integrator on which theadapter is deployed.
Dispatcher version Specifies the version of the Dispatcher.
Installation platformSpecifies summary information about the operating system wherethe adapter is installed.
Adapter account Specifies the account that running the adapter binary file.
Adapter up time: Date Specifies the date when the adapter started.
Adapter up time: Time Specifies the time of the date when the adapter started.
Adapter memory usage Specifies the memory usage for running the adapter.
If the connection fails, follow the instructions in the error message. Alsov Verify the adapter log to ensure that the test request was successfully
sent to the adapter.v Verify the adapter configuration information.v Verify service parameters for the adapter profile. For example, verify the
work station name or the IP address of the managed resource and theport.
14 Cisco Unified Communications Manager Adapter Installation and Configuration Guide
Verifying that the adapter is working correctlyAfter you install and configure the adapter, verify that the installation andconfiguration are correct.
Procedure1. Test the connection for the service that you created on the IBM Security Identity
server.2. Run a full reconciliation from the IBM Security Identity server.3. Run all supported operations such as add, modify, and delete on one user
account.4. Verify the ibmdi.log file after each operation to ensure that no errors are
reported.5. Verify the trace.log file to ensure that no errors are reported when you run an
adapter operation.
Chapter 3. Installing 15
16 Cisco Unified Communications Manager Adapter Installation and Configuration Guide
Chapter 4. Upgrading
Upgrading an IBM Tivoli Directory Integrator-based adapter involves tasks such asupgrading the dispatcher, the connector, and the adapter profile. Depending on theadapter, some of these tasks might not be applicable. Other tasks might also berequired to complete the upgrade.
Upgrading the adapter binaries or connectorUpgrading the adapter involves tasks such as upgrading the connector.
Before you upgrade the connector, verify the version of the connector.v If the connector version mentioned in the release notes is later than the existing
version on your workstation, install the connector.v If the connector version mentioned in the release notes is the same or earlier
than the existing version, do not install the connector.
Note: Stop the dispatcher service before the upgrading the connector and start itagain after the upgrade is complete.
Upgrading the adapter profileUpgrading the adapter involves tasks such as upgrading the existing adapterprofile.
Read the adapter release notes for any specific instructions before importing a newadapter profile on Security Identity Manager
See Importing the adapter profile.
Note: Restart the dispatcher service after importing the profile. Restarting thedispatcher clears the assembly lines cache and ensures that the dispatcher runs theassembly lines from the updated adapter profile.
17
18 Cisco Unified Communications Manager Adapter Installation and Configuration Guide
Chapter 5. Configuring
After you install the adapter, configure it to function correctly. Configuration isbased on your requirements or preference.
The configuration of the Cisco Unified Communications Manager Adapter involvesprofile customization, password management, and configuring settings for JVM,dispatcher information, logon and SSL communication.v “Customizing the adapter profile”v “Editing the adapter profile on the UNIX or Linux operating system” on page 20v “Password management for account restoration” on page 21
See the IBM Security Dispatcher Installation and Configuration Guide for additionalconfiguration options such as:v JVM propertiesv Dispatcher filteringv Dispatcher propertiesv Dispatcher port numberv Logging configurationsv Secure Sockets Layer (SSL) communication
Customizing the adapter profileTo customize the Cisco Unified Communications Manager Adapter profile, youmust modify the Cisco Unified Communications Manager Adapter JAR file.
About this task
You can customize the adapter profile to change the account form or the serviceform. You can also change the labels on the forms by using the Form Designer orCustomLabels.properties. Each adapter has a CustomLabels.properties file forthat adapter.
Note: You cannot modify the schema of the Cisco Unified CommunicationsManager Adapter.
The JAR file is included in the Cisco Unified Communications Manager Adaptercompressed file that you downloaded from the IBM website.
The following files are included in the Cisco Unified Communications ManagerAdapter JAR file:v CiscoUniComMgrAdapter.xmlv CiscoUniComMgrAdd.xmlv CiscoUniComMgrDelete.xmlv CiscoUniComMgrModify.xmlv CiscoUniComMgrSearch.xmlv CiscoUniComMgrTest.xmlv CustomLabels.properties
19
v erCiscoUniComMgrAccount.xmlv erCiscoUniComMgrRMIservice.xmlv schema.dsmlv service.def
To edit the JAR file, complete these steps:1. Log on to the workstation where the Cisco Unified Communications Manager
Adapter is installed.2. Copy the JAR file into a temporary directory.3. Extract the contents of the JAR file into the temporary directory by running the
following command:#cd /tmp#jar -xvf CiscoUniComMgrProfile.jar
The jar command extracts the files into the CiscoUniComMgrProfile directory.4. Edit the file that you want to change.
After you edit the file, you must import the file into the Security Identity Managerserver for the changes to take effect.
To import the file, complete these steps:1. Create a JAR file by using the files in the /tmp directory by running the
following commands:#cd /tmp#jar -cvf CiscoUniComMgrProfile.jar CiscoUniComMgrProfile
2. Import the JAR file into the Security Identity Manager application server. Formore information about importing the JAR file, see Importing the adapterprofile.
3. Stop and start the Security Identity Manager server.4. Stop and start the Cisco Unified Communications Manager Adapter service. See
Start, stop, and restart the adapter service for information about starting,stopping, and restarting the Cisco Unified Communications Manager Adapterservice.
Editing the adapter profile on the UNIX or Linux operating systemThe adapter profile .jar file might contain ASCII files that are created by using theMS-DOS ASCII format.
About this task
If you edit an MS-DOS ASCII file on the UNIX operating system, you might see acharacter ^M at the end of each line. These characters indicate new lines of text inMS-DOS. The characters can interfere with the running of the file on UNIX orLinux systems. You can use tools, such as dos2unix, to remove the ^M characters.You can also use text editors, such as the vi editor, to remove the charactersmanually.
Example
You can use the vi editor to remove the ^M characters. From the vi commandmode, run the following command and press Enter::%s/^M//g
20 Cisco Unified Communications Manager Adapter Installation and Configuration Guide
When you use this command, enter ^M or Ctrl-M by pressing ^v^M or Ctrl V CtrlM sequentially. The ^v instructs the vi editor to use the next keystroke instead ofissuing it as a command.
Password management for account restorationWhen an account is restored from being previously suspended, you are notprompted to supply a new password for the reinstated account. However, in somecases you might want to be prompted for a password.
The password requirement to restore an account falls into two categories: allowedand required.
How each restore action interacts with its corresponding managed resourcedepends on either the managed resource, or the business processes that youimplement. Certain resources reject a password when a request is made to restorean account. In this case, you can configure IBM Security Privileged IdentityManager to forego the new password requirement. , Your company might have abusiness process that dictates that the account restoration process must beaccompanied by resetting the password. If so, you can set the Cisco UnifiedCommunications Manager Adapter to require a new password when the account isrestored
In the service.def file, you can define whether a password is required as a newprotocol option. When you import the adapter profile, if an option is not specified,the adapter profile importer determines the correct restoration password behaviorfrom the schema.dsml file. Adapter profile components also enable remote servicesto determine if you discard a password that is entered by the user in a situationwhere multiple accounts on disparate resources are being restored. In thissituation, only some of the accounts might require a password. Remote servicesdiscard the password from the restore action for those managed resources that donot require them.
Edit the service.def file to add the new protocol options, for example:<Property Name = "com.ibm.itim.remoteservices.ResourceProperties.
PASSWORD_NOT_REQUIRED_ON_RESTORE"<value>false</value></property><Property Name = "com.ibm.itim.remoteservices.ResourceProperties.
PASSWORD_NOT_ALLOWED_ON_RESTORE"<value>false</value></property>
By adding the two options in the example above, you are ensuring that you areprompted for a password when an account is restored.
Note: The Cisco Unified Communications Manager Adapter does not supportsuspend operations or restore operations. There is no provision on the CiscoUnified Communications Manager server to suspend an account.
Enabling SSL communicationYou must configure Secure Sockets Layer (SSL) communication between theadapters that are based on Tivoli Directory Integrator and the WebSphere®
Application Server.
You can configure the Tivoli Directory Integrator to use SSL and also configureWebSphere with the default keystore and default truststore. For more information
Chapter 5. Configuring 21
about WebSphere SSL configuration, see the WebSphere online help from theWebSphere Application Server Administrative Console.
SSL terminology for adaptersThere are several SSL terms that apply to adapters.
SSL serverThe workstation on which the Tivoli Directory Integrator is installed is theSSL server. It listens for connection requests.
SSL clientThe workstation on which the IBM Security Identity server and WebSphereApplication Server are installed. The client submits connection requests tothe Tivoli Directory Integrator.
Signed certificatesAn industry-standard method of verifying the authenticity of an entity,such as a server, a client, or an application. Signed certificates are issued bya third-party certificate authority for a fee. Some utilities, such as theiKeyman utility can also issue signed certificates. Use a certificate authority(CA) certificate to verify the origin of a signed digital certificate.
Signer certificates (CA certificates)When an application receives the signed certificate of another application,the application uses a CA certificate to verify the originator of thecertificate. You can configure many applications. For example, you canconfigure web browsers with the CA certificates of well-known certificateauthorities. This type of configuration can eliminate or reduce the task ofdistributing CA certificates across the security zones in a network.
Self-signed certificatesA self-signed certificate contains information about the owner of thecertificate and the signature of the owner. You can also use a signedcertificate as a CA certificate. To use self-signed certificates, you mustextract the CA certificate to configure SSL.
SSL keystoreA key database file that is designated as a keystore. The file contains theSSL certificate.
Note: You can use a keystore and truststore as the same physical file.
SSL truststoreA key database file that is designated as a truststore. The SSL truststorecontains the list of signer certificates (CA certificates) that define, whichcertificates the SSL protocol trusts. Only a certificate that is issued by oneof the listed trusted signers is accepted.
Note: You can use a keystore and truststore as the same physical file.
One-way SSL communicationFor one-way SSL communication, you must have a:v Keystore and a certificate on the SSL server (the Tivoli Directory
Integrator server)v Truststore on the SSL client-side (the IBM Security Identity server)
Two-way SSL communication For two-way SSL (client-side) communication, you must have a:v Keystore with a certificate
22 Cisco Unified Communications Manager Adapter Installation and Configuration Guide
v Truststore that contains the signer certificate that issued the certificatefrom the other side.
You require the keystore and the truststore on the SSL server and the SSLclient-side.
Configuring certificates for SSL authenticationConfiguring communication between an SSL server and client can use one-way ortwo-way SSL authentication.
For the following tasks, the SSL client is the computer on which the IBM SecurityIdentity server is installed, and the SSL server is theTivoli Directory Integrator.
Configuring SSL for one-way SSL communicationUse one-way SSL communication when the client must authenticate the server.
About this task
One-way authentication requires a truststore on the client and a keystore on theserver. In this example, CA certificate "A" exists in the truststore on the SSL clientand also in the keystore on the SSL server. The client sends a request to the SSLserver. The SSL server sends Certificate A from the keystore to the client. The clientvalidates Certificate A against the certificates that are contained in the truststore. Ifthe certificate is found in the truststore, the client accepts communication from theSSL server.
The following figure describes SSL configuration for one-way SSL communication.
Note: IBM Security Identity server uses the existing truststore of theWebSphereApplication Server.
Procedure1. Create a keystore for the Tivoli Directory Integrator server.2. Create a truststore for the Tivoli Directory Integrator server. One-way SSL
communication on the Tivoli Directory Integrator server does not require thetruststore. However, you must configure the truststore for the Remote MethodInvocation (RMI) SSL initialization.
3. Create a server-signed certificate for the Tivoli Directory Integrator server.4. Create a CA certificate for the Tivoli Directory Integrator server.5. Import the Tivoli Directory Integrator CA certificate in the WebSphere
Application Server truststore.
KeystoreTruststore
CA certificate "A" Certificate “A”
IBM Security IdentityManager (SSL client)
Tivoli DirectoryIntegrator (SSL server)
Figure 4. One-way SSL communication (server communication)
Chapter 5. Configuring 23
Note: You can modify the solution.properties file for steps 6, 7, and 8 in asingle operation. When you do so, do not stop and restart the adapter serviceat the end of steps 6 and 7.
6. Configure the Tivoli Directory Integrator to use keystores.7. Configure the Tivoli Directory Integrator to use truststores.8. Enable the adapter service to use SSL.9. Stop and restart the adapter service.
10. Stop and restart WebSphere Application Server.
Configuring SSL for two-way SSL communicationUse two-way SSL communication when the client must authenticate the server andthe server must authenticate the client.
About this task
Two-way authentication requires a truststore and a keystore on both the client andthe server. In this example, CA certificate "A" exists in the truststore and a CAcertificate "B" in the keystore of the client. CA certificate "B" exists in the truststoreand a CA certificate "A" in the keystore of the server. The client sends a request tothe SSL server. The SSL server sends Certificate A from the keystore to the client.The client validates Certificate A against the certificates that are contained in thetruststore.
If the certificate is found in the truststore, the client accepts communication fromthe SSL server. The server sends an authentication request to the client. The clientsends Certificate B from the keystore to the server. The server validates CertificateB against the certificates that are contained in the truststore. If the certificate isfound in the truststore, the server accepts communication from the client.
The following figure describes SSL configuration for two-way SSL communication.
Note: IBM Security Identity server uses the existing truststore and keystore oftheWebSphere Application Server.
IBM Security IdentifyManager (SSL client)
Truststore
CA certificate “A”
Keystore
Certificate “B”
Tivoli DirectoryIntegrator (SSL server)
Truststore
CA certificate “B”
Keystore
Certificate “A”
Figure 5. Two-way SSL communication (client communication)
24 Cisco Unified Communications Manager Adapter Installation and Configuration Guide
Procedure
To configure two-way SSL, do the following tasks:1. Create a keystore for the Tivoli Directory Integrator server.2. Create a truststore for the Tivoli Directory Integrator server. Do not do this
task if you use the same file for keystore and truststore.3. Create a server-signed certificate for the Tivoli Directory Integrator server.4. Create a CA certificate for the Tivoli Directory Integrator server.5. Import the Tivoli Directory Integrator CA certificate in the WebSphere
Application Server truststore.
Note: You can modify the solution.properties file for steps 6, 7, and 8 in asingle operation. When you do so, do not stop and restart the adapter serviceat the end of steps 6 and 7.
6. Configure the Tivoli Directory Integrator to use keystores.7. Configure the Tivoli Directory Integrator to use truststores.8. Enable the adapter service to use SSL.9. Create a certificate for the IBM Security Identity server.
10. Create a CA certificate for IBM Security Identity server.11. Import the WebSphere Application Server CA Certificate in Tivoli Directory
Integrator truststore.12. Stop and restart the adapter service.13. Stop and restart WebSphere Application Server.
Tasks done on the SSL serverYou can configure the Tivoli Directory Integrator as the SSL server.
Complete all tasks on the Tivoli Directory Integrator server workstation.
Note: File names such as tdikeys.jks and locations such as ITDI_HOME\keys areexamples. Actual file names and locations might differ.
Creating a keystore for the Tivoli Directory Integrator serverYou must create a keystore to hold the certificates that the SSL server uses toauthenticate itself to clients.
About this task
A keystore is a database of private keys and the associated certificates thatauthenticate the corresponding public keys. Digital certificates are stored in akeystore file. A keystore also manages certificates from trusted entities.
Procedure1. Navigate to the ITDI_HOME\jvm\jre\bin directory.2. Start the ikeyman.exe file (for Windows operating systems) or ikeyman (for
UNIX and Linux operating systems).3. From the Key Database File menu, select New.4. Select the key database type of JKS.5. Type the keystore file name. For example, type tdikeys.jks.6. Type the location. For example, type .
Chapter 5. Configuring 25
Note: Ensure that location that you specify exists.7. Click OK.8. Type a password for the keystore. The default password is secret.9. Click OK.
Creating a truststore for the Tivoli Directory Integrator serverYou must create a truststore on the SSL server to hold trusted certificates, so thatclients can authenticate to the server.
About this task
A truststore is a database of public keys for target servers. The SSL truststorecontains the list of signer certificates (CA certificates) that define which certificatesthe SSL protocol trusts. Only a certificate that is issued by one of these listedtrusted signers can be accepted. Do not do the following task if you use the samefile for keystore and truststore.
Procedure1. Navigate to the ITDI_HOME\jvm\jre\bin directory.2. Start the ikeyman.exe file (for Windows operating systems) or ikeyman (for
UNIX and Linux operating systems).3. From the Key Database File menu, select New.4. Select JKS.5. Type the keystore file name. For example, type tdikeys.jks.6. Type the location. For example, type .
Note: Ensure that location that you specify exists.7. Click OK.8. Type a password for the keystore. The default password is secret.9. Click OK.
Creating a self-signed certificate for the Tivoli DirectoryIntegrator serverA self-signed certificate contains information about the owner of the certificate andthe signature of the owner. This type of certificate is typically used in a testingenvironment.
About this task
A self-signed certificate is a signed certificate and also a CA certificate. To useself-signed certificates, you must extract the CA certificate from the self-signedcertificate to configure SSL. You can purchase a certificate from a well-knownauthority, such as VeriSign. You can also use a certificate server, such as the oneincluded with the MicrosoftWindows 2003 Advanced Server, to generate your owncertificates.
Procedure1. Navigate to the ITDI_HOME\jvm\jre\bin directory.2. Start the ikeyman.exe file (for Windows operating system) or ikeyman (for
UNIX and Linux operating systems).3. From the Key Database File menu, select Open.
26 Cisco Unified Communications Manager Adapter Installation and Configuration Guide
4. Navigate to the keystore file that was created previously:ITDI_HOME\keys\tdikeys.jks.
5. Enter the keystore password. The default password is secret.6. Select Create > New Self Signed certificate.7. Set the Key Label to tdiserver.8. Use your system name (DNS name) as the Common Name (workstation
name).9. Enter the name of your organization. For example, enter IBM.
10. Click OK.
Extracting a CA certificate for the Tivoli Directory IntegratorUse a CA certificate to verify the origin of a signed digital certificate.
About this task
When an application receives signed certificate of another application, it uses a CAcertificate to verify the originator of the certificate. You can configure manyapplications. For example, you can configure web browsers with the CA certificatesof well-known certificate authorities. This type of configuration can eliminate orreduce the task of distributing CA certificates across the security zones in anetwork.
Procedure1. Navigate to the ITDI_HOME\jvm\jre\bin directory.2. Launch the ikeyman.exe file (for Windows operating system) or ikeyman (for
UNIX and Linux operating system).3. From the Key Database File menu, select Open.4. Navigate to the keystore file that was created previously:
ITDI_HOME\keys\tdikeys.jks
5. Enter the keystore password. The default password is secret.6. Extract the Server certificate for client use by selecting Extract Certificate.7. Select Binary DER data as the data type.8. Enter the certificate file name: idiserver.der.9. Enter the location as ITDI_HOME\keys.
10. Click OK.11. Copy the idiserver.der certificate file to the workstation on which IBM
Security Identity server is installed.
Importing the WebSphere CA certificate in the Tivoli DirectoryIntegrator truststoreIBM Security Identity server uses the WebSphere CA certificate, to authenticate tothe Tivoli Directory Integrator.
About this task
After you extract the WebSphere CA certificate, you must import it into the TivoliDirectory Integrator truststore. After it is stored in the truststore, the SSL server canrecognize the credentials of the client and authenticate the client.
Procedure1. Navigate to the ITDI_HOME\jvm\jre\bin directory.
Chapter 5. Configuring 27
2. Start the ikeyman.exe file (Windows operating system) or ikeyman (UNIX andLinux operating system).
3. From the Key Database File menu, select Open.4. Select JKS.5. Type the keystore file name: tditrust.jks.6. Type the location: ITDI_HOME\keys and click OK.7. Click Signer Certificates in the dropdown menu and click Add.8. Select Binary DER data as the data type.9. Use Browse to select the timclient.der file that is stored in ITDI_HOME\keys
directory.10. Use timclient as the label.11. Click OK to continue.
Configuring the Tivoli Directory Integrator to use the keystoresYou can configure the Tivoli Directory Integrator properties file to use keystores.
Procedure1. Navigate to the ITDI_HOME\timsol directory.2. Open the Tivoli Directory Integrator solution.properties file in an editor.3. Edit the following lines under client authentication:
javax.net.ssl.keyStore=ITDI_HOME\keys\tdikeys.jks{protect}-javax.net.ssl.keyStorePassword=secretjavax.net.ssl.keyStoreType=JKS
a. Uncomment them, if necessary.b. Set the location, password, and type of keystore to match the keystore you
created.4. Save your changes.5. Stop and restart the adapter service.
Note: You can modify the solution.properties file in a single operation. Donot stop and restart the adapter service after you configure the Tivoli DirectoryIntegrator to use the keystores and truststores. You can stop and restart theadapter after you enable the adapter service to use SSL.
Configuring Tivoli Directory Integrator to use the truststoresYou can configure the Tivoli Directory Integrator properties file to use truststores.
Procedure1. Navigate to the ITDI_HOME\timsol directory.2. Open the Tivoli Directory Integrator solution.properties file in an editor.3. Edit the following lines under client authentication:
javax.net.ssl.trustStore=ITDI_HOME\keys\tditrust.jks{protect}-javax.net.ssl.trustStorePassword=secretjavax.net.ssl.trustStoreType=JKS
a. Uncomment them, if necessary.b. Set the location, password, and type of keystore to match the keystore you
created.4. Save your changes.5. Stop and restart the adapter service.
28 Cisco Unified Communications Manager Adapter Installation and Configuration Guide
Note: You can modify the solution.properties file in a single operation. Donot stop and restart the adapter service after you configure the Tivoli DirectoryIntegrator to use the keystores and truststores. You can stop and restart theadapter after you enable the adapter service to use SSL.
Enabling the adapter service to use SSLYou can configure the Tivoli Directory Integrator properties file to enable theadapter service to use SSL.
Procedure1. Navigate to the ITDI_HOME\timsol directory.2. Open the Tivoli Directory Integrator solution.properties file in an editor.3. Edit the following two lines, which depend on the type of secure
communications you want to use.
For no SSLcom.ibm.di.dispatcher.ssl=falsecom.ibm.di.dispatcher.ssl.clientAuth=false
For one-way SSLcom.ibm.di.dispatcher.ssl=truecom.ibm.di.dispatcher.ssl.clientAuth=false
For two-way SSLcom.ibm.di.dispatcher.ssl=truecom.ibm.di.dispatcher.ssl.clientAuth=true
4. Save your changes.5. Stop and restart the adapter service.
Tasks performed on the SSL client (IBM Security IdentityManager and WebSphere Application Server workstation)
You must do several tasks to establish SSL communication between IBM SecurityIdentity Manager and Tivoli Directory Integrator.
Procedure
Perform the following tasks on the server workstation on which IBM(r) SecurityIdentity Manager and Websphere Application Server are installed:1. “Configuring certificates for SSL authentication” on page 232. “Creating a signed certificate for the IBM Security Identity Manager server”3. “Extracting a WebSphere Application Server CA certificate for IBM Security
Identity Manager” on page 304. “Importing the IBM Security Identity Manager CA certificate in the WebSphere
Application Server truststore” on page 30
Creating a signed certificate for the IBM Security IdentityManager serverYou can use a well-known authority or your own certificate server to generate acertificate.
About this task
In this case, use the Personal certificates requests option to produce a certificaterequest to send to the well-known authority or to your certificate server. You canuse the Accept option under Personal certificates to load the data sent by the
Chapter 5. Configuring 29
certificate authority in response to the request.
Procedure1. Connect to the WebSphere Application Server Administrative Console.2. Navigate to Security > SSL certificate and key management > Keystores and
certificates.3. Select NodeDefaultKeyStore.4. Select Personal certificates.5. Select Create a self-signed certificate.6. Set appropriate values for the certificate fields:
a. Set the Alias to timclient.b. Use your system name (DNS name) as the Common Name (workstation
name).c. Enter the name of your organization. For example, enter IBM.
7. Click OK and save.8. Extract the CA certificate from the self-signed certificate.
Extracting a WebSphere Application Server CA certificate for IBMSecurity Identity ManagerTo establish a secure communication between IBM Security Identity server and theadapter you must extract a WebSphere Application Server CA certificate for IBMSecurity Identity server.
Procedure1. Connect to the WebSphere Application Server Administrative Console.2. Navigate to Security > SSL certificate and key management > Keystores and
certificates.3. Select NodeDefaultKeyStore.4. Select Personal certificates.5. Select the check box against the certificate that you created and select Extract.6. Enter a file name: C:\keys\timclient.der.7. Select Binary DER data as the data type.8. Click OK.
Importing the IBM Security Identity Manager CA certificate in theWebSphere Application Server truststoreAfter you create a WebSphere Application Server CA certificate for IBM SecurityIdentity Manager, you must import the IBM Security Identity Manager CAcertificate in the WebSphere Application Server truststore.
Procedure1. Copy the SSL server CA certificate file, idiserver.der, to the C:\keys directory
on the workstation on which IBM Security Identity Manager is installed.2. Connect to the WebSphere Application Server Administrative Console.3. Navigate to Security > SSL certificate and key management > Keystores and
certificates.4. Select NodeDefaultTrustStore.5. Select Signer certificates.6. Click Add.
a. Set the Alias to idiserver.
30 Cisco Unified Communications Manager Adapter Installation and Configuration Guide
b. Specify the file name of the exported Tivoli Directory Integrator servercertificate: C:\ keys\idiserver.der.
c. Select Binary DER data as the data type.7. Click OK to continue and save.
Chapter 5. Configuring 31
32 Cisco Unified Communications Manager Adapter Installation and Configuration Guide
Chapter 6. Troubleshooting
Troubleshooting is a systematic approach to solving a problem. The goal oftroubleshooting is to determine why something does not work as expected andhow to resolve the problem. This topic provides information and techniques foridentifying and resolving problems that are related to the adapter, includingtroubleshooting errors that might occur during the adapter installation.
Techniques for troubleshooting problemsCertain common techniques can help with the task of troubleshooting. The firststep in the troubleshooting process is to describe the problem completely.
Problem descriptions help you and the IBM technical-support representative findthe cause of the problem. This step includes asking yourself basic questions:v What are the symptoms of the problem?v Where does the problem occur?v When does the problem occur?v Under which conditions does the problem occur?v Can the problem be reproduced?
The answers to these questions typically lead to a good description of the problem,which can then lead you to a problem resolution.
What are the symptoms of the problem?
When you start to describe a problem, the most obvious question is “What is theproblem?” This question might seem straightforward; however, you can break itdown into several more-focused questions that create a more descriptive picture ofthe problem. These questions can include:v Who, or what, is reporting the problem?v What are the error codes and messages?v How does the system fail? For example, is it a loop, hang, crash, performance
degradation, or incorrect result?
Where does the problem occur?
Determining where the problem originates is not always easy, but it is one of themost important steps in resolving a problem. Many layers of technology can existbetween the reporting and failing components. Networks, disks, and drivers areonly a few of the components to consider when you are investigating problems.
The following questions help you to focus on where the problem occurs to isolatethe problem layer:v Is the problem specific to one operating system, or is it common across multiple
operating systems?v Is the current environment and configuration supported?v Do all users have the problem?v (For multi-site installations.) Do all sites have the problem?
33
If one layer reports the problem, the problem does not necessarily originate in thatlayer. Part of identifying where a problem originates is understanding theenvironment in which it exists. Take some time to completely describe the problemenvironment, including the operating system and version, all correspondingsoftware and versions, and hardware information. Confirm that you are runningwithin an environment that is a supported configuration. Many problems can betraced back to incompatible levels of software that are not intended to run togetheror are not fully tested together.
When does the problem occur?
Develop a detailed timeline of events that lead up to a failure, especially for thosecases that are one-time occurrences. You can most easily develop a timeline byworking backward: Start at the time an error was reported (as precisely as possible,even down to the millisecond), and work backward through the available logs andinformation. Typically, you use the first suspicious event that you find in adiagnostic log.
To develop a detailed timeline of events, answer these questions:v Does the problem happen only at a certain time of day or night?v How often does the problem happen?v What sequence of events leads up to the time that the problem is reported?v Does the problem happen after an environment change, such as upgrading or
installing software or hardware?
Responding to these types of questions can give you a frame of reference in whichto investigate the problem.
Under which conditions does the problem occur?
Knowing which systems and applications are running at the time that a problemoccurs is an important part of troubleshooting. These questions about yourenvironment can help you to identify the root cause of the problem:v Does the problem always occur when the same task is being done?v Is a certain sequence of events required for the problem to occur?v Do any other applications fail at the same time?
Answering these types of questions can help you explain the environment inwhich the problem occurs and correlate any dependencies. Remember that justbecause multiple problems might occur around the same time, the problems arenot necessarily related.
Can the problem be reproduced?
From a troubleshooting standpoint, the ideal problem is one that can bereproduced. Typically, when a problem can be reproduced you have a larger set oftools or procedures at your disposal to help you investigate. Problems that you canreproduce are often easier to debug and solve.
However, problems that you can reproduce can have a disadvantage: If theproblem is of significant business impact, you do not want it to recur. If possible,re-create the problem in a test or development environment, which typically offersyou more flexibility and control during your investigation.v Can the problem be re-created on a test system?
34 Cisco Unified Communications Manager Adapter Installation and Configuration Guide
v Do multiple users or applications have the same type of problem?v Can the problem be re-created by running a single command, a set of
commands, or a particular application?
Error messages and problem solvingA warning or error message might be displayed in the user interface to provideinformation about the adapter or when an error occurs.
Table 4 contains warnings or errors that might be displayed on the user interface.
Table 4. Messages and corrective action
Message number Message Corrective action
CTGIMT001E The following error occurred.
Either the Cisco UnifiedCommunications Manager servicename is incorrect or the service isnot up.
Ensure that service name given on Tivoli IdentityManager service form is running.
CTGIMT001E The following error occurred.
Either the Cisco UnifiedCommunications Manager host orport is incorrect.
Verify that the host workstation name and the port forCisco Unified Communications Manager server arecorrectly specified.
CTGIMT002E The login credential is missing orincorrect. Verify that login credential specified on service form is
correct.
CTGIMT003E The account already exists. The user has already been added to the resource. Thiserror might occur if you are attempting to add a user tothe managed resource and Tivoli Identity Manager is notsynchronized with the resource. To fix this problem,schedule a reconciliation between Tivoli IdentityManager and the resource. See the online help forinformation about scheduling a reconciliation.
CTGIMT006E An error occurred while establishingcommunication with the IBM TivoliDirectory Integrator server.
v Verify that the Tivoli Directory Integrator-BasedAdapter Service is running.
v Verify that the Web address specified on the serviceform for Tivoli Directory Integrator is correct.
CTGIMT009E The account username cannot bemodified because it does not exist.
This error might occur when you attempt to modify auser. This error might also occur if you attempt tochange the password for a user. To fix the problem,ensure that:
v The location specified for the managed resource iscorrect.
v The user was created on the resource.
v The user was not deleted from the resource.
v If the user does not exist on the resource, create theuser on the resource and then schedule areconciliation. See the online help for informationabout scheduling a reconciliation.
Chapter 6. Troubleshooting 35
Table 4. Messages and corrective action (continued)
Message number Message Corrective action
CTGIMT015E An error occurred while deleting theusername account because theaccount does not exist.
This error might occur when you attempt to delete auser. This error might also occur if you attempt tochange the password for a user. To fix the problem,ensure that:
v The location specified for the managed resource iscorrect.
v The user was created on the resource.
v The user was not deleted from the resource.
v If the user does not exist on the resource, no action isnecessary.
36 Cisco Unified Communications Manager Adapter Installation and Configuration Guide
Chapter 7. Uninstalling
To remove an adapter from the IBM Security Identity server for any reason, youmust remove all the components that were added during installation. Uninstallingan IBM Tivoli Directory Integrator based adapter mainly involves removing theconnector file, and the adapter profile from the IBM Security Identity server.Depending on the adapter, some of these tasks might not be applicable, or therecan be other tasks.
About this task
Removing the adapter binaries or connectorRemove the Tivoli Directory Integrator Cisco Unified Communications Managerconnector to uninstall the adapter from the Tivoli Directory Integrator.
About this task
To remove the Cisco Unified Communications Manager Adapter, complete thesesteps:
Procedure1. Stop the Dispatcher service.2. Remove the CiscoUniComMgr.jar file from the ITDI_HOME/jars/connectors
directory.3. Start the Dispatcher service.
Deleting the adapter profileRemove the adapter service/target type from the IBM Security Identity server.Before you delete the adapter profile, ensure that no objects exist on the IBMSecurity Identity server that reference the adapter profile.
Objects on the IBM Security Identity server that can reference the adapter profile:v Adapter service instancesv Policies referencing an adapter instance or the profilev Accounts
Note: The Dispatcher component must be installed on your system for adapters tofunction correctly in a Tivoli Directory Integrator environment. When you deletethe adapter profile, do not uninstall the Dispatcher.
For specific information about how to delete the adapter profile, see the IBMSecurity Privileged Identity Manager product documentation.
37
38 Cisco Unified Communications Manager Adapter Installation and Configuration Guide
Chapter 8. Reference
Reference information is organized to help you locate particular facts quickly, suchas adapter attributes, registry settings, and environment variables.
Adapter attributes and object classesAdapter attributes and object classes are required for customization, creatingprovisioning rules, and understanding what service/target attributes are supportedby the adapter. The IBM Security Identity server communicates with the adapterby using attributes, which are included in transmission packets that are sent over anetwork.This topic is not applicable for this adapter.
The combination of attributes, included in the packets, depends on the type ofaction that the IBM Security Identity server requests from the adapter.
Table 5 lists the attributes that are used by the adapter. The table gives a briefdescription, constraints, and permissions.
Use the following keys for the permissions column:R = Read onlyRW = Add, read, modify, writeAR = Add, Read
Table 5. Required attributes for the erCUCMAccount object class
Attribute name and descriptionDatatype
Singlevalued
Permissions Constraints
Attribute name on CUCMserver
eruid
Specifies the user login ID.
String Yes AR Maximumlength is128characters
User ID
sn
Specifies the last name of the user.
String No RW Maximumlength is 64characters
Last Name
Table 6. Optional attributes for the erCUCMAccount object class
Attribute name and descriptionDatatype
Singlevalued
Permissions Constraints
Attribute name on CUCMserver
erPassword
Specifies the password of the user.
String Yes RW Maximumlength is 128characters
Password
givenname
Specifies the first name of the user.
String No RW Maximumlength is 64characters
First Name
erCUCMPwdPin
Specifies the PIN associated with theuser.
Integer Yes RW Mustcontain 1-127numericcharacters
Pin
39
Table 6. Optional attributes for the erCUCMAccount object class (continued)
Attribute name and descriptionDatatype
Singlevalued
Permissions Constraints
Attribute name on CUCMserver
erCUCMTelePhoneNumber
Specifies the telephone number of theuser.
String Yes RW Maximumlength is 64characters
Telephone Number
erCUCMDepartment
Specifies the department of the user.
String Yes RW Maximumlength is 64characters
Department
erCUCMManagerId
Specifies the manager of the user.
String Yes RW Maximumlength is 128characters
Manager ID
erCUCMUserLocale
Specifies the locale of the user.
String Yes RW NA User Locale
erCUCMAssociatedPC
Specifies the PC associated with theuser.
String Yes RW Maximumlength is 51characters
Associated PC
erCUCMPwdDigestCredentials
Specifies the digest credentials of theuser.
String Yes RW Maximumlength is 31characters
Digest Credentials
erCUCMLineName
Specifies the primary extensionassociated with the user.
String Yes RW Must not benull inmodifyoperation
Primary Extension
erCUCMEnabMobility
Specifies the mobility of the user.
Boolean Yes RW NA Enable Mobility
erCUCMEnabMobVoiceAccess
Specifies whether the Mobile VoiceAccess is enabled for the user.
Boolean Yes RW NA Enable Mobile Voice Access
erCUCMMaxWaitTimeForDeskPickup
Specifies the maximum time to waitfor the desk phone to pick up.
Integer Yes RW Must be aNumber inthe range of0 - 30000milliseconds
Maximum Wait Time for DeskPickup
erCUCMRemDestLimit
Specifies the remote destination limitsassociated with the user.
Integer Yes RW Must be aNumber inthe range of1 - 10
Remote Destination Limit
erCUCMRemDestProfileName
Specifies the remote destination profilenames associated with the user.
String No RW Maximumlength is 51characters
Remote Destination Profile
erCUCMAccessList
Lists the access lists associated withthe user.
String No R NA Access List
40 Cisco Unified Communications Manager Adapter Installation and Configuration Guide
Table 6. Optional attributes for the erCUCMAccount object class (continued)
Attribute name and descriptionDatatype
Singlevalued
Permissions Constraints
Attribute name on CUCMserver
erCUCMEnableCTI
Specifies to enable computer-telephonyintegration.
Boolean Yes RW NA Allow Control of Devices fromCTI
erCUCMDevices
Specifies the phones associated withthe user.
String No RW NA Controlled Devices
erCUCMDeviceProfiles
Specifies the phone profiles associatedwith the user.
String No RW NA Controlled Device Profiles
erCUCMAssociatedGroups
Specifies the groups associated withthe user.
String No RW NA Groups
erCUCMRoles
Lists the roles associated with thegroups to which the user belongs.
String No R NA Roles
Chapter 8. Reference 41
42 Cisco Unified Communications Manager Adapter Installation and Configuration Guide
Index
Aadapter
attributes 39features
group management 1password change 1remote destination profiles 1support data 1user account management 1
installation 9dispatcher requirement 9troubleshooting errors 33verifying 10, 15warnings 33
installation worksheet 8profile
customizing 19upgrade 17
supported configurations 2uninstall 37uninstallation 37upgrading 17
adaptersremoving profiles 37service, enabling SSL 29
attributes, adapter 39authentication
communication with SSL 23SSL, one-way and two-way 23
Ccertificates
extractingCA for Tivoli Directory
Integrator 27WebSphere Application Server
CA 30importing 27importing to truststore 30origin verification 27, 30self-signed 26signed 29
CiscoUniComMgr.jar file 37communication
SSL client 29SSL one-way 23SSL two-way 24WebSphere Application Server
workstation 29configuring
keystores, Security DirectoryIntegrator 28
Security Directory Integratorfor keystores 28for truststores 28
truststores, configuring SecurityDirectory Integrator 28
connector, upgrade 17
creatingservices 11
customizing adapter profile 19
Ddefinition
certificate authority 21certificates 21private key 21
dispatcherarchitecture 2installation 9
download, software 7
Eerror messages 35extracting certificates 30
IiKeyman utility 21importing
certificates 27importing certificates
to truststores 30installation
adapterdispatcher requirement 9software 9
planning roadmaps 5subsequent steps
adapter configuration 19adapter verification 19language pack installation 19SSL setup 19
uninstall 37verification
adapter 15verify 10worksheet 8
Kkey management utility, iKeyman 21keystore
creating 25directory integrator usage 25server authentication to clients 25
Mmessages
error 35warning 35
MS-DOS ASCII characters 20
Ooperating system prerequisites 6
Ppost-installation steps
adapterconfiguration 19verification 19
language pack installation 19SSL setup 19
private key, definition 21profile
customizing 19editing on UNIX or Linux 20
protocolSSL
certificate management 25client authentication 26keystore 25truststore 26
SSL, overview 21
Rremoving
adapter profiles 37restoring accounts, password
requirements 21roadmaps
planning 5
SSecure Sockets Layer
terminology 22self-signed certificates 26server, SSL tasks 25service
restart 10SSL, enabling for adapter 29start 10stop 10
service, creating 11signed certificates
creating 29for server 29
softwaredownload 7requirements 6website 7
SSLadapter service, enabling 29authentication 23certificate installation 21client communication 29communication, one-way and
two-way 23creating a keystore 25
43
SSL (continued)creating truststores 26one-way communication 23overview 21tasks done on the server 25terminology 22two-way communication 24workstation communication 29
SSL certificatesself-signed 26
supported configurationsadapter 2overview 2
Tterminology
SSL 22tivoli directory integrator connector 2troubleshooting
identifying problems 33techniques for 33
troubleshooting and supporttroubleshooting techniques 33
truststoreimporting certificates 30
truststoresclient authentication to server 26creating 26
Uuninstallation
adapter 37CiscoUniComMgr.jar file 37server and profile 37
upgradeadapter 17connector 17existing adapter profile 17
Vverification
dispatcher installation 9installation 15operating system prerequisites 6operating system requirements 6software prerequisites 6software requirements 6
vi command 20
Wwarning messages 35
44 Cisco Unified Communications Manager Adapter Installation and Configuration Guide
IBM®
Printed in USA