Deploying EMC Documentum WDK Applications with IBM WebSEAL as a Reverse Proxy

(1)

Deploying EMC Documentum

WDK Applications with IBM WebSEAL

as a Reverse Proxy

(2)

Deploying EMC Documentum WDK Applications with IBM WebSEAL as a Reverse Proxy

Applied Technology 2

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.

(3)

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

(4)

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 sign-on for Web applicatisign-ons.

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.

(5)

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

(6)

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.

(7)

(8)

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)

10. Retain the selection of the Microsoft Internet Explorer option, and click Next. The InstallShield Wizard Complete screen is displayed.

(10)

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.

(11)

(12)

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.

(13)

4. Retain the default directory where IBM DB2 will be installed, and click Next. The next screen is displayed.

(14)

5. Retain the default directory where IBM Global Security Kit will be installed, and click Next. The next screen is displayed.

(15)

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).

(16)

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

(17)

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.”

(18)

(19)

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.

(20)

(21)

After installing the files on disk 1, the wizard prompts you to insert disk 2.

(22)

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.

(23)

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:

(24)

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.

(25)

(26)

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.

(27)

6. Accept the default install location, and click Next. The next screen specifies the folder where you must install the runtime.

(28)

7. Accept the default installation location, and click Next. The Tivoli Common Directory Information screen is displayed.

(29)

(30)

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.

(31)

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.

(32)

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.

(33)

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.

(34)

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.

(35)

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.

(36)

(37)

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.

(38)

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 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.

(39)

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.

(40)

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.

(41)

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

(42)

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 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.

(43)

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.

(44)

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.

(45)

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.

(46)

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.

(47)

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.

(48)

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.

(49)

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.

(50)

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.

(51)

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.

(52)

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.

(53)

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.”

(54)

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 (webseald-default.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.

(55)

(56)

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.

(57)

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

Deploying EMC Documentum WDK Applications with IBM WebSEAL as a Reverse Proxy