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

Transcription

1 White Paper ENABLING SINGLE SIGN-ON FOR EMC DOCUMENTUM WDK-BASED APPLICATIONS USING IBM WEBSEAL ON AIX 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

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

3 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 Setting up IBM Tivoli Access Manager Authorization Server Installing the web security system Setting up Tivoli Access Manager WebSEAL Configuring the WebSEAL system Creating a WebSEAL junction Configuring Webtop to enable WebSEAL authentication Configuring Privileged Documentum Foundation Classes using Documentum Administrator User creation in the target repository Documentum-specific configuration Configuring content transfer Rewriting WebSEAL URL Accessing the SSO-enabled Webtop application Miscellaneous Useful commands Conclusion References Appendix: ikeyman utility

4 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, multithreaded 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 WDKbased applications using IBM WebSEAL. WebSEAL authentication scheme The new authentication scheme, WebsealAuthenticationScheme, is created to support WebSEAL integration with WDK. 4

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

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 CZG8IML.zip IBM Tivoli Access Manager for e-business Directory Server for AIX (2 of 2) version 6.1, 6

7 CZG8EML.zip Multilingual 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 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 7

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

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

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

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

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

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

14 8. Click Next. 14

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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 39

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. 4. After the splash screen displays, click Next to start the installation. 40

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

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

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

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

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

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

47 11. Accept the default HTTP port and click Next. 47

48 12. Accept the default HTTPS port and click Next. 48

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

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

51 15. Review the configuration options and click Next. 51

52 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: 52

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 create t tcp -s -j -e utf8_uri -c iv_user -p h /myjunction Note: The default-webseald is the server instance name obtained from the previous command. 6. Specify the hostname (for example, ) 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. 53

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

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

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

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

58 6. In the Privileged Client Properties dialog box, select the checkboxes for the following : Trusted Login Trusted Server Privilege 58

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

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

61 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 and is running on port 8080, access Webtop using the following URL: b. To access Webtop that is SSO-enabled using WebSEAL in HTTP mode, access the following URL: (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: (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. 61

62 Miscellaneous Useful commands Action Starting and stopping WebSEAL Checking the status of a WebSEAL instance Listing various WebSEAL server instances Listing all junctions associated with a server instance Creating a junction Deleting a junction Listing the properties of a junction Reloading jmt.conf after an edit Command pdweb start <instancename> pdweb stop <instancename> pdweb status instancename> server list (Command to execute after logging in to the pdadmin utility) server task <instancename> list server task <instancename> create t tcp -s -j - e utf8_uri -c iv_user -p <port> -h <host> /<junctionname> server task defaultwebseald delete /myjunction server task <instancename> show <junctionname> server task <instancename> 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 62

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

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. 3. Create a new key database file by selecting Key Database File > New. 64

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

66 5. Set the password and click OK. 66

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