enabling single sign-on for emc documentum wdk … ibm tivoli access manager for e-business base for...

White Paper

Abstract

This white paper explains how you can use the IBM Tivoli Access Manager for e-business WebSEAL SSO solution in your EMC® Documentum® Web Development Kit-based applications. EMC Documentum can integrate with WebSEAL if your Documentum application supports the single sign-on (SSO) mechanism.

March 2011

ENABLING SINGLE SIGN-ON FOR EMC DOCUMENTUM WDK-BASED APPLICATIONS USING IBM WEBSEAL ON AIX

2 Enabling Single Sign-On for EMC Documentum WDK-based Applications using IBM WebSEAL on AIX

Copyright © 2011 EMC Corporation. All Rights Reserved. EMC believes the information in this publication is accurate 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 h8203


Table of Contents

Executive summary.................................................................................................. 4

Audience ............................................................................................................................ 4

WebSEAL authentication scheme ............................................................................. 4

Authentication sequence ......................................................................................... 5

Requirements .......................................................................................................... 6

Installing IBM Tivoli Access Manager for e-business ................................................. 7

Base system installation .................................................................................................... 7

Setting up an Access Manager Java runtime system ....................................................... 7

Setting up IBM Tivoli Directory Server (as the Registry Server) ........................................ 8

Setting up IBM Tivoli Access Manager Policy Server ...................................................... 16

Setting up IBM Tivoli Access Manager Authorization Server .......................................... 29

Installing the web security system ......................................................................... 39

Setting up Tivoli Access Manager WebSEAL ............................................................ 40

Configuring the WebSEAL system ........................................................................... 52

Creating a WebSEAL junction ............................................................................................ 52

Configuring Webtop to enable WebSEAL authentication ................................................... 53

Configuring Privileged Documentum Foundation Classes using Documentum Administrator .............................................................................................. 54

User creation in the target repository ................................................................................ 59

Documentum-specific configuration ................................................................................. 60

1. Configuring content transfer .................................................................................... 60

2. Rewriting WebSEAL URL ........................................................................................... 61

Accessing the SSO-enabled Webtop application .............................................................. 61

Miscellaneous ....................................................................................................... 62

Useful commands ............................................................................................................ 62

Conclusion ............................................................................................................ 63

References ............................................................................................................ 63

Appendix: iKeyman utility ...................................................................................... 64


Executive summary This white paper explains how you can use the single sign-on (SSO) solution supported by IBM Tivoli Access Manager for e-business WebSEAL in your EMC® Documentum® application. Documentum Webtop can integrate with WebSEAL if your Documentum application supports the SSO mechanism.

This paper covers the process of installing and configuring WebSEAL, and integrating its SSO solution with the Documentum Webtop application.

IBM Tivoli Access Manager for e-business WebSEAL is a high-performance, multi-threaded Web server that applies a fine-grained security policy to a protected network. WebSEAL incorporates back-end Web application server resources into its security policy, and can provide SSO solutions. WebSEAL acts as a reverse web proxy by receiving HTTP or HTTPS requests from a Web browser and delivering content from its own Web server or from back-end Web application servers. Requests passing through WebSEAL are evaluated by its authorization service to determine whether the user is authorized to access the requested resource.

Documentum Web Development Kit (WDK) integrates with WebSEAL and provides seamless support for its SSO authentication. WDK integrates with WebSEAL using its pluggable authentication framework similar to other SSO solutions. The configuration parameters are part of the app.xml file.

This integration will support DRL and VirtualLink features. Webtop version 6.7 is certified with form-based WebSEAL authentication and there is no plan to support certificate-based authentication.

Audience

This white paper is intended for IT architects, support professionals, and customers.

The paper contains detailed steps to enable the SSO solution for Documentum WDK-based applications using IBM WebSEAL.

WebSEAL authentication scheme The new authentication scheme, WebsealAuthenticationScheme, is created to support WebSEAL integration with WDK.


Figure 1. WebsealAuthenticationScheme

WebsealAuthenticationScheme implements IAuthenticationScheme to plug in to the WDK authentication framework. The WDK authentication framework invokes the configured authentication schemes for a request that requires a DFC session. The AuthenticationSchemes.properties file defines the order in which pluggable authentication schemes are invoked. The respective authentication scheme decides the capability to authenticate based on the data available with the HTTP request or HTTP session object.

WebsealAuthenticationScheme looks for the “iv-user” request header attribute. This request header attribute specifies the username that WebSEAL has authenticated. As per WebSEAL recommendations, the request reaching WDK must be trusted as authenticated and authorized. WDK will not validate the user/request.

If the default repository is configured for WebSEAL, WebsealAuthenticationScheme will use the DFC Principal Authentication privilege support to request a DFC session. In the absence of the default repository, WebsealAuthenticationScheme will launch the existing SSOLogin component to display the repository selection page. The repository selection page enables the end user to select the repository to connect. When the repository selection page is submitted, this then allows WebsealAuthenticationScheme to request a DFC session to the selected repository.

Authentication sequence The authentication call sequence with the repository selection page is depicted in Figure 2.


Figure 2. Authentication call sequence with the repository selection page

Requirements Before integrating IBM WebSEAL with Documentum WDK applications, you must ensure the following prerequisites are satisfied:

A fresh AIX machine

The 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, on a production setup the various components are installed on separate machines. In a production setup the application server resides in a demilitarized zone within a secure firewall while the WebSEAL setup is available outside the firewall. Direct access to deployed applications is not available.

Download and extract all installer packages of IBM Tivoli Access Manager for e-business from IBM Partnerworld. The required files are as follows:

C1AV3ML.zip IBM Tivoli Access Manager for e-business Directory Server for AIX (1 of 1) version 6.1, Multilingual

CZG8IML.zip IBM Tivoli Access Manager for e-business Directory Server for AIX (2 of 2) version 6.1,


Installing IBM Tivoli Access Manager for e-business This section explains the process of installing and configuring IBM Tivoli Access Manager for e-business WebSEAL components.

Base system installation

Before you install and configure the IBM Tivoli base system, you must perform the following installation tasks:

Setting up an Access Manager Java runtime system

Setting up IBM Tivoli Directory Server

Setting up IBM Tivoli Access Manager Policy Server

Setting up IBM Tivoli Access Manager Authorization Server

Setting up an Access Manager Java runtime system

To set up IBM Java runtime: 1. Navigate to the following path: /home/webseal/CZG8IML/usr/sys.

2. Run the following command: installp -acgYXd ./inst.images Java5.ext Java5.samples Java5.sdk

Java5.source

Multilingual

CZG8EML.zip IBM Tivoli Access Manager for e-business Base for AIX version 6.1, Multilingual

CZG8FML.zip IBM Tivoli Access Manager for e-business Web Security for AIX version 6.1, Multilingual


Setting up IBM Tivoli Directory Server (as the Registry Server)

The install_ldap_server installation wizard simplifies the installation of IBM Tivoli Directory Server as the Registry Server. It installs all prerequisite software and the following components in the specified order:

a. IBM Global Security Kit (GSKit)

b. IBM DB2 Universal Database, Enterprise Server Edition

c. IBM Tivoli Directory Server (client, server, and proxy server)

The install_ldap_server installation wizard enables SSL security. The wizard also generates an SSL key database (am_key.kdb) and a self-signed certificate, automatically. You can override this step by using your own key database during the installation.

Prerequisites

Install the Hummingbird or XManager software on your desktop.

Log in to the AIX machine, and set the display on your local machine to launch installation wizards on your local machine. Run the following command to set the display: export DISPLAY=IP Address:0.0

Ensure that you specify the IP address of your local machine where the installer will be started.

To install and configure IBM Tivoli Directory Server as the Registry Server: 1. Navigate to /home/webseal/C1AV3ML and run the program

install_ldap_server.sh. The installation wizard is launched.

2. Select a language and click OK.


3. After the splash screen displays, click Next to start the installation.


4. In the Software License Agreement page, accept the license terms and click Next.


5. Set the password for the default DB2 administrator (ldapdb2) to configure the IBM Tivoli Directory Server. Accept the other default values provided and click Next.


6. Specify the following details:

Password for the database administrator ID. An example is cn=root

User-defined suffix of your choice (o=cma,c=us)

Your fully qualified hostname or IP address (check the full computer name in the System Properties dialog box of the computer)


7. Specify the SSL key file password and leave the other options to default values. The installation wizard automatically creates an SSL key database and a self-signed certificate to provide Secure Socket Layer (SSL) security. You can override this step by creating your own key database files and certificates. This step is useful to overcome certificate-related issues during UCF SSL validation. For instructions on generating a key file database and certificate, see the Appendix.


8. Click Next.


9. Check the available disk space and click Next.

10. Review the configuration options and click Next.

11. Verify the installation summary, and click Finish to close the installation wizard.


Setting up IBM Tivoli Access Manager Policy Server

After the Registry Server is successfully installed, install the Tivoli Access Manager Policy Server. The following steps guide you through the process of installing the Policy Server using the install_ammgr program and configuring it with an LDAP type of registry. This program installs and configures all components required for the Policy Server:

1. Log in to the AIX machine with root access and navigate to the installer location. An example is /home/webseal/CZG8EML.

2. Run the program install_ammgr.sh program to start the installation.



5. In the InstallShield Wizard for IBM Tivoli Access Manager Policy Server, click Next to continue with the installation.


7. Select the LDAP Registry Server setup for IBM Tivoli Access Manager and click Next.


8. Accept the default values in the Tivoli Common Directory Information page and click Next.


9. Configure the Registry Server details such as hostname and port. In the example, accept the defaults or enter the hostname and click Next.


10. Specify a password for the Tivoli Access Manager Administrator user and click Next.


11. Provide the LDAP administrator password and the LDAP management location DN as configured earlier, and click Next.


12. Select the user and group tracking information format as Standard, and click Next.


13. Select the Enable SSL with the registry server option, to enable SSL with the Registry Server and click Next.


14. Provide the path to the SSL key database file configured during Registry Server installation. Provide the SSL key file password and certificate label provided earlier and click Next.


15. Ensure that the FIPS option is not selected and click Next.


16. View the disk space requirement and availability details and click Next.


17. Review the configuration options and click Next. The products listed in this page are installed.


18. Verify the installation summary and click Finish to close the installation wizard.

Setting up IBM Tivoli Access Manager Authorization Server

After you have successfully installed the Policy Server, you can set up the Authorization Server.

The install_amacld.sh program simplifies the setup of the Tivoli Access Manager Authorization Server.

To set up Authorization Server: 1. Log in to the AIX machine with root access and navigate to the installer location,

for example, /home/webseal/CZG8EML.

2. Run the install_amacld.sh program to start the installation.




5. In the InstallShield Wizard for IBM Tivoli Access Manager Authorization Server click Next to continue with the installation.


7. Configure the policy server details such as hostname and port. In the example, accept the defaults or enter the hostname and click Next.


8. Accept the default domain and set the password for the sec_master administrator account you configured. In addition, accept the default values for the other fields and click Next.


9. Select the Enable SSL with the registry server option to enable SSL communication with the Registry Server and click Next.


10. Provide the path to the SSL key database file configured during Registry Server installation. Provide the SSL key file password and certificate label provided earlier and click Next.


11. View the disk space requirement and availability details and click Next.


12. Review the configuration options and click Next. The products listed in this page are installed.


13. Click Next to proceed with the installation.

14. When the installation is complete, verify the installation summary and click Finish to close the installation wizard.


Installing the web security system The install_amweb program simplifies the setup of the 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) IBM Tivoli Security Utilities IBM Tivoli Access Manager License IBM Tivoli Access Manager runtime IBM Tivoli Access Manager web security runtime IBM Tivoli Access Manager WebSEAL


Setting up Tivoli Access Manager WebSEAL After installing the Authorization Server, you can install the Tivoli Access Manager WebSEAL system. Ensure that the following services are running before you install WebSEAL:

IBM DB2 and IBM Tivoli Directory Server

IBM Tivoli Access Manager Policy Server

IBM Tivoli Access Manager Authorization Server

To install IBM Tivoli Access Manager WebSEAL: 1. Log in to the AIX machine as a root user and navigate to the installer location, for

example, /home/webseal/CZG8FML.

2. Run the install_amweb program. The InstallShield Wizard launches.




6. Accept the default instance name to configure WebSEAL, or specify a name for the instance and click Next.


7. Specify the Tivoli Access Manager Administration information to configure WebSEAL, and click Next.


8. Select the Enable SSL with the LDAP server option to enable SSL with the LDAP server, and click Next.


9. Provide the SSL key file path, SSL key file password, and the certificate label configured earlier, and click Next.


10. Enable HTTP access and HTTPS access for WebSEAL, and click Next.


11. Accept the default HTTP port and click Next.


12. Accept the default HTTPS port and click Next.


13. Accept the default root directory that contains the document resources secured by IBM Tivoli Access Manager WebSEAL and click Next.


14. Details about the available disk space and the required space for the installation are displayed. Click Next to continue.


15. Review the configuration options and click Next.


16. Verify the installation summary and click Finish to close the installation wizard.

Configuring the WebSEAL system After installing IBM Tivoli Access Manager WebSEAL, the next step is to configure WebSEAL to work with Documentum WDK applications (Webtop in the context of this paper).

Creating a WebSEAL junction

A WebSEAL junction is a connection point between WebSEAL and the 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 a junction. WebSEAL identifies a junction through a junction cookie or dynamically generated server-related URLs.

To create a WebSEAL junction: 1. Log in to the AIX machine where WebSEAL is installed.

2. Add the location of the pdadmin utility (/opt/PolicyDirector/bin in our case) to the system path.

3. Start pdadmin and log in as sec_master using the following command:


pdadmin –a sec_master –p password

4. Execute the “server list” command to list all available server instances.

5. Execute the following command to create a junction: “server task default-webseald-10.31.104.32 create –t tcp -s -j -e

utf8_uri -c iv_user -p 8080 -h 10.31.70.231 /myjunction”

Note: The default-webseald-10.31.104.32 is the server instance name obtained from the previous command.

6. Specify the hostname (for example, 10.31.70.231) and port (for example, 8080) of the application server machine where the Web application is deployed.

Configuring Webtop to enable WebSEAL authentication 1. Open wdk/app.xml.

2. Set the value of the user_header tag to iv-user within the authentication tag: <authentication>

<webseal_config>

<user_header>iv-user</user_header>

</webseal_config>

</authentication>

3. Change the sequence in which the repository is invoked in the WEB-INF/classes/com/documentum/web/formext/session /AuthenticationSchemes.Properties file as follows, and restart the server: scheme_class.1=com.documentum.web.formext.session.WebsealSSOAuthentic

ationScheme

scheme_class.2=com.documentum.web.formext.session.DocbaseLoginAuthent

icationScheme

scheme_class.3=com.documentum.web.formext.session.TicketedAuthenticat

ionScheme

scheme_class.4=com.documentum.web.formext.session.RSASSOAuthenticatio

nScheme

scheme_class.5=com.documentum.web.formext.session.SSOAuthenticationSc

heme

scheme_class.6=com.documentum.web.formext.session.KerberosSSOAuthenti

cationScheme

scheme_class.7=com.documentum.web.formext.session.UserPrincipalAuthen

ticationScheme

scheme_class.8=com.documentum.web.formext.session.SavedCredentialsAut

henticationScheme.


Configuring Privileged Documentum Foundation Classes using Documentum Administrator

In an enterprise environment, applications sometimes authenticate users using an external authentication mechanism that is not accessible to Content Server. Such authenticated users must be able to log in to Content Server directly. Currently, the Principal Mode in DFC uses a superuser on a specified repository to obtain the log in the ticket for the users. The password of the superuser must be stored in the application environment, which may pose a security problem. Since Content Server supports the Principal Authentication Privilege for privileged DFC clients, the feature can be extended to support Principal Mode.

Privileged DFC is configured using Document Administrator.

DA provides the Web interface to register and add a Privileged DFC of a Documentum application to the repository.

To register a Privileged DFC of the Webtop application to the target repository:

1. Log in to the target repository using Documentum Administrator.

2. Select the Privileged Clients node in the Navigation pane that lists registered Privileged DFC clients.


3. Click Manage Clients and select the DFC instance associated with your application (for example, Webtop) and add the instance to the repository. Click OK.


4. Right-click the new DFC client you added to the repository, and select the Approve Privilege option.


5. Right-click the registered DFC client and select Properties. The Privileged Client Properties dialog box displays.


6. In the Privileged Client Properties dialog box, select the checkboxes for the following :

Trusted Login

Trusted Server Privilege


User creation in the target repository 1. Log in to Documentum Administrator and select User Management > Users and

select File > New User.


2. Create the same user you configured in Tivoli Directory Server in the target repository by selecting the User Source as “Inline Password” and by giving the required user privileges.

Documentum-specific configuration

You must perform the following Documentum-specific configurations steps.

1. Configuring content transfer

Standard UCF configurations must be performed for using Webtop 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 the hostname as the CN is generated and configured for use. For instructions on creating key database files and certificates, see Appendix: iKeyman utility.

2. Rewriting WebSEAL URL

WebSEAL modifies URLs to access back-end resources as per junction details. To enable effective access to resources WebSEAL converts URLs by adding junction information to all requests including relative URLs. However, this conversion is not effective in inline requests resulting in erroneous results. This problem can be overcome using the junction map and performing the required configuration.

Create a file called jmt.conf in the /opt/pdweb/www-default/lib folder and add a mapping similar to “/myjunction /webtop/*” in the file. The mapping signifies that any inline request with a context URL conforming to the wild-card pattern /webtop/* must use /myjunction as the junction.

Accessing the SSO-enabled Webtop application

Perform the steps provided in this section to access the SSO-enabled Webtop application.

To access the Webtop application: 1. Access Webtop using one of the following scenarios:

a. If the Webtop application is deployed on an application server that is installed on 10.31.70.231 and is running on port 8080, access Webtop using the following URL: http://10.31.70.231:8080/webtop.

b. To access Webtop that is SSO-enabled using WebSEAL in HTTP mode, access the following URL: http://aix32:80/myjunction/webtop (in HTTP mode, port is 80 by default, which is configurable).

c. To access Webtop that is SSO-enabled using WebSEAL in HTTPS mode, access the following URL: https://aix32:443/myjunction/ (in HTTPS mode, port is 443 by default).

2. Click Yes in the Security Alert dialog box.

3. Enter your username and password in the WebSEAL Login dialog box.

4. Select a repository in the Repository list.

5. Click OK to log in to Webtop.

http://10.31.70.231:8080/webtop

http://aix32/myjunction/webtop

https://aix32/myjunction/taskspace


Miscellaneous

Useful commands

Action Command

Starting and stopping WebSEAL pdweb start <instance-name>

pdweb stop <instance-name>

Checking the status of a WebSEAL instance

pdweb status instance-name>

Listing various WebSEAL server instances server list

(Command to execute after logging in to 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>

Deleting a junction server task default-webseald-10.31.105.180 delete /myjunction

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 authentication modes

By default, basic authentication is enabled. To enable forms-based authentication, open the WebSEAL configuration file (for example, webseald-default.conf) located in the /opt/pdweb/etc folder and search for the following entry: forms-auth = none


Change the entry as follows: forms-auth = both

This enables both the HTTP and HTTPS modes for accessing WebSEAL.

Forms-based authentication is supported in Webtop 6.7 and TaskSpace 6.7.

Switching between HTTP and HTTPS modes

To change the default mode of accessing WebSEAL, open the WebSEAL configuration file (webseald-default.conf in our case) located, for example, in the /opt/pdweb/etc folder and search for one of the following entries: forms-auth = https

OR forms-auth = http

Conclusion This white paper provides detailed steps with screenshots to install and configure IBM Tivoli Access Manager for e-business to work with EMC Documentum WDK web applications.

You can use the information to set up IBM Tivoli Access Manager for e-business effortlessly, and integrate with Documentum Webtop seamlessly. You can log in to Documentum Webtop using WebSEAL-based SSO on successful completion of the procedures described in this paper.

References For more information about IBM Tivoli Access Manager for e-business see the IBM Tivoli Access Manager for e-business Installation Guide available 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.

http://publib.boulder.ibm.com/infocenter/tivihelp/v2r1/index.jsp


Appendix: iKeyman utility Use the iKeyman utility to create 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.

To create your own key database files and certificates: 1. Navigate to the /opt/IBM/ldap/V6.1/java/jre/bin directory.

2. Run the ikeyman.sh program to open the iKeyman utility.

3. Create a new key database file by selecting Key Database File > New.


4. Select CMS as the key database type, and specify a filename and path.


5. Set the password and click OK.


6. Select Create > New Self-Signed Certificate to create a certificate.

7. Specify the hostname of the machine as the common name.

8. Enter a key label and click OK to create the self-signed certificate.

9. Configure the new certificate with WebSEAL by editing the keyfile details in the

WebSEAL configuration file.

Old configuration: webseal-cert-keyfile = /var/pdweb/www-default/certs/pdsrv.kdb

# webseal-cert-keyfile-pwd = <password>

webseal-cert-keyfile-stash = /var/pdweb/www-default/certs/pdsrv.sth

webseal-cert-keyfile-label = WebSEAL-Test-Only

New configuration: webseal-cert-keyfile = /opt/IBM/ldap/V6.1/lib/aix32.kdb

webseal-cert-keyfile-stash = = /var/pdweb/www-default/certs/pdsrv.sth

webseal-cert-keyfile-pwd = password

webseal-cert-keyfile-label = PDLDAP

enabling single sign-on for emc documentum wdk … ibm tivoli access manager for e-business base for...

Documents