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

(1)

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

(2)

2 Enabling Single Sign-On for EMC Documentum WDK-based Applications

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.

(3)

using IBM WebSEAL on AIX

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.

(5)

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.

(6)

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

(7)

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,

(8)

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.

(9)

using IBM WebSEAL on AIX 3. After the splash screen displays, click Next to start the installation.

(10)

using IBM WebSEAL on AIX 4. In the Software License Agreement page, accept the license terms and click Next.

(11)

using IBM WebSEAL on AIX 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.

(12)

using IBM WebSEAL on AIX 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)

(13)

using IBM WebSEAL on AIX 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.

(14)

using IBM WebSEAL on AIX 8. Click Next.

(15)

using IBM WebSEAL on AIX 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.

(16)

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. 3. Select a language and click OK.

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

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

(17)

using IBM WebSEAL on AIX 6. In the Software License Agreement page, accept the license terms and click

(18)

using IBM WebSEAL on AIX 7. Select the LDAP Registry Server setup for IBM Tivoli Access Manager and click

Next.

(19)

using IBM WebSEAL on AIX 8. Accept the default values in the Tivoli Common Directory Information page and

click Next.

(20)

using IBM WebSEAL on AIX 9. Configure the Registry Server details such as hostname and port. In the

example, accept the defaults or enter the hostname and click Next.

(21)

using IBM WebSEAL on AIX 10. Specify a password for the Tivoli Access Manager Administrator user and click

(22)

using IBM WebSEAL on AIX 11. Provide the LDAP administrator password and the LDAP management location

DN as configured earlier, and click Next.

(23)

using IBM WebSEAL on AIX 12. Select the user and group tracking information format as Standard, and click

Next.

(24)

using IBM WebSEAL on AIX 13. Select the Enable SSL with the registry server option, to enable SSL with the

Registry Server and click Next.

(25)

using IBM WebSEAL on AIX 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.

(26)

using IBM WebSEAL on AIX 15. Ensure that the FIPS option is not selected and click Next.

(27)

using IBM WebSEAL on AIX 16. View the disk space requirement and availability details and click Next.

(28)

using IBM WebSEAL on AIX 17. Review the configuration options and click Next. The products listed in this

page are installed.

(29)

using IBM WebSEAL on AIX 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. 3. Select a language and click OK.

(30)

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

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

(31)

(32)

using IBM WebSEAL on AIX 7. Configure the policy server details such as hostname and port. In the example,

accept the defaults or enter the hostname and click Next.

(33)

using IBM WebSEAL on AIX 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.

(34)

using IBM WebSEAL on AIX 9. Select the Enable SSL with the registry server option to enable SSL

communication with the Registry Server and click Next.

(35)

using IBM WebSEAL on AIX 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.

(36)

using IBM WebSEAL on AIX 11. View the disk space requirement and availability details and click Next.

(37)

using IBM WebSEAL on AIX 12. Review the configuration options and click Next. The products listed in this

(38)

using IBM WebSEAL on AIX 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.

(39)

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

(40)

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. 3. Select a language and click OK.

(41)

(42)

using IBM WebSEAL on AIX 6. Accept the default instance name to configure WebSEAL, or specify a name for

(43)

using IBM WebSEAL on AIX 7. Specify the Tivoli Access Manager Administration information to configure

(44)

using IBM WebSEAL on AIX 8. Select the Enable SSL with the LDAP server option to enable SSL with the LDAP

(45)

using IBM WebSEAL on AIX 9. Provide the SSL key file path, SSL key file password, and the certificate label

(46)

using IBM WebSEAL on AIX 10. Enable HTTP access and HTTPS access for WebSEAL, and click Next.

(47)

using IBM WebSEAL on AIX 11. Accept the default HTTP port and click Next.

(48)

using IBM WebSEAL on AIX 12. Accept the default HTTPS port and click Next.

(49)

using IBM WebSEAL on AIX 13. Accept the default root directory that contains the document resources

(50)

using IBM WebSEAL on AIX 14. Details about the available disk space and the required space for the

(51)

using IBM WebSEAL on AIX 15. Review the configuration options and click Next.

(52)

using IBM WebSEAL on AIX 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.

(53)

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:

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

(54)

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.

(55)

using IBM WebSEAL on AIX 3. Click Manage Clients and select the DFC instance associated with your application

(56)

using IBM WebSEAL on AIX 4. Right-click the new DFC client you added to the repository, and select the

(57)

using IBM WebSEAL on AIX 5. Right-click the registered DFC client and select Properties. The Privileged

(58)

using IBM WebSEAL on AIX 6. In the Privileged Client Properties dialog box, select the checkboxes for the

following : Trusted Login

(59)

User creation in the target repository

1. Log in to Documentum Administrator and select User Management > Users and select File > New User.

(60)

using IBM WebSEAL on AIX 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.

(61)

using IBM WebSEAL on AIX 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.

(62)

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

<instancename> create –t tcp s j -e utf8_uri -c iv_us-er -p <port> -h

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:

(63)

using IBM WebSEAL on AIX 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

(64)

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.

(65)

using IBM WebSEAL on AIX 4. Select CMS as the key database type, and specify a filename and path.

(66)

using IBM WebSEAL on AIX 5. Set the password and click OK.

(67)

using IBM WebSEAL on AIX 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