BlackBerry Enterprise Server Adapter Installation and Configuration Guide

Transcription

1 IBM Security Identity Manager Version 6.0 BlackBerry Enterprise Server Adapter Installation and Configuration Guide SC

2

3 IBM Security Identity Manager Version 6.0 BlackBerry Enterprise Server Adapter Installation and Configuration Guide SC

4 Note Before using this information and the product it supports, read the information in Notices on page 49. Edition notice Note: This edition applies to version 6.0 of IBM Security Identity Manager (product number 5724-C34) and to all subsequent releases and modifications until otherwise indicated in new editions. Copyright IBM Corporation US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

5 Contents Figures v Tables vii Preface ix About this publication ix Access to publications and terminology..... ix Accessibility x Technical training x Support information x Statement of Good Security Practices x Chapter 1. Overview of the adapter... 1 Features of the adapter Architecture of the adapter Supported configurations Chapter 2. Adapter installation planning 5 Preinstallation roadmap Installation roadmap Prerequisites Prerequisites for running the adapter Installation worksheet for the adapter Software downloads Chapter 3. Adapter installation Dispatcher installation verification Verifying the version of Tivoli Directory Integrator. 9 Exporting and importing the BlackBerry Enterprise Server SSL certificate Installing the adapter Installation verification Adapter service start, stop, and restart Importing the adapter profile into the IBM Security Identity Manager server Adapter profile installation verification Adapter user account creation Creating a service Chapter 4. First steps after you install the BlackBerry Enterprise Server Adapter Adapter configuration Editing adapter profiles on the UNIX or Linux operating system Modification of the maximum length of the account form attributes Creating a JAR file and importing the profile on the IBM Security Identity Manager Language pack installation for BlackBerry Enterprise Server Adapter Verifying that the BlackBerry Enterprise Adapter is working correctly Chapter 5. Adapter error troubleshooting Techniques for troubleshooting problems Exception messages Known limitations Chapter 6. Adapter upgrades Upgrading the connector Adapter profile upgrades Chapter 7. Adapter uninstallation Uninstalling the adapter from the Tivoli Directory Integrator server Adapter profile: Removal from the IBM Security Identity Manager server Chapter 8. Adapter reinstallation Appendix A. Adapter attributes Attribute descriptions Appendix B. Adapter installation on a z/os operating system Appendix C. Definitions for ITDI_HOME and ISIM_HOME directories Appendix D. Support information Searching knowledge bases Obtaining a product fix Contacting IBM Support Appendix E. Accessibility features for IBM Security Identity Manager Notices Index Copyright IBM Corp iii

6 iv IBM Security Identity Manager: BlackBerry Enterprise Server Adapter Installation and Configuration Guide

7 Figures 1. The architecture of the BlackBerry Enterprise Server Adapter Example of a single server configuration Example of multiple server configuration 3 Copyright IBM Corp v

8 vi IBM Security Identity Manager: BlackBerry Enterprise Server Adapter Installation and Configuration Guide

9 Tables 1. Preinstallation roadmap Installation roadmap Prerequisites to install the adapter BlackBerry Enterprise Server Adapter prerequisites Required information to install the adapter 7 6. Adapter component Attributes for the erbesaccount object class Attributes for the erbesrmiservice object class Attributes for the erbesgroup object class Attributes for the erbesrole object class Attributes for the erbesitpolicy object class Attributes for the erbesswconfig object class 38 Copyright IBM Corp vii

10 viii IBM Security Identity Manager: BlackBerry Enterprise Server Adapter Installation and Configuration Guide

11 Preface About this publication The IBM Security Identity Manager BlackBerry Enterprise Server Adapter Installation and Configuration Guide provides the basic information that you can use install and configure the adapter. IBM Security Identity Manager was previously known as Tivoli Identity Manager. The adapter enables connectivity between the IBM Security Identity Manager server and the managed resource. Access to publications and terminology This section provides: v A list of publications in the IBM Security Identity Manager library. v Links to Online publications. v A link to the IBM Terminology website. IBM Security Identity Manager library For a complete listing of the IBM Security Identity Manager and IBM Security Identity Manager Adapter documentation, see the online library ( com.ibm.isim.doc_6.0/ic-homepage.htm). Online publications IBM posts product publications when the product is released and when the publications are updated at the following locations: IBM Security Identity Manager library The product documentation site ( infocenter/tivihelp/v2r1/index.jsp?topic=/com.ibm.isim.doc_6.0/ichomepage.htm) displays the welcome page and navigation for the library. IBM Security Systems Documentation Central IBM Security Systems Documentation Central provides an alphabetical list of all IBM Security Systems product libraries and links to the online documentation for specific versions of each product. IBM Publications Center The IBM Publications Center site ( linkweb/publications/servlet/pbi.wss) offers customized search functions to help you find all the IBM publications you need. IBM Terminology website The IBM Terminology website consolidates terminology for product libraries in one location. You can access the Terminology website at software/globalization/terminology. Copyright IBM Corp ix

12 Accessibility Technical training Support information Accessibility features help users with a physical disability, such as restricted mobility or limited vision, to use software products successfully. With this product, you can use assistive technologies to hear and navigate the interface. You can also use the keyboard instead of the mouse to operate all features of the graphical user interface. For technical training information, see the following IBM Education website at IBM Support provides assistance with code-related problems and routine, short duration installation or usage questions. You can directly access the IBM Software Support site at Appendix D, Support information, on page 43 provides details about: v What information to collect before contacting IBM Support. v The various methods for contacting IBM Support. v How to use IBM Support Assistant. v Instructions and problem-determination resources to isolate and fix the problem yourself. Note: The Community and Support tab on the product information center can provide additional support resources. Statement of Good Security Practices IT system security involves protecting systems and information through prevention, detection and response to improper access from within and outside your enterprise. Improper access can result in information being altered, destroyed, misappropriated or misused or can result in damage to or misuse of your systems, including for use in attacks on others. No IT system or product should be considered completely secure and no single product, service or security measure can be completely effective in preventing improper use or access. IBM systems, products and services are designed to be part of a comprehensive security approach, which will necessarily involve additional operational procedures, and may require other systems, products or services to be most effective. IBM DOES NOT WARRANT THAT ANY SYSTEMS, PRODUCTS OR SERVICES ARE IMMUNE FROM, OR WILL MAKE YOUR ENTERPRISE IMMUNE FROM, THE MALICIOUS OR ILLEGAL CONDUCT OF ANY PARTY. x IBM Security Identity Manager: BlackBerry Enterprise Server Adapter Installation and Configuration Guide

13 Chapter 1. Overview of the adapter Features of the adapter Architecture of the adapter An adapter provides an interface between a managed resource and the IBM Security Identity Manager server. An adapter, which might or might not reside on the managed resource, functions as a trusted virtual administrator for the resource. Adapters perform tasks such creating, suspending, and restoring user accounts, and other administrative functions that are performed manually. An adapter runs as a service, independently of whether you are logged on to the IBM Security Identity Manager server. The BlackBerry Enterprise Server Adapter enables communication between the IBM Security Identity Manager server and the BlackBerry Enterprise Server. The adapter automates the following user account management tasks: v Creating BlackBerry-enabled user accounts from accounts that exist in the BlackBerry Enterprise Server underlying messaging service. v Creating BlackBerry-enabled administrative user accounts. The adapter does not manage administrative accounts that are not BlackBerry-enabled. v Modifying user account attributes such as activation passwords, groups, IT policy, and software configurations. v Modifying login passwords for BlackBerry-enabled administrative user accounts. v Suspending, restoring, and deleting user accounts. v Reconciling user accounts and other data such as groups, roles, IT policies, and software configurations You must install the following components for the adapter to function correctly: v The Dispatcher v The Tivoli Directory Integrator connector v The IBM Security Identity Manager adapter profile You must install the Dispatcher and the adapter profile; however, the Tivoli Directory Integrator connector might already be installed with the base Tivoli Directory Integrator product. Figure 1 on page 2 describes the components that work together to complete the user account management tasks in a Tivoli Directory Integrator environment. Copyright IBM Corp

14 IBM Security Identity Manager Server RMI calls Dispatcher Service (an instance of the IBM Tivoli Directory Integrator) Adapter resource Supported configurations Figure 1. The architecture of the BlackBerry Enterprise Server Adapter For more information about Tivoli Directory Integrator, see the Quick Start Guide at IBM Security Identity Manager product documentation. Each environment consists of several components. v The IBM Security Identity Manager server v The Tivoli Directory Integrator server v The managed resource v The adapter The adapter must reside directly on the server that runs the Tivoli Directory Integrator server. Single server configuration In a single server configuration, install the following products on the same server: v IBM Security Identity Manager server v Tivoli Directory Integrator server v BlackBerry Enterprise Server Adapter This server communicates with the BlackBerry Enterprise Server server. The BlackBerry Enterprise Server server is installed on a different server as described in Figure 2. IBM Security Identity Manager Server Tivoli Directory Integrator Server Managed resource Adapter Figure 2. Example of a single server configuration Multiple server configuration In a multiple server configuration, the IBM Security Identity Manager server, the BlackBerry Enterprise Server Adapter, and the BlackBerry Enterprise Server are installed on different servers. Install the Tivoli Directory Integrator server and the BlackBerry Enterprise Server Adapter on the same server as described Figure 3 on page 3. 2 IBM Security Identity Manager: BlackBerry Enterprise Server Adapter Installation and Configuration Guide

15 IBM Security Identity Manager server Tivoli Directory Integrator server Managed resource Adapter Figure 3. Example of multiple server configuration Chapter 1. Overview of the adapter 3

16 4 IBM Security Identity Manager: BlackBerry Enterprise Server Adapter Installation and Configuration Guide

17 Chapter 2. Adapter installation planning Preinstallation roadmap Installing and configuring the adapter involves several steps that you must complete in an appropriate sequence. Review the roadmaps before you begin the installation process. Before you install the adapter, you must prepare the environment. Perform the tasks that are listed in Table 1. Table 1. Preinstallation roadmap Task Obtain the installation software. Verify that your environment meets the software and hardware requirements for the adapter. Obtain and install the Dispatcher. Obtain the necessary information for the installation and configuration. Export and import the BlackBerry Enterprise Server SSL certificate. For more information Download the software from Passport Advantage website. See Software downloads on page 8. See Prerequisites on page 6 and Prerequisites for running the adapter on page 6. Download the software from Passport Advantage website. See Software downloads on page 8. Follow the installation instructions in the dispatcher download package. See Installation worksheet for the adapter on page 7. See Exporting and importing the BlackBerry Enterprise Server SSL certificate on page 9. Installation roadmap To install the adapter, complete the tasks that are listed in the following table: Table 2. Installation roadmap Task For more information Verify the Dispatcher installation. See Dispatcher installation verification on page 9. Install the adapter. See Installing the adapter on page 10. Verify the adapter installation. See Installation verification on page 12. Import the adapter profile. See Importing the adapter profile into the IBM Security Identity Manager server on page 12. Verify the profile installation. See Adapter profile installation verification on page 13. Create an adapter user account. See Adapter user account creation on page 14. Create a service. See Creating a service on page 14. Copyright IBM Corp

18 Table 2. Installation roadmap (continued) Task For more information Configure the adapter. See Adapter configuration on page 19. Prerequisites Verify that your environment meets all the prerequisites before you install the adapter. The following table identifies the software and operating system prerequisites for the adapter installation. Ensure that you install the adapter on the same workstation as the Tivoli Directory Integrator server. Table 3. Prerequisites to install the adapter Prerequisite IBM Tivoli Directory Integrator Description Version 7.1 fix pack 5 or later Version IBM Security Identity Manager server Version 6.0 BlackBerry Enterprise Server for Domino Version System Administrator authority To complete the adapter installation procedure, you must have system administrator authority. Tivoli Directory Integrator adapters solution directory A Tivoli Directory Integrator adapters solution directory is a Tivoli Directory Integrator work directory for IBM Security Identity Manager adapters. BlackBerry Enterprise Server For more information, see the Dispatcher Installation and Configuration Guide. For either: v Lotus Domino v Microsoft Exchange For information about the prerequisites and supported operating systems for Tivoli Directory Integrator, see the IBM Tivoli Directory Integrator 7.1: Administrator Guide. Prerequisites for running the adapter The following table lists the requirements to run the BlackBerry Enterprise Server Adapter. Table 4. BlackBerry Enterprise Server Adapter prerequisites Requirement Description Task Export and Import the SSL Certificate. Export the SSL certificate from the managed resource and import it to the certificate authority (CA) truststore of the Tivoli Directory Integrator Java Virtual Machine (JVM). See Exporting and importing the BlackBerry Enterprise Server SSL certificate on page 9. 6 IBM Security Identity Manager: BlackBerry Enterprise Server Adapter Installation and Configuration Guide

19 Table 4. BlackBerry Enterprise Server Adapter prerequisites (continued) Requirement Description Task Create a separate Tivoli Directory Integrator environment for the BlackBerry Enterprise Server connector. Best practice is to run the BlackBerry Enterprise Server connector in its own Tivoli Directory Integrator environment. In the Tivoli Directory Integrator environment, delete the ITDI_HOME/jars/3rdparty/IBM/axis2 directory. Failure to remove this directory causes the connector to fail. Installation worksheet for the adapter The following table identifies the information that you need before you install the adapter. Table 5. Required information to install the adapter Required information Description Value Tivoli Directory Integrator Home Directory The ITDI_HOME directory contains the jars/connectors subdirectory that contains adapter JAR files. For example, the jars/connectors subdirectory contains the JAR file for the UNIX adapter. If Tivoli Directory Integrator is automatically installed with your IBM Security Identity Manager product, the default directory path for Tivoli Directory Integrator is as follows: Windows: v for version 7.1: drive\program Files\IBM\TDI\V7.1 Adapters solution directory When you install the dispatcher, the installer prompts you to specify a file path for the solution directory. For more information about the solution directory, see the Dispatcher Installation and Configuration Guide. UNIX: v for version 7.1: /opt/ibm/tdi/v7.1 The default solution directory is at: Windows: v for version 7.1: drive\program Files\IBM\TDI\V7.1\ timsol UNIX: v for version 7.1: /opt/ibm/tdi/v7.1/ timsol Chapter 2. Adapter installation planning 7

20 Software downloads Download the software through your account at the IBM Passport Advantage website. Go to IBM Passport Advantage. See the IBM Security Identity Manager Download Document for instructions. Note: You can also obtain additional adapter information from IBM Support. 8 IBM Security Identity Manager: BlackBerry Enterprise Server Adapter Installation and Configuration Guide

21 Chapter 3. Adapter installation All the Tivoli Directory Integrator based adapters require the dispatcher for the adapters to function correctly. If the dispatcher is installed from a previous installation, do not reinstall it unless there is an upgrade to the dispatcher. See Dispatcher installation verification. After verifying the Dispatcher installation, you might need to install the Tivoli Directory Integrator connector. Depending on your adapter, the connector might already be installed as part of the Tivoli Directory Integrator product and no further action is required. Dispatcher installation verification If this installation is the first Tivoli Directory Integrator based adapter installation, you must install the dispatcher before you install the adapter. Install the dispatcher on the same Tivoli Directory Integrator server where you want to install the adapter. Obtain the dispatcher installer from the IBM Passport Advantage website, pao_customers.htm. For information about Dispatcher installation, see the Dispatcher Installation and Configuration Guide. Verifying the version of Tivoli Directory Integrator Before you install the adapter, ensure that the Tivoli Directory Integrator is a supported version. Procedure 1. Navigate to the build.properties file in the ITDI_HOME\etc\ directory on a Windows operating system. 2. Open the file in text editor, such as Notepad and check the value of the Version property. For example, if fix pack 1 is installed on the base version of Tivoli Directory Integrator 7.1, then the value of Version property is Exporting and importing the BlackBerry Enterprise Server SSL certificate You must download the certificate from the BlackBerry Administrative Server and import it to the CA certificate keystore. Before you begin Go to the BlackBerry Getting Started website to ensure that you have the most current instructions for downloading the certificate. en/developers/deliverables/25822/ Download_a_copy_of_the_SSL_cert_of_the_BAS_ _11.jsp Copyright IBM Corp

22 About this task Perform the following steps to download and import the BlackBerry Enterprise Server SSL certificate. Procedure v To download the BlackBerry Enterprise Server root certificate: 1. Create a temporary directory. For example, C:\temp\baa. 2. In a browser, open the BlackBerry Administration Service. Go to Servername represents the fully qualified domain name (FQDN) or the IP address of the server that hosts the BlackBerry Administration Service. 3. Click File > Properties. 4. In the Properties window, click Certificates. 5. Click Details. 6. Click Copy to File. 7. Follow the screen instructions to copy the certificate in DER encoded binary format to the temporary directory that you created. v The certificate is copied to C:\temp\baa\bascert.cer. To import the server root certificate: Installing the adapter Note: You must provide your CA certificate keystore password to import the server root certificate. 1. Locate the server root certificate file that you exported from BlackBerry Enterprise Server and copy it to the target host. 2. Import the certificate to the local CA certificate keystore. a. Change directories to ITDI_HOME/jvm/jre/bin directory. b. Type: keytool -import -trustcacerts -file \temp\baa\bascert.cer -keystore ITDI_HOME/timsol/serverapi/testadmin.jks -storepass administrator -alias bas Note: The default password for the testadmin.jks keystore is administrator. The Java keytool displays a confirmation that the certificate is added to the keystore. Take these steps to install the adapter: Before you begin Do the following tasks: v Verify that your site meets all the prerequisite requirements. See Prerequisites on page 6 and Prerequisites for running the adapter on page 6. Note: The ITDI_HOME/jars/3rdparty/IBM/axis2 directory must be removed from the Tivoli Directory Integrator environment. You can either delete it or move it to a location outside of the Tivoli Directory Integrator environment. If the BlackBerry Enterprise Server Adapter is uninstalled, you might need to restore this directory. 10 IBM Security Identity Manager: BlackBerry Enterprise Server Adapter Installation and Configuration Guide

23 v Obtain a copy of the adapter software. See Software downloads on page 8. v Obtain system administrator authority. About this task The adapter uses the Tivoli Directory Integrator BlackBerry Enterprise Server connector. The connector is not available with the base Tivoli Directory Integrator product. The adapter installation involves the Tivoli Directory Integrator BlackBerry Enterprise Server connector installation. Before you install the adapter, make sure that the dispatcher is installed. See Dispatcher installation verification on page 9. Procedure To install the adapter, perform the following steps: 1. Create a temporary directory on the workstation where you want to extract the adapter. 2. Extract the contents of the compressed file in the temporary directory. The extracted files are typically: ibmdita.css license license/la... more licenses... license/li_zh_tw... doc files... ReleaseNotes-BES-6.0.html connectors connectors/domino connectors/domino/besconnector.jar connectors/exchange connectors/exchange/besconnector.jar BESProfile.jar 3. Copy the appropriate BESConnector.jar file for your system to the ITDI_HOME/jars/connectors directory. v For BlackBerry Enterprise Server for IBM Lotus Domino, copy the connectors/domino/besconnector.jar v For BlackBerry Enterprise Server for Microsoft Exchange, copy the connectors/exchange/besconnector.jar file 4. Restart the IBM Security Identity Manager adapter (Dispatcher) service. What to do next After you finish the adapter installation, do the following tasks: v Verify that the installation completed successfully. See Installation verification on page 12. v Import the adapter profile. See Importing the adapter profile into the IBM Security Identity Manager server on page 12. v Create a user account for the adapter on IBM Security Identity Manager. See Adapter user account creation on page 14. Chapter 3. Adapter installation 11

24 Installation verification If the adapter is installed correctly, you can verify that the components exist in the specified directories. Table 6. Adapter component Adapter component BESConnector.jar Directory On the Windows operating system ITDI_HOME\jars\connectors\ On the UNIX operating system ITDI_HOME/jars/connectors/ To upgrade the BlackBerry Enterprise Server connector, copy the new BESConnector.jar file over the existing one. Restart the Tivoli Directory Integrator server. Verifying the BlackBerry Enterprise Server environment The adapter supports two versions of the connector. One for the Lotus Domino environment and the other for the Microsoft Exchange environment. Use the manifest file to verify that the correct BESConnector.jar file is installed for your environment. 1. Issue the command: jar xvf BESConnector.jar META-INF/MANIFEST.MF 2. Open the META-INF/MANIFEST.MF file with an editor. 3. Verify that the Implementation is correct for your environment. Implementation-Title: IBM Security Identity Manager BlackBerry Enterprise Server for Lotus Domino Adapter Connector or Implementation-Title: IBM Security Identity Manager BlackBerry Enterprise Server for Microsoft Exchange Adapter Connector Adapter service start, stop, and restart To start, stop, or restart the adapter, you must start, stop, or restart the Dispatcher. The adapter does not exist as an independent service or a process. The adapter is added to the Dispatcher instance, which runs all the adapters that are installed on the same Tivoli Directory Integrator instance. See the topic about starting stopping, and restarting the dispatcher service in the Dispatcher Installation and Configuration Guide. Importing the adapter profile into the IBM Security Identity Manager server An adapter profile defines the types of resources that the IBM Security Identity Manager server can manage. 12 IBM Security Identity Manager: BlackBerry Enterprise Server Adapter Installation and Configuration Guide

25 About this task Use the profile to create an adapter service on IBM Security Identity Manager server and establish communication with the adapter. Before you can add an adapter as a service to the IBM Security Identity Manager server, the server must have the adapter profile. The server uses the profile to recognize the adapter as a service. The files that are packaged with the adapter include the adapter BESProfile.jar file. You can import the adapter profile as a service profile on the server with the Import feature of IBM Security Identity Manager. The BESProfile.jar file includes all the files that are required to define the adapter schema, account form, service form, and profile properties. You can extract the files from the JAR file to modify the necessary files and package the JAR file with the updated files. Before you begin to import the adapter profile, verify that the following conditions are met: v The IBM Security Identity Manager server is installed and running. v You have root or Administrator authority on IBM Security Identity Manager. To import the adapter profile, perform the following steps: Procedure 1. Log on to the IBM Security Identity Manager server by using an account that has the authority to perform administrative tasks. 2. In the My Work pane, expand Configure System and click Manage Service Types. 3. On the Manage Service Types page, click Import to display the Import Service Types page. 4. Specify the location of the BESProfile.jar file in the Service Definition File field by performing one of the following tasks: v Type the complete location of where the file is stored. v Use Browse to navigate to the file. 5. Click OK. What to do next v v When you import the adapter profile and if you receive an error that is related to the schema, see the trace.log file for information about the error. The trace.log file location is specified by using the handler.file.filedir property that is defined in the IBM Security Identity Manager enrolelogging.properties file. The enrolelogging.properties file is installed in the IBM Security Identity Manager \data directory. Restart the IBM Security Identity Manager for the change to take effect. Adapter profile installation verification After you install the adapter profile, verify that the installation was successful. An unsuccessful installation: v Might cause the adapter to function incorrectly. v Prevents you from creating a service with the adapter profile. Chapter 3. Adapter installation 13

26 To verify that the adapter profile is successfully installed, create a service with the adapter profile. For more information about creating a service, see Creating a service. If you are unable to create a service with the adapter profile or open an account on the service, the adapter profile is not installed correctly. You must import the adapter profile again. Adapter user account creation Creating a service You must create an administrative user account for the adapter on the managed resource. You must provide the account information when you create a service. For more information about creating a service, see Creating a service. Ensure that the account has sufficient privileges to administer the BlackBerry Enterprise Server users. After the adapter profile is imported on IBM Security Identity Manager, you must create a service so that IBM Security Identity Manager can communicate with the adapter. About this task A service represents a single BlackBerry Enterprise Server instance. The adapter cannot move a user account from one BlackBerry Enterprise Server to another. To create a service, perform the following steps: Note: To create or change a service, you must use the service form to provide information for the service. Service forms might vary depending on the adapter. Procedure 1. Log on to the IBM Security Identity Manager server with an account that has the authority to perform administrative tasks. 2. In the My Work pane, click Manage Services and click Create. 3. On the Select the Type of Service page, select BlackBerry Enterprise Server profile. 4. Click Next to display the adapter service form. 5. Complete the following fields on the service form: On the General Information tab: Service Name Specify a name that defines the adapter service on the IBM Security Identity Manager server. Note: Do not use forward (/) or backward slashes (\) in the service name. Description Specify a description that identifies the service for your environment. 14 IBM Security Identity Manager: BlackBerry Enterprise Server Adapter Installation and Configuration Guide

27 Tivoli Directory Integrator location Specify the URL for the Tivoli Directory Integrator instance. The valid syntax for the URL is rmi://ip-address:port/ ITDIDispatcher, where ip-address is the Tivoli Directory Integrator host and port is the port number for the Dispatcher. The default URL is rmi://localhost:1099/itdidispatcher For information about changing the port number, see the IBM Security Dispatcher Installation and Configuration Guide. Server Host Name Specify the name of the host that is running the BlackBerry Enterprise Server. Administrator Name Specify the administrator user that is used to log in to the resource and perform user management operations. Make sure that the administrator user has Security Administrator authority on the BlackBerry Enterprise Server. Note: If you use the Active Directory authenticator type, do not use a domain-qualified administrator name. That is, do not use the DomainName\UserName format, just use UserName. Password Specify the password for administrator user. Authentication Domain Specify the authentication domain to use when the user authenticates to the BlackBerry Enterprise Server. This field is not required for all authenticator types. Active Directory authentication requires an authentication domain, but BlackBerry Administration Service authentication does not. Authenticator Type Specify the type of authentication to use to access the BlackBerry Enterprise Server. The following are examples of authenticator types. v Active Directory v BlackBerry Administration Service v Domino mailbox Note: This field is not case-sensitive. On the Dispatcher Attributes tab: AL FileSystem Path Specify the file path from where the dispatcher loads the assembly lines. If you do not specify a file path, the dispatcher loads the assembly lines that are received from IBM Security Identity Manager. You can specify a file path such as the following to load the assembly lines from the profiles directory of the Windows operating system: c:\program Files\IBM\TDI\V7.1\profiles or you can specify the following file path to load the assembly lines from the profiles directory of the UNIX and Linux operating systems: /opt/ibm/tdi/v7.1/profiles. You must extract the assembly line files from the profile JAR file. Use a command such as Chapter 3. Adapter installation 15

28 jar xvf BESProfile.jar extracts the files BESProfile BESProfile/BESAdd.xml BESProfile/BESDelete.xml BESProfile/BESModify.xml BESProfile/BESSearch.xml BESProfile/BESTest.xml BESProfile/CustomLabels.properties BESProfile/erBESAccount.xml BESProfile/erBESRMIService.xml BESProfile/schema.dsml BESProfile/service.def You must copy the assembly line files to the location that you specify for the AL FileSystem Path. Max Connection Count Specify the maximum number of assembly lines that the dispatcher can execute simultaneously for the service. If you enter 0 in the Max Connection Count field, the dispatcher does not limit the number of assembly lines that are executed simultaneously for the service. Disable AL Caching Select the check box to disable the assembly line caching in the dispatcher for the service. The assembly lines for the reconciliation and test operations are not cached. On the Status and information tab Contains read only information about the adapter and managed resource. These fields are examples. The actual fields vary depending on the type of adapter and how the service form is configured. The adapter must be running to obtain the information. Click Test Connection to populate the fields. Last status update: Date Specifies the most recent date when the Status and information tab was updated. Last status update: Time Specifies the most recent time of the date when the Status and information tab was updated. Managed resource status Specifies the status of the managed resource that the adapter is connected to. Adapter version Specifies the version of the adapter that the IBM Security Identity Manager service uses to provision request to the managed resource. Profile version Specifies the version of the profile that is installed in the IBM Security Identity Manager server. 16 IBM Security Identity Manager: BlackBerry Enterprise Server Adapter Installation and Configuration Guide

29 TDI version Specifies the version of the Tivoli Directory Integrator on which the adapter is deployed. Dispatcher version Specifies the version of the Dispatcher. Installation platform Specifies summary information about the operating system where the 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. Also v Verify the adapter log to ensure that the IBM Security Identity Manager test request was successfully sent to the adapter. v Verify the adapter configuration information. v Verify IBM Security Identity Manager service parameters for the adapter profile, such as the work station name or the IP address of the managed resource, and the port. 6. Click Finish. Chapter 3. Adapter installation 17

30 18 IBM Security Identity Manager: BlackBerry Enterprise Server Adapter Installation and Configuration Guide

31 Chapter 4. First steps after you install the BlackBerry Enterprise Server Adapter Adapter configuration After you install the adapter, you must do several other tasks. The tasks include configuring the adapter, setting up SSL, installing the language pack, and verifying that the adapter works correctly. The BlackBerry Enterprise Server Adapter has configuration options to edit the profile, modify account form attributes, and create JAR files. v Editing adapter profiles on the UNIX or Linux operating system v Modification of the maximum length of the account form attributes on page 20 v Creating a JAR file and importing the profile on the IBM Security Identity Manager on page 20 See the IBM Security Dispatcher Installation and Configuration Guide for more configuration options such as: v JVM properties v Dispatcher filtering v Dispatcher properties v Dispatcher port number v Logging configurations v Secure Sockets Layer (SSL) communication Editing adapter profiles on the UNIX or Linux operating system The adapter profile.jar file might contain ASCII files that are created by using the MS-DOS ASCII format. About this task If you edit an MS-DOS ASCII file on the UNIX operating system, you might see a character ^M at the end of each line. These characters indicate new lines of text in MS-DOS. The characters can interfere with the running of the file on UNIX or Linux 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 characters manually. Example You can use the vi editor to remove the ^M characters. From the vi command mode, run the following command and press Enter: :%s/^m//g When you use this command, enter ^M or Ctrl-M by pressing ^v^m or Ctrl V Ctrl M sequentially. The ^v instructs the vi editor to use the next keystroke instead of issuing it as command. Copyright IBM Corp

32 Modification of the maximum length of the account form attributes To modify the maximum length of the attributes on the account form, you must modify the schema.dsml file with the required length. For example, the default value for the maximum length of the Address attribute is 240. To change the value of the attribute to 256, modify the schema.dsml file as: Old profile: <!-- ******************************************************** --> <!-- erbes addr --> <!-- ******************************************************** --> <attribute-type single-value = "true" > <name>erbes addr</name> <description>bes user address</description> <object-identifier> </object-identifier> <syntax> </syntax> </attribute-type> Modified profile: <!-- ******************************************************** --> <!-- erbes addr --> <!-- ******************************************************** --> <attribute-type single-value = "true" > <name>erbes addr</name> <description>bes user address</description> <object-identifier> </object-identifier> <syntax> {256}</syntax> </attribute-type> If the attribute is already defined in LDAP and contains data, you must change the length in LDAP manually. If the attribute does not exist or does not contain data, the attribute is created with the new length when the profile is imported. Creating a JAR file and importing the profile on the IBM Security Identity Manager After you modify the schema.dsml or any other profile files, you must import these files into IBM Security Identity Manager for the changes to take effect. About this task If you are upgrading an existing adapter profile, the new adapter profile schema is not reflected immediately. You must stop and start the IBM Security Identity Manager server to refresh the cache and the adapter schema. For more information about upgrading an existing adapter, see Chapter 6, Adapter upgrades, on page 29. Procedure 1. Extract the contents of the BESProfile.jar file into the temporary directory by running the following command: cd c:\temp jar -xvf BESProfile.jar The jar command creates the c:\temp\besprofile directory. 2. Update the profile files. 20 IBM Security Identity Manager: BlackBerry Enterprise Server Adapter Installation and Configuration Guide

33 3. Create a JAR file by using the files in the \temp directory by running the following commands: cd c:\temp jar -cvf BESProfile.jar BESProfile 4. Import the BESProfile.jar file into the IBM Security Identity Manager server. For more information about importing the file, see Importing the adapter profile into the IBM Security Identity Manager server on page Stop and start the IBM Security Identity Manager server. Language pack installation for BlackBerry Enterprise Server Adapter The adapters use the same language package as IBM Security Identity Manager. See the IBM Security Identity Manager library and search for information about installing language packs. Verifying that the BlackBerry Enterprise Adapter is working correctly After you install and configure the adapter, take steps to verify that the installation and configuration are correct. Procedure 1. Test the connection for the service that you created on IBM Security Identity Manager. 2. Run a full reconciliation from IBM Security Identity Manager. 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 IBM Security Identity Manager log file trace.log to ensure that no errors are reported when you run an adapter operation. Chapter 4. First steps after you install the BlackBerry Enterprise Server Adapter 21

34 22 IBM Security Identity Manager: BlackBerry Enterprise Server Adapter Installation and Configuration Guide

35 Chapter 5. Adapter error troubleshooting Troubleshooting can help you determine why a product does not function properly. The troubleshooting topics provide information and techniques for identifying and resolving problems with the adapter. They also provide information about troubleshooting errors that might occur during the adapter installation. Techniques for troubleshooting problems Troubleshooting is a systematic approach to solving a problem. The goal of troubleshooting is to determine why something does not work as expected and how to resolve the problem. Certain common techniques can help with the task of troubleshooting. The first step in the troubleshooting process is to describe the problem completely. Problem descriptions help you and the IBM technical-support representative know where to start to find the 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 describe a problem, the most obvious question is What is the problem? This question might seem straightforward; however, you can break it down into several more-focused questions that create a more descriptive picture of the 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 the most important steps in resolving a problem. Many layers of technology can exist between the reporting and failing components. Networks, disks, and drivers are only 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 isolate the problem layer: v v Is the problem specific to one platform or operating system, or is it common across multiple platforms or operating systems? Is the current environment and configuration supported? Copyright IBM Corp

36 v v Do all users have the problem? (For multi-site installations.) Do all sites have the problem? If one layer reports the problem, the problem does not necessarily originate in that layer. Part of identifying where a problem originates is understanding the environment in which it exists. Take some time to completely describe the problem environment, including the operating system and version, all corresponding software and versions, and hardware information. Confirm that you are running within an environment that is a supported configuration. Many problems can be traced back to incompatible levels of software that are not intended to run together or were not fully tested together. When does the problem occur? Develop a detailed timeline of events that lead up to a failure, especially for those cases that are one-time occurrences. You can most easily develop a timeline by working 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 and information. Typically, you need to look only as far as the first suspicious event that you find in a diagnostic 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 which to investigate the problem. Under which conditions does the problem occur? Knowing which systems and applications are running at the time that a problem occurs is an important part of troubleshooting. These questions about your environment can help you to identify the root cause of the problem: v Does the problem always occur when the same task is being performed? v Does a certain sequence of events need to happen 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 in which the problem occurs and correlate any dependencies. Just because multiple problems might occur around the same time, the problems are not necessarily related. Can the problem be reproduced? From a troubleshooting standpoint, the ideal problem is one that can be reproduced. Typically, when a problem can be reproduced you have a larger set of tools or procedures at your disposal to help you investigate. Problems that you can reproduce are often easier to debug and solve. However, problems that you can reproduce can have a disadvantage: If the problem is of significant business impact, you do not want it to recur. If possible, 24 IBM Security Identity Manager: BlackBerry Enterprise Server Adapter Installation and Configuration Guide

37 Exception messages re-create the problem in a test or development environment, which typically offers you more flexibility and control during your investigation. v Can the problem be re-created on a test system? v v Are there multiple users or applications that are encountering the same type of problem? Can the problem be re-created by running a single command, a set of commands, or a particular application? For information about obtaining support, see Appendix D, Support information, on page 43. Exception messages are recorded in the ITDI_HOME/timsol/logs/ibmdi.log file. BES connector error Console error message CTGIMT605E An error occurred while processing the search operation on the IBM Tivoli Directory Integrator server. Error: {1} Exception thrown :37:23,359 ERROR [C Program Files_IBM_TDI_V7.1_timsol_ITIM_RMI.xml] - recorderrormessage():794 Assembly line start exception occured. FunctionName: executealsearchstart(): AssemblyLineName: <<BESSearch>> Exception Class:com.ibm.di.dispatcher.rmi.AdaptersALStartException<<com.ibm.di.d ispatcher.rmi.adaptersalstartexception><statuscode=2><reasoncode=100><com.ibm.di.dispatcher.fail_start_al><[bessearch_bes_ _071e e1-11b2 -c5bd a5dc, javax.xml.bind.marshalexception - with linked exception: [javax.xml.bind.jaxbexception: com.rim.com_rim_bes_bas.encodeusername is not known to this context]]>> At com.ibm.di.dispatcher.rmi.rmidispatcherimpl.startassemblyline (RMIDispatcherImpl.java:1350) at com.ibm.di.dispatcher.rmi.rmidispatcherimpl.executealsearchstart (RMIDispatcherImpl.java:2546) at sun.reflect.nativemethodaccessorimpl.invoke0(native Method) at sun.reflect.nativemethodaccessorimpl.invoke(nativemethodaccessorimpl.java:48) at sun.reflect.delegatingmethodaccessorimpl.invoke(delegatingmethodaccessorimpl.java:37) at java.lang.reflect.method.invoke(method.java:600) at sun.rmi.server.unicastserverref.dispatch(unicastserverref.java:310) at sun.rmi.transport.transport$1.run(transport.java:171) at java.security.accesscontroller.doprivileged(accesscontroller.java:284) at sun.rmi.transport.transport.servicecall(transport.java:167) at sun.rmi.transport.tcp.tcptransport.handlemessages(tcptransport.java:547) at sun.rmi.transport.tcp.tcptransport$connectionhandler.run0(tcptransport.java:802) at sun.rmi.transport.tcp.tcptransport$connectionhandler.run(tcptransport.java:661) at java.util.concurrent.threadpoolexecutor$worker.runtask(threadpoolexecutor.java:886) at java.util.concurrent.threadpoolexecutor$worker.run(threadpoolexecutor.java:908) at java.lang.thread.run(thread.java:736) Probable cause The ITDI_HOME/jars/3rdparty/IBM/axis2 directory was not deleted from the BES connector Tivoli Directory Integrator environment. Corrective action Delete the directory from the environment and run the operation again. If it is not feasible to remove the axis2 directory, then the Apache CXF distribution must be downloaded and installed into the ITDI_HOME/jars/patches directory. Download the latest available binary distribution from the Apache CXF site. Note: The classes from the Apache CXF distribution take precedence over those classes in the axis2 distribution. Connectors depending on axis2 might no longer work. Chapter 5. Adapter error troubleshooting 25