Deploying EMC Documentum WDK Applications with IBM WebSEAL as a Reverse Proxy Applied Technology Abstract This white paper serves as a detailed solutions guide for installing and configuring IBM WebSEAL as a reverse proxy for use with EMC Documentum WDK-based applications. September 2010
Copyright 2010 EMC Corporation. All rights reserved. EMC believes the information in this publication is accurate as of its publication date. The information is subject to change without notice. THE INFORMATION IN THIS PUBLICATION IS PROVIDED AS IS. EMC CORPORATION MAKES NO REPRESENTATIONS OR WARRANTIES OF ANY KIND WITH RESPECT TO THE INFORMATION IN THIS PUBLICATION, AND SPECIFICALLY DISCLAIMS IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Use, copying, and distribution of any EMC software described in this publication requires an applicable software license. For the most up-to-date listing of EMC product names, see EMC Corporation Trademarks on EMC.com All other trademarks used herein are the property of their respective owners. Part Number h8052 Applied Technology 2
Table of Contents Executive summary... 4 Introduction... 4 Audience... 4 Installing and configuring IBM WebSEAL as a reverse proxy server... 4 Requirements... 5 Installing IBM Tivoli Access Manager for e-business... 5 Base system installation... 5 Setting up an Access Manager Java runtime system... 6 Setting up IBM Tivoli Directory Server Registry server... 10 Setting up a policy server... 23 Setting up an authorization server... 38 Installing the Web security system... 42 Setting up the Access Manager WebSEAL... 42 Configuring the WebSEAL system... 52 Creating a WebSEAL junction... 52 Documentum-specific configuration... 53 Miscellaneous... 54 Conclusion... 54 References... 54 Appendix: ikeyman utility... 54 Applied Technology 3
Executive summary This white paper outlines best practices guidelines for installing and configuring IBM WebSEAL as a reverse proxy to work with EMC Documentum WDK-based applications. IBM WebSEAL acts as a front end, protecting resources and applications located on the back-end servers in a web-based network. WebSEAL is a component of IBM Tivoli Access Manager for e-business. WebSEAL together with other Tivoli Access Manager for e-business components can provide end-to-end authentication and single signon for Web applications. Introduction This guide provides detailed information about how to install and configure IBM WebSEAL as a reverse proxy to use with EMC Documentum WDK-based applications. The IBM Tivoli Access Manager is a security-policy management suite that provides centralized authentication, authorization, and management services for web resources and hosted applications. In a web-based network, these services are best provided by front-end WebSEAL servers that protect resources and applications located on the back-end servers. This white paper includes three main sections: Installing and configuring IBM WebSEAL as a reverse proxy server, which includes requirements to use WebSEAL with Documentum. Installing IBM Tivoli Access Manager for e-business, which includes setting up an Access Manager Java runtime system, Tivoli Directory Server, policy server, authorization server, and Access Manager SEAL. Information on installing a web security system is also provided. Configuring the WebSEAL system, which includes creating a WebSEAL junction. EMC does not support IBM WebSEAL at this time. This setup was done with Documentum Webtop 6.5 SP2 and IBM WebSEAL version 6.1. It has been observed that the following steps lead to a successful install. If you choose to deviate from these steps, EMC does not guarantee that the procedure would work. A production setup may need advanced configurations, which are out of the scope of this documentation. In such cases you are expected to refer to other available documentation and judiciously go about the install. Audience This white paper is intended for IT architects, engineers, support professionals, and customers. It provides basic directions to use IBM WebSEAL as a reverse proxy. Installing and configuring IBM WebSEAL as a reverse proxy server IBM WebSEAL abstracts back-end resources and applications, and effectively protects them as a reverse web proxy. Applied Technology 4
Figure 1. A typical reverse proxy setup using IBM WebSEAL Requirements Before you can use IBM WebSEAL with EMC Documentum, you must meet these prerequisites: A fresh Windows Server 2003 Enterprise Edition R2 computer Installer packages for IBM Tivoli Access Manager for e-business version 6.1 This paper illustrates the process of installing all components on a single machine. However, in a production setup, you must install each of the various components on separate machines. With this sort of setup, the application server resides in a demilitarized zone within a secure firewall, while the WebSEAL setup resides outside the firewall. Direct access to deployed applications is not available in a production setup. Download the installer packages of IBM Tivoli Access Manager for e-business from IBM PartnerWorld. The required files are: C1AW6ML.zip: IBM Tivoli Access Manager for e-business Directory Server for Windows (1 of 3) version 6.1, Multilingual C1AW7ML.zip: IBM Tivoli Access Manager for e-business Directory Server for Windows (2 of 3) version 6.1, Multilingual C1AV9ML.zip: IBM Tivoli Access Manager for e-business Base for Windows version 6.1, Multilingual C1AW2ML.zip: IBM Tivoli Access Manager for e-business Web Security for Windows version 6.1, Multilingual Download and extract all the packages to the C:\installers folder. Installing IBM Tivoli Access Manager for e-business This section explains how to install and configure IBM Tivoli Access Manager for e-business WebSEAL components. Base system installation Before you install and configure an IBM Tivoli Base system, you must perform the following installation tasks (as required): Setting up an Access Manager Java runtime system Setting up IBM Tivoli Directory Server Applied Technology 5
Setting up a policy server Setting up an authorization server Setting up an Access Manager Java runtime system To set up IBM Java runtime: 1. Log in to your local computer as an administrator and navigate to the following folder: C:\installers\C1AW6ML\windows\JDK 2. Double-click ibm-java2-sdk-50-win-i386.exe. An InstallShield wizard is started and the Choose Setup Language dialog box is displayed. 3. Select a language from the list, and click OK. The next page displays the InstallShield wizard. 4. Click Next. Click Yes on the License Agreement screen. The Choose Destination Location screen is displayed. Applied Technology 6
5. Retain the default destination folder, and click Next. The Setup Type screen is displayed. Applied Technology 7
6. Select the Typical option and click Next. The Question dialog box is displayed. 7. Click Yes to install IBM Java runtime as the system JVM. The Start Copying Files screen is displayed. 8. Click Next to continue. The Setup status screen is displayed and the InstallShield wizard copies the required files. 9. Click Next after the installation is completed. The Browser Registration screen is displayed. Applied Technology 8
10. Retain the selection of the Microsoft Internet Explorer option, and click Next. The InstallShield Wizard Complete screen is displayed. 11. Click Finish to close the InstallShield wizard. Applied Technology 9
12. Add the IBM JRE s bin to path. In this example, we used C:\Program Files\IBM\Java50\jre\bin. 13. Set the JAVA_HOME environmental variable to point to C:\Program Files\IBM\Java50. Setting up IBM Tivoli Directory Server Registry server You must set up a registry server to use with IBM Tivoli Access Manager. The install_ldap_server installation wizard simplifies the IBM Tivoli Directory Server system setup as the registry server. The installation wizard installs and configures the following components in the specified order: IBM Global Security Kit (GSKit) IBM DB2 Universal Database, Enterprise Server Edition IBM Tivoli Directory Server (client, server, and proxy server) This installer enables Secure Sockets Layer (SSL) security. The installer automatically generates an SSL key database (am_key.kdb) and a self-signed certificate. However, you can override this SSL key database by using your key database during the installation. To install and configure the Tivoli Directory Server as a registry server: 1. Navigate to C:\installers\C1AW6ML and double-click install_ldap_server.bat. A dialog box is displayed. Applied Technology 10
2. Select the language you wish to use, and click OK. The welcome screen is displayed. Applied Technology 11
3. Click Next. The Software License Agreement screen is displayed. Select the I accept the terms in the license agreement option, and click Next. The next screen is displayed. Applied Technology 12
4. Retain the default directory where IBM DB2 will be installed, and click Next. The next screen is displayed. Applied Technology 13
5. Retain the default directory where IBM Global Security Kit will be installed, and click Next. The next screen is displayed. Applied Technology 14
6. Retain the default directory where IBM Tivoli Directory Server will be installed, and click Next. The next screen is displayed. 7. Specify the relevant database information to configure the IBM Tivoli Directory Server: 1. Specify the password for the default DB2 administrator (db2admin). 2. Accept the other default values. Applied Technology 15
8. Click Next. The next screen is displayed. 9. Type a valid DN name or accept the default name (cn=root) and set the administrator password. Enter a user-defined suffix to maintain the user and group data (for example, o=tam, c=us). Accept the other default values, and click Next. The next screen that displays prompts you to specify database information. Applied Technology 16
10. Use the default values for the ports. State the full path to the SSL key file, provide the key file password, and present the certificate label. 11. Retain the selection of the Create SSL key file checkbox. When this option is selected, the installation wizard automatically creates an SSL key database and a self-signed certificate to provide SSL security. However, you can override this option by creating key database files and certificates. This step is useful to overcome certificate-related issues in Unified Client Facilities (UCF) SSL validation. For instructions on how to generate a key file database and certificate, see Appendix: ikeyman utility. Applied Technology 17
12. Click Next. The next screen displays describes the disk space requirements and availability. Applied Technology 18
13. Click Next. The next screen displays the configuration options that you have selected. 14. Click Next. This will install the various prerequisite components, if they are not already available. If you encounter an error while using the downloaded installer packages, click Finish, and start the installation again. Double-click install_ldap_server.bat and repeat all the steps you performed earlier. Applied Technology 19
Applied Technology 20
After installing the files on disk 1, the wizard prompts you to insert disk 2. 15. Enter the path to the contents of disk 2. An example is C:\installers\C1AW7ML. Applied Technology 21
16. Click Next. This initiates the IBM Tivoli Directory Server installation. 17. After the installation is complete, the wizard prompts you with a message indicating that the installation will continue after the computer is restarted. Click Next to restart your computer. 18. Log in to the computer after it starts. An installation wizard prompts you to select the language you wish to use. 19. Select the language to use and click OK. 20. Click Next to continue with the installation. The IBM Tivoli Directory Server installation and configuration start. When IBM Tivoli Directory Server is successfully installed and configured, the next screen is displayed. Applied Technology 22
21. Click Finish to close the installation wizard. The next step is to set up the policy server. Setting up a policy server After you have successfully installed the registry server, you need to install the IBM Tivoli Access Manager policy server. The following steps guide you through the installation of the policy server using a wizard (install_ammgr) and the configuration of the server with an LDAP type of registry. The wizard installs and configures the following components required for the policy server: IBM Global Security Kit (GSKit) IBM Tivoli Directory Server client (as needed) Tivoli Security Utilities Access Manager License Access Manager Runtime Access Manager Policy Server Applied Technology 23
To install the policy server: 1. Log in to the local machine as an admin user, and navigate to the installer location (for example, C:\installers\C1AV9ML). 2. Double-click install_ammgr.exe to start the installation. 3. Select the language you wish to use, and click OK. The Welcome screen is displayed. 4. Click Next to continue. Read the license agreement, select the I accept the terms in the license agreement option, and click Next to continue. The Registry Selection screen is displayed. Applied Technology 24
Applied Technology 25
5. Select the LDAP type of registry server setup for IBM Tivoli Access Manager, and click Next. The next screen specifies the folder where you must install Tivoli Security Utilities. Applied Technology 26
6. Accept the default install location, and click Next. The next screen specifies the folder where you must install the runtime. Applied Technology 27
7. Accept the default installation location, and click Next. The Tivoli Common Directory Information screen is displayed. Applied Technology 28
8. Accept the default directory name and click Next. The next screen will help you configure the runtime. Applied Technology 29
9. Specify the registry server details configured such as hostname and port, and click Next. The next screen that displays continues to configure the runtime. Applied Technology 30
10. Select the Enable SSL with the registry server checkbox to enable SSL with the registry server and click Next. The next screen helps you to configure SSL with the registry server. 11. Provide the path to the SSL key database file configured during the registry server installation. Provide the SSL key file password and certificate label provided earlier, and click Next. The next screen that is displayed configures the policy server. Applied Technology 31
12. Specify a password for the Tivoli Access Manager administrator user. This administrator user is the security master with ID sec_master. Ensure that this password meets the security requirements as enforced by the operating system. If you fail to provide an appropriate password, you would have to reconfigure the policy server later with an appropriate password. Click Next. The screen that displays allows you to specify additional configuration details. Applied Technology 32
13. Provide the LDAP administrator password and the LDAP management domain location DN as configured earlier, and click Next. The screen that displays allows you to set the format of user and group tracking information. Applied Technology 33
14. Select the Minimal option since you do not have an earlier version of Access Manager installed, and click Next. The next screen that displays allows you to enable federal information processing standards. Applied Technology 34
15. Do not select the Enable Federal Information Processing Standards (FIPS) checkbox. Click Next. The next screen provides the available disk space and the space required details. Applied Technology 35
16. Click Next. The next screen displays the configuration option that you selected. Applied Technology 36
17. Review the configuration options and click Next to approve your choices. Click Back if you want to change a value in any of the earlier screens. Click Next. The next screen displays the installer that installs components such as Access Manager Runtime. 18. The installer informs you that you need to restart your computer in order to continue the installation. Click Next to restart the system. 19. Log in to the computer after it is restarted. The installation wizard starts automatically and prompts you to select a language. 20. Select a language and click OK. The installation wizard starts the LDAP server. The policy server installation continues and configures the Access Manager Runtime. Applied Technology 37
21. Click Finish to complete the installation. The status details of the installation are displayed. The next step is to set up an authorization server. Setting up an authorization server After you have successfully installed the policy server, you can set up an authorization server. The install_amacld installation wizard simplifies the setup of a Tivoli Access Manager Authorization Server system by installing and configuring the following components in the specified order: IBM Global Security Kit (GSKit) IBM Tivoli Directory Server client (as needed) Tivoli Security Utilities Access Manager License Access Manager Runtime Access Manager Authorization Server To set up the authorization server: 1. Log in to the local computer as an admin user and navigate to the installer location. For example, you can navigate to C:\installers\C1AV9ML\windows\PolicyDirector\Disk Images\Disk1. 2. Double-click setup.exe to start the installation. The Choose Setup Language screen is displayed. Applied Technology 38
3. Select the language you wish to use and click Next. The Welcome screen is displayed. 4. Click Next to start the installation. The License Agreement screen is displayed. Click Yes to accept the terms of the agreement and continue with the installation. The Select Packages screen is displayed. 5. Select the Access Manager Authorization Server component that is packaged with the installer, and click Next. The installation continues and a prompt notifies you when the installation has completed successfully. Applied Technology 39
6. Click OK. 7. Select Start > Programs > IBM Tivoli Access Manager > Configuration to start the Access Manager Configuration tool. The Access Manager Configuration dialog box is displayed. 8. Select the Access Manager Authorization Server that has not been configured, and click Configure. The Domain Information wizard is displayed. 9. Accept the default domain information, and click Next. The Policy Server Information screen is displayed. Applied Technology 40
10. Accept the default policy server hostname and port values, and click Next. The Administrator Information screen is displayed. 11. Specify the password for the sec_master administrator account you configured, and click Next. The Authorization Server Information screen is displayed. 12. Accept the default local hostname, and administration and authorization port values of the authorization server, and click OK. The Access Manager Authorization Server configuration is started. 13. After the Access Manager Authorization Server is configured, the Access Manager Configuration dialog box is displayed. Click Close. Applied Technology 41
After the Tivoli Access Manager Authorization Server is installed successfully, the next step is to install IBM WebSEAL. Installing the Web security system The install_amweb installation wizard simplifies the setup of a Tivoli Access Manager WebSEAL system by installing and configuring the following components in the specified order: IBM Global Security Kit (GSKit) IBM Tivoli Directory Server client (as needed) Tivoli Security Utilities Access Manager License Access Manager Runtime Access Manager Web Security Runtime Access Manager WebSEAL Setting up the Access Manager WebSEAL After you have successfully installed the authorization server, you can install the Tivoli Access Manager WebSEAL system. Ensure that you have started the following services before you install the WebSEAL system: Access Manager Authorization Server Access Manager Auto-Start Service (This starts the policy server.) Access Manager Policy Server IBM DB2 and IBM Tivoli Directory Server To install the Access Manager WebSEAL: 1. Log in to the local computer as an admin user and navigate to the installer location. For example, navigate to C:\installers\C1AW2ML. 2. Double-click install_amweb.exe to start the installation. The InstallShield wizard is started and a dialog box prompts you to select a language. Applied Technology 42
3. Select the language you want to use, and click OK. The Welcome screen is displayed. 4. Click Next to continue with installation. The Software License Agreement is displayed. Select the I accept the terms in the license agreement option, and click Next. The next screen that displays prompts you to specify the directory where the Web security runtime must be installed. Applied Technology 43
5. Accept the default installation location for the IBM Tivoli Access Manager Web Security Runtime, and click Next. The next screen prompts you to specify the directory where WebSEAL must be installed. Applied Technology 44
6. Accept the default installation location for the IBM Tivoli Access Manager WebSEAL, and click Next. The next screen prompts you to specify the WebSEAL instance name. 7. Accept the default instance name or provide a relevant name, and click Next. The next screen prompts you to specify the Tivoli Access Manager domain. Applied Technology 45
8. Accept the default domain or provide a relevant domain name, and click Next. The next screen prompts you to provide Tivoli Access Manager administration information and WebSEAL information. 9. Specify the relevant Tivoli Access Manager Administration information that you need in order to configure WebSEAL, and click Next. The next screen allows you to choose to enable SSL communication. Applied Technology 46
10. Select the Enable SSL with the LDAP server checkbox, and click Next. The next screen prompts you to specify information to enable SSL communication. Applied Technology 47
11. Provide the SSL key full file path, SSL key file password, and the certificate label that you have configured. Provide the SSL port configured earlier with the LDAP server, and click Next. The next screen prompts you to choose to enable HTTP and HTTPS access. 12. Select the Enable HTTP access and Enable HTTPS access checkboxes, and click Next. The next screen prompts you to specify the HTTP port. Applied Technology 48
13. Accept the default HTTP port, and click Next. The next screen prompts you to specify the HTTPS port. 14. Accept the default HTTPS port, and click Next. The next screen prompts you to specify the root directory location of document resources secured by IBM Tivoli Access Manager WebSEAL. Applied Technology 49
15. Accept the default directory location, and click Next. The next screen describes details about the available disk space and the space required for the installation. 16. Click Next. The next screen lists the configuration options that you selected in the previous steps. Applied Technology 50
17. Review the configuration options, and click Next. You can also click Back to reconfigure the options. 18. The installation wizard notifies you that the installation will continue after the computer is restarted. Click Next to restart the system. Applied Technology 51
19. Log in to the computer after it restarts. The installation wizard displays automatically and a dialog box prompts you to select the language that you want to use. 20. Select a language, and click OK. The Tivoli Access Manager Installation wizard starts the LDAP server. 21. After the LDAP server is started, the IBM Tivoli Access Manager WebSEAL installation continues. 22. After the installation is completed, click Finish to close the installation wizard. After this step, the installation of IBM Tivoli Access Manager for WebSEAL is successfully completed. Configuring the WebSEAL system After installing IBM Tivoli Access Manager WebSEAL, the next step is to configure WebSEAL as a reverse proxy server to work with EMC Documentum WDK-based applications. Creating a WebSEAL junction A WebSEAL junction is a connection point between WebSEAL and back-end servers. The back-end server can be another WebSEAL server or a third-party application server. The web space of the back-end server is connected to WebSEAL through specially designed mount points called junctions. WebSEAL identifies a junction using a junction cookie, or through dynamically generated server-related URLs. To create a WebSEAL junction: 1. Start the pdadmin utility. 2. Add the location of the pdadmin utility (for example, C:\Program Files\Tivoli\Policy Director\bin in our case) to the system path. Applied Technology 52
3. Start pdadmin and log in as sec_master using the following command: pdadmin a sec_master p password. Note: You must specify your password as part of the command. 4. The server list command lists the names all of the available server instances. 5. Create a junction using the following command: server task default-webseald-webseal.dctmlabs.com create t tcp -s -j -e utf8_uri -c iv_user -p 8080 -h 10.31.169.74 /myjunction The default-webseald-webseal.dctmlabs.com is the server instance name obtained from the previous command. Provide the hostname (for example, 10.31.169.74 here) and port (for example, 8080) of the application server computer where the web application is deployed. 6. Access the application using a reverse proxy server. You can access a web application deployed on an application server installed on 10.31.169.74 and running on port 8080 using the following URL: http://10.31.169.74:8080/taskspace. However, in a production environment, the application server is set up in a secure zone behind a firewall and the only way to access it is through a reverse proxy server. You can also access the same application using WebSEAL as a reverse proxy using the following URL: http://webseal:90/myjunction/taskspace (in HTTP mode - port is 90 by default and can be configured) and https://webseal/myjunction/taskspace (in HTTPS mode). Here, WEBSEAL is the hostname of the machine where WebSEAL is deployed. Documentum-specific configuration You must perform the following Documentum-specific configuration steps: 1. Content transfer specific configuration You must perform standard UCF configurations for using UCF through a proxy server. The UCF client anticipates a certificate that contains the hostname from which the certificate originated, during the SSL validation process. When you use the https mode in WebSEAL, ensure that a certificate with a hostname as the CN is generated and configured for use. For more information see Appendix: ikeyman utility. 2. WebSEAL URL rewriting WebSEAL modifies URLs to access back-end resources based upon the junction details you have provided. WebSEAL converts URLs by adding junction information to all requests including relative URLs to accomplish effective access to resources. However, in case of inline requests, this conversion is not effective, and leads to erroneous results. You can overcome this problem by using the junction map and performing the required configuration. Create a file called jmt.conf under C:\Program Files\Tivoli\PDWeb\www-default\lib and add a mapping, similar to: /myjunction /webtop/*, in the file. This mapping signifies that any inline Applied Technology 53
requests with a context URL conforming to the wild-card pattern /webtop/* must use /myjunction as the junction. Miscellaneous The following are useful commands: Starting and stopping WebSEAL net start <instance-name> To start on the command line net stop <instance-name> To stop on the command line Listing multiple WebSEAL server instances server list after logging into the pdadmin utility Listing all junctions associated with a server instance server task <instance-name> list Creating a junction server task <instance-name> create t tcp -s -j -e utf8_uri -c iv_user -p <port> -h <host> /<junction-name> Listing the properties of a junction server task <instance-name> show <junction-name> Reloading jmt.conf after an edit server task <instance-name> jmt load Switching between HTTP and HTTPS modes To change the default mode of access of WebSEAL, open the WebSEAL configuration file (websealddefault.conf located at C:\Program Files\Tivoli\PDWeb\etc in our case) and modify the following entry as needed: ba-auth. An example is ba-auth = https or ba-auth = http. Conclusion The IBM Tivoli Access Manager for e-business is successfully installed and configured as a reverse proxy server to work with EMC Documentum WDK web applications. References For more information about IBM Tivoli Access Manager for e-business see the IBM Tivoli Access Manager for e-business Installation Guide at http://publib.boulder.ibm.com/infocenter/tivihelp/v2r1/index.jsp. In the left pane, click the Access Manager for e-business link, expand the Installation and upgrade information link, and click the Installation Guide link for more information. Appendix: ikeyman utility The ikeyman utility creates key database files and certificates. Perform the following steps to create your own key database files and certificates for use with the Tivoli product suite. 1. Navigate to the directory C:\Program Files\IBM\Java50\jre\bin and double-click ikeyman.exe to open the ikeyman utility. Applied Technology 54
2. Select Key Database File > New to create a key database file. The New dialog box is displayed. 3. Select the CMS key database type, and provide a file name and path. Applied Technology 55
4. Click OK. The Password Prompt dialog box is displayed. 5. Set the password and click OK. 6. Select Create > New Self-Signed Certificate. The Create New Self-Signed Certificate dialog box is displayed. Applied Technology 56
7. Enter the hostname of the computer as the common name. Enter a key label, and click OK to create the self-signed certificate. 8. Configure the newly created certificate with WebSEAL. Edit the keyfile details in the WebSEAL configuration file (for example, webseald-default.conf here). Old configuration: webseal-cert-keyfile = C:/Program Files/Tivoli/PDWeb/www-default/certs/pdsrv.kdb # webseal-cert-keyfile-pwd = <password> webseal-cert-keyfile-stash = C:/Program Files/Tivoli/PDWeb/www-default/certs/pdsrv.sth webseal-cert-keyfile-label = WebSEAL-Test-Only New configuration: webseal-cert-keyfile = C:/Program Files/IBM/LDAP/V6.1/lib/my_key.kdb webseal-cert-keyfile-pwd = password #webseal-cert-keyfile-stash = C:/Program Files/Tivoli/PDWeb/www-default/certs/pdsrv.sth webseal-cert-keyfile-label = WebSEAL.dctmlabs.com Applied Technology 57