Configuring Single Sign-On for Documentum Applications with RSA Access Manager Product Suite Abstract This white paper outlines the deployment and configuration of a Single Sign-On solution for EMC Documentum products using the RSA Access Manager product suite. The purpose of the document is to provide guidelines, suggestions, and verification check points and is not intended to be exact for all deployments. The document was based on a typical deployment environment used by the author. March 2011
Copyright 2011 EMC Corporation. All rights reserved. EMC believes the information in this publication is accurate as of its publication date. The information is subject to change without notice. The information in this publication is provided as is. EMC Corporation makes no representations or warranties of any kind with respect to the information in this publication, and specifically disclaims implied warranties of merchantability or fitness for a particular purpose. Use, copying, and distribution of any EMC software described in this publication requires an applicable software license. For the most up-to-date listing of EMC product names, see EMC Corporation Trademarks on EMC.com. All other trademarks used herein are the property of their respective owners. 2
Table of Contents 1. Executive summary... 4 2. Introduction... 4 2.1 Customer problems... 4 2.2 SSO use cases... 4 3 Audience... 5 4 Architecture description... 5 4.1 Overview... 5 4.2 SSO authentication process... 6 5 Deploying an SSO solution with RSA products... 4 5.1 Topology... 4 5.1.1 Prepare modules for deployment... 4 5.2 Deploy Access Manager... 5 5.3 Deploy Content Server... 7 5.4 Deploy Webtop... 8 5.5 Deploy Web Agent... 10 5.6 Protect resources... 11 5.7 Verify your deployments... 12 5.7.1 Verify Webtop... 12 6 DFS/CenterStage specific configuration... 14 7 Conclusion... 14 8 References and Related Documentation... 14 9 Definitions... 14 3
1. Executive summary The objective of this white paper is to help EMC Documentum customers deploy and configure a Single Sign-On (SSO) solution using the RSA Access Manager suite of products. This document outlines the deployment and configuration of these SSO products with Documentum products (Release D6 and beyond) in a typical deployment environment. Specifically, the document is based on a deployment used by the author and hence may not apply exactly to all customer deployments. 2. Introduction 2.1 Customer problems Some of the challenges related to SSO implementation for EMC Documentum products arise out of SSO requirements themselves and deployment complexity. This white paper addresses these issues: Centralized Authentication Multiple levels of authentication support at the enterprise level, working for applications such as EMC Documentum applications Centralized Authorization A centralized and common authorization management at enterprise level, based on configurable common users, entitlements, and so on without overwriting or compromising Documentum s authorization framework Integration of SSO servers with Documentum products Post-installation configuration of SSO products as well as Documentum products for an SSO solution Verification of such a deployment and validation of configuration Other challenges for customers, beyond the scope of this white paper and thus not addressed here, could include: Administration of SSO products Version upgradeability of the SSO environment (newer Documentum products, newer SSO products, or both) Auditability and report generation Broad platform supportability Supporting all commonly used application servers, web servers, directory servers, and so on that EMC Documentum products support Extensibility and scalability of the deployment for more applications, user bases, and repositories Additional authorization mechanisms Security over various protocols that Documentum products support Deployability in secure enterprise environments using firewalls, DMZs, proxies, and so on 2.2 SSO use cases Consider a deployment as follows: A customer wants to deploy an RSA-based SSO solution for Content Server and Webtop in a simple deployment model using a clustered application server and IIS web server 4
as a reverse proxy. The solution authenticates users against the RSA Access Manager (sharing an LDAP server with the Content Server) and subsequently against the Content Server. A few customer use cases that justify the need for an SSO solution with Documentum products are given below: SSO Use Cases 1. User has not logged in to the repository and invokes an application like Webtop. When the user logs in to a repository the first time, authentication is done using an SSO scheme. The user is authenticated against an SSO server (RSA Access Manager). 2. User has not logged in to the repository and invokes a DRL to a document using an application like Webtop. This prompts the user to enter SSO credentials once. 3. User invokes a virtual link, and this is subjected to SSO authentication. 4. While logged in to a repository, user adds another (visible) repository from Webtop. The SSO credentials are used and the user does not get prompted to log in again. 5. While being logged in to a repository (via Webtop), user invokes a DRL to the same repository from the desktop or from another product. The user does not get prompted to log in to the repository again. 6. While being logged in to a repository (via Webtop), user invokes a virtual link. The user is not prompted to log in again. 7. With multiple SSO-enabled applications, such as Webtop and Web Publisher, user is able to log in to Webtop providing credentials. Thereafter, the user is able to also log in to Web Publisher using the same authentication. 8. User is logged in to a repository using SSO. The SSO tokens had expired during a period of inactivity, thus forcing the user to authenticate again. 9. User is logged in to a repository using SSO. The SSO tokens had expired due to a Webtop session timeout, thus forcing the user to authenticate again. 10. User invokes Webtop deployed on a high availability (clustered) application server and is able to use the SSO credentials, even after application server fails over. 3 Audience The audience for this white paper is Documentum system administrators who help in deploying a Documentum SSO solution on any release (D6 and beyond) using the products from RSA. In addition to deployment expertise on Documentum products, the readers are expected to have some familiarity with deploying and configuring the RSA SSO products. 4 Architecture description 4.1 Overview In general, for implementations that use RSA products with Documentum products, the following steps are necessary for an SSO solution. 5
1. Installation of the SSO server to authenticate Documentum users. 2. Installation of the Documentum environment Content Server, Documentum application, and proxy servers. 3. Configuration of the RSA products, such as the Access Manager and the RSA Web Agent. This step also includes configuration of the Access Manager with users, resources, entitlements, and so on. 4. Configuration of the RSA plugin on Content Server. The Content Server based plug-in redirects authentication requests from users of the Documentum applications to the Access Manager. This also includes configuration of the Documentum application to use an external HTTP Server, and to customize the login procedure of the application to use SSO. 4.2 SSO authentication process An important piece of the authentication mechanism is the RSA Web Agent configuration. The Web Agent serves as a connector between the applications and the Access Manager so that requests to application servers can go through the HTTP server. The process of authentication, authorization, and validation is illustrated in the following graphic. 6
/webtop Web Agent Interception Form HTTP header Application Server (Webtop, DA, CenterStage ) Provide Ticket to Server Yes No Authenticated? (Has Ticket?) Content Server (CS) RSA Plugin Find User Entitlement on Application/Resource Inside Access Manager Yes Yes Ask for Authorization Ask for Authentication No Is Ticket Valid? Yes No Check user for resource entitlement Issue ticket for user Authentication path Authorization path 1. When the user tries to invoke the application URL (such as the Webtop or CenterStage URL), the URL is subject to RSA Access Manager Web Agent interception and eventual routing to the web server. 2. The Web Agent connects to the RSA Access Manager to authenticate the user against the user s entitlements on the application and the protected resource being accessed. For example, users accessing Webtop and anything beneath it can be authenticated. 3. After authentication by the RSA Access Manager, the Web Agent updates HTTP headers with SSO Tokens for the application to handle them. For instance, the Documentum application looks for the username in the HTTP_CT_REMOTE_USER part of the HTTP header and the ticket returned from authentication in the CTSESSION part of the header. 4. The application uses the tokens and the user name to establish a connection to a repository and to authenticate the user. 5. The RSA plugin on the Content Server, on its part, seeks authorization for the user from the Access Manager. The Content Server can do this only if the appropriate RSA plugin (named dm_rsa ) had been loaded when the Content Server was started. 6. If the authorization is validated by the Access Manager, the user is not prompted to login by the application again. If the authorization is invalidated, the application asks for authentication again. 3
5 Deploying an SSO solution with RSA products 5.1 Topology The customer wants to deploy an SSO solution using RSA products for Content Server and a Documentum application in a deployment model using a clustered application server and a proxy redirector in an intranet environment. The solution allows the users of one or more repositories to be authenticated against the RSA Access Manager. Client End User Proxy Web Server (AG) Web Server RSA Web Agent (WT) Application Server Documentum Application (WT) Application Server Documentum Application (AM) (CS) RSA Access Manager Content Server RSA Plugin LDAP DB 5.1.1 Prepare modules for deployment Note that the following deployment model is a sample one and deployments and composition of products on a single host may vary on customer sites. 1. Machine AM RSA Access Manager, LDAP server (it could be KDC instead of LDAP in some deployments) 2. Machine CS Content Server 3. Machine WT Application server and Webtop 4. Machine AG Web server and RSA Web Agent. (One could use Apache 2.2.x for the Web Server since it is easy to set up a reverse proxy with Apache web servers. Ensure that the version of RSA Web Agent that you install is supported with the web server that you use.) Verify that the machines can communicate with each other. For the deployment, you need binaries for the following software: Host Machine AM: am-host (am-host-ipaddress) Required binaries OS: Windows server (2003 server or 2008 server based on Access Manager version used) RSA Access Manager LDAP / Directory Server (Sun Directory server 5.2 SP4 was used in this deployment) 4
Host Required binaries Admin.gui.war Apache Tomcat application server 6 for Administrator Console Machine CS: Cs-host (cs-host-ip-address) OS: Windows or 2008 server (based on Content server support) Oracle database server/content Server RSA Plugin for the Content Server (This component is bundled with the Content Server) Machine AG: Ag-host (ag-host-ip-address) OS: Windows server (based on support from Apache web server and RSA web agent) Apache web server 2.2.x You must configure the web server as a reverse proxy to the application server RSA Access Manager Web Server Agent Machine WT: Wt-host (wt-host-ip-address) OS: Windows server (2003 or 2008, based on application server support) BEA Application server (single node as admin server). The actual version of the application server must be supported by Webtop version selected. Webtop 5.2 Deploy Access Manager Note: If you are using the domain KDC instead of LDAP, proceed to step 4. 1. Verify that the binaries are available for Access Manager and LDAP. 2. Install LDAP/Directory Server (which is Sun Directory Server 5.2 SP4 in our case) on the am-host as planned. Refer to the Directory Server for installation details. However, during installation, you may set parameters as follows: a. Enter the fully qualified computer name for directory server name (for example, amhost.dctmlabs.com). b. Choose Typical installation. c. Select the installation directory (for example, C:\Sun\MPS). d. Select the default directory server port as 389. This is the typical default LDAP port. However, it may be different in your environment; if so, make a note of the port number. e. Enter Userid and Password for Directory administrator. Make a note of this information. f. Enter Base DN: dc=dctmlabs,dc=com g. Enter Cn=Directory Manager h. Enter password: password i. Enter the Admin port as 390. This is the typical default administrator port. However, it may be different in your environment. 3. Verify directory server installation by invoking the Sun Directory Server admin console: 5
To start LDAP server (on Unix): i. Go to /var/sun/mps/slapd-am-host ii../start-slapd To start the admin console: a. Go to /var/sun/mps b. Start Admin Server:./start-admin c. Go to /var/sun/mps d. Start Console:./startconsole (enter userid and password for the admin console as set during installation) NOTE: You need to have X Display server running on your machine. 4. Install the RSA Access Manager. The Access Manager is installed under /opt/ctrust/server-<version> on a Unix machine. On Windows, the default install location is C:\Program Files\RSA\Access Manager Servers <version>. Note: If you do not want to set up a certificate server, use clear authentication instead of SSL (anon or auth). Modify the three conf files (dispatch.conf, aserver.conf and eserver.conf) by searching for anon and setting it to clear. Include commented out security settings, since they default to SSL. 5. Verify that an aserver.conf file is generated under conf folder. The folder is located at C:\Program Files\RSA\Access Manager Servers <version>\bin on a Windows machine and /opt/ctrust/server-60/conf on a Unix machine. 6. Start the Access Manager: a. On Unix: cd /opt/ctrust/server-60/bin Start the processes in the specified order:./dispatcher.sh start./aserver.sh start./eserver.sh start b. On Windows: Go to C:\Program Files\RSA\Access Manager Servers <version>\bin and run each bat file in the same order as specified above. 7. Verify Access Manager using the admin console: a. Deploy Apache Tomcat application server. This may also be deployed on another machine if desired. b. Deploy the admin-gui.war on Tomcat. c. Start the application server, and verify whether the application server was started with the admin-gui application. (The name of the application may be different in later versions of Access Manager. For example, the URL looks like http://localhost:8080/axm-admin-gui for Access Manager 6.1.) 6
d. Invoke the RSA Access Manager URL (http://localhost:8080/admingui). The following screen appears: i. Enter administrator login credentials. The RSA Access Manager is displayed as shown below: 8. Create users in LDAP: i. Invoke the LDAP console (Start > Programs > Sun Directory Server). ii. Create user ssouser1 with password. iii. Create user ssouser2 with password. 9. Verify that the LDAP objects are created from the Admin console (under User Group). 5.3 Deploy Content Server Objective: A repository is configured to authenticate with the Access Manager. The RSA plugin on this repository has been loaded and configured to point to the Access Manager. Access by specific LDAP authenticated test users will be directed to the Access Manager for authentication. The plugin also verifies re-authentication in the event of expiration of tickets acquired from prior authentications. 1. Install the Oracle database. 7
2. Install Content Server. The Content Server gets installed with the RSA plugin. 3. Configure a repository (your_repository, for example). 4. Go to $DM_HOME/install/external_apps/auth_plugins/rsa. Verify that the following files exist under this path: a. Follow the instructions in the README.txt file to deploy these files and the dynamic libraries. b. Copy the following DLL files: 1. Copy the dm_rsa.dll file from the above folder to %DOCUMENTUM_HOME%\dba\auth directory. 2. Copy the RSA Access Manger Runtime API (ct_runtime_api.dll) in the %DOCUMENTUM_HOME%\product\5.3\bin directory. c. Invoke Documentum Server Manager to restart the Content Server. 7. Create test users ssouser1 and ssouser2 in the repository (if the users are not imported from LDAP using the LDAP Synchronization job). The following attributes may be defined for the user objects: user_name, user_login_name, user_ldap_dn. 5.4 Deploy Webtop This document was based on a Webtop installation on WebLogic application server, but steps 3 to 8 are also applicable for Webtop deployed on other supported application servers. 1. Verify that the following binaries are available for installation: a. BEA WebLogic server b. Webtop 2. Deploy WebLogic cluster and configure a domain. 3. The WAR file may be expanded ( jar xvf webtop.war ) to make changes to the dfc.properties file. This file will be found under /webtop/web-inf/classes path. Set the dfc.properties file with the connection broker information to connect to the repository and the global registry (which is cs-host host in this example). 4. Install Webtop on the application server. Webtop may be deployed from the same folder where it was expanded. Restart the application server if necessary. 8
5. Invoke the Webtop URL (http://wt-host:7001/webtop) and verify if the super user or other available users can log in. 6. Make a backup copy of the Webtop application configuration file (as app.xml.org, for instance). You will find this file under <Webtop virtual directory>/webtop folder. 7. Make changes to the application configuration as follows: Note: EMC does not recommend modifying the Webtop default configuration. Hence, you must copy the entire <authentication> element from <Webtop virtual directory>/webtop /app.xml to <Webtop virtual directory>/custom/app.xml and make changes there. Refer to the WDK documentation for modification mechanisms. Replace: <authentication> <!-- Default domain and repository to authenticate against --> <domain/> <docbase/> <!-- Class that provide the authentication service --> <service_class>com.documentum.web.formext.session.authentication Service</service_class> <!-- Single Sign-On authentication scheme configuration --> <sso_config> <ecs_plug_in/> <ticket_cookie/> <user_header/> </sso_config> </authentication> With: <authentication> <!-- Default domain and repository to authenticate against --> <domain></domain> <repository></repository> <!-- Class that provide the authentication service --> <service_class>com.documentum.web.formext.session.authentic ationservice</service_class> <!-- Single Sign-On authentication scheme configuration --> <sso_config> <ecs_plug_in>dm_rsa</ecs_plug_in> <ticket_cookie>ctsession</ticket_cookie> <user_header>ctuser</user_header> </sso_config> </authentication> 8. To make these changes take effect, simply navigate to http://server_name/webtop/wdk/refresh.jsp. Refer to the section Configuring Single Sign-on through security servers in the Documentum Web Development Kit and Webtop Deployment Guide for further details on Webtop configurations. 9
5.5 Deploy Web Agent The following instructions reflect the use of Apache web server for reverse proxy. 1. Verify that the RSA Web Agent is available for installation. You can obtain this kit from http://edelivery.rsasecurity.com/agent/cleartrust/47/axm-agent-4.7- apache2-win32.zip. 2. Verify that the Apache web server is running by invoking the URL (http://localhost). 3. Configure the web server as a reverse proxy to Webtop (and other protected applications) and restart the web server, if necessary. Add these lines at the end of httpd.conf: ProxyRequests Off ProxyPass /webtop http://appserver:port/webtop ProxyPassReverse /webtop http:// appserver:port/webtop Also modifiy httpd.conf to allow loading of proxy related modules by uncommenting the following lines: LoadModule proxy_module modules/mod_proxy.so LoadModule proxy_connect_module modules/mod_proxy_connect.so LoadModule proxy_http_module modules/mod_proxy_http.so LoadModule proxy_ftp_module modules/mod_proxy_ftp.so 4. Invoke Webtop via the proxy and verify that Webtop is invoked (http://ag-host/webtop or simply http://localhost/webtop from the same host). 5. Install RSA Access Manager Web agent on the web server and configure it. Provide information about the Access Manager as needed. Stop the web server before installation, as required. 6. Input the following values during configuration: a. Cleartrust.agent.web_server_name (name of the RSA Access Manager server) b. Cookie.domain (for example, dctmlab.com) c. RSA Access Manager server name (for example, am-host.dctmlabs.com). A fully qualified name must be specified here. d. Cleartrust.agent.ssl.use: Clear 7. Configuring the RSA Access Manager Web Agent generates a webagent.conf file (under C:\Program Files\RSA\Access Manager Agent <version>\<web server>\conf folder, for example). Verify the file s content. 8. In webagent.conf, change cleartrust.agent.form_based_enabled to false to force the browser authentication dialog instead of form redirect. 9. Restart the web server. 10. Invoke Webtop via the proxy again and verify that it displays the normal login page (http://ag-host/webtop). If there are any errors in displaying the login page, verify the configuration files created. Since Webtop is not a protected resource yet, you will see the default login page. 10
11. On the Webtop machine (Machine WT): Note: The steps below are applicable for Webtop, so they may not apply to other applications. Refer to the appropriate product documentation for applicable configuration values. a. Create a directory named rsaconfig under the Webtop virtual root directory. b. Copy the webagent.conf file from the Access Manager Agent system (ag-host) and the aserver.conf file from the Access Manager system (am-host) to this webtop/rsaconfig path. c. Modify the aserver.conf file on the Webtop machine to remove usages of localhost in it. The ClearTrust.aserver.dispatcher_info_list in aserver.conf uses localhost, and this needs to be replaced with the RSA Access Manager Host name (or preferably, the IP address of the RSA Access Manager host). 5.6 Protect resources 1. Log in to the Access Manager system (Machine AM). 2. Invoke the Access Manager administration interface (http://localhost:8080/admin-gui) and log in as admin/admin (the access credentials here are as set up on the test deployment). 3. Add a new server: a. From the top menu, select Define Resources > Servers> Add New. This displays the Add a New Server page as shown below. b. Provide values for the following settings: i. Server Name: This may be the name of the RSA Access Manager Web Agent server. This must be the same as the value for Cleartrust.agent.web_server_name. Server type: Web Server Product: Choose the web server product used on the Web Agent. 11
4. Add a new application: Hostname: The name of the machine on which the RSA Web Agent and the web server were installed. Port: 80 For other settings, use the default values. ii. Click Save. iii. Select Define Resources > Servers to check if the new server is added to the list. a. From the top menu, select Define Resources > Applications > Add New. This displays the Add a new application page. On this page: i. Provide a name for the application (such as Webtop). ii. For all other settings, use the default values. iii. Click Save. b. Check Define Resources > Applications to verify if the new application is added to the list. 5. Add new resources: a. From the top menu, select Define Resources > Applications > Manage Existing. All the existing applications are listed. b. Find the application you want to add as a new resource. c. Click Resources. All the resources in the current application are listed. d. Click Add New. The Add Resources page is shown. e. Enter the values for the following settings: i. URL: /webtop/* ii. Web server: Select the server hosting Webtop from the list box. iii. For other settings, use the default values. f. Click Save. Go to the resource list page to verify if the new resource is added. 6. Add entitlement to the user and verify that the user has been created in LDAP already: a. From the top menu, select Manage Users > Users & Administrators > Manage Existing, and then click Go without entering anything in the Search User text box. All existing users are listed. b. Find the new user that was just created and click Entitlements. All the entitlements of the current user are listed. c. Click Add New. All the available applications are listed to allow the user to choose. d. Find the application you want to add, and click Add Entitlements. The Add Entitlements page is shown. e. Select the checkbox next to the resource you want to add, and click Done. The selected resources should be added for the selected user. 7. Verify the policy. Use Authorize Access > Test Authorization to make sure the user can get to /webtop and /webtop/. 5.7 Verify your deployments 5.7.1 Verify Webtop 1. Invoke Webtop via the reverse proxy (http://ag-host/webtop). 2. Enter the RSA user credentials (ssouser1 or ssouser2 username and password). 12
3. Verify that no further prompt appears and the user is logged in to Webtop. This indicates that SSO worked for the repository specified in the application configuration file. Troubleshooting: If further prompts appear, it could mean that the user was not authenticated by the Content Server or that the RSA plugin on the Content Server was not loaded. To rectify: i. Log in to the Content Server host and invoke Documentum Server Manager. ii. On the Docbase tab, click Edit Services. Append the following to the Command field: -otrace_authentication iii. Click OK to save and then restart the repository (stop the repository and start it again). iv. Verify the server repository log. Click View Log and locate the following message that indicates that the plugin has been loaded: DM_SESSION_I_AUTH_PLUGIN_LOADED]info: "Loaded Authentication plugin with code 'dm_rsa' (C:\dctm\dba\auth\dm_rsa_auth.dll)." v. It is important to undo the trace setting after verification. To undo tracing after verification, click Edit Services again, and remove the - otrace_authentication argument in the command. Restart the repository. 4. Restart the application server. 5. Invoke Webtop via the reverse proxy (http://ag-host/webtop) again. 6. RSA credentials are prompted. Enter the username and password for ssouser1 or ssouser2. 7. The Webtop login page appears, prompting the user to select the repository. Select the test repository (your_repository) and click OK. Note: To allow users to log on to a specific repository after SSO authentication, modify the application configuration file (<Webtop virtual directory>/webtop/app.xml). EMC does not recommend modifying the Webtop default configuration. Hence, you must copy the entire <authentication> element from <Webtop virtual directory>/webtop /app.xml to <Webtop virtual directory>/custom/app.xml and make changes as shown below. <authentication> <!-- Default domain and repository to authenticate against --> <domain></domain> <repository>your_repository</repository> To make this change take effect, simply navigate to http://aghost/webtop/wdk/refresh.jsp. The user is logged in to the repository and the Webtop page appears. 13
6 DFS/CenterStage specific configuration To use DFS with RSA, you need to specify the RSA Access Manager Server information. To do so, create a dfs-sso-config.properties file in the WEB-INF\classes directory (where dfc.properties resides) and set the sso.argument property and dfs.sso.argument to the value RSA RSA- POLICYSERVER PORT 1. For example, the value may be: sso.argument=rsa RSA-POLICY 5608 1 7 Conclusion This white paper outlined the deployment and configuration of an EMC Documentum Single Sign On environment using RSA Access Manager product suite. The document also outlined some use cases and some tests for verifying the deployment incrementally and for final verification of the deployment. 8 References and related documentation The information was collected from various sources including EMC Documentum product documentation, RSA product documentation, and EMC Documentum internal documents, including: Documentum Web Development Kit Development Guide Documentum Web Development Kit and Webtop Reference Guide Documentum Product Support Matrix (for platforms and products supported by EMC Documentum and by RSA) RSA Access Manager Integration Installation and Configuration Guide To download RSA products, you need to register at https://knowledge.rsasecurity.com. 9 Definitions Special terms, abbreviations, and acronyms used in this document are defined below. CS Documentum Content Server DA Documentum Administrator DRL Document Resource Locator DMZ De-Militarized Zone IIS Internet Information Services JRE Java run-time environment JDK Java Development Kit LDAP Lightweight Directory Access Protocol OS Operating System SSO Single Sign-On WDK Web Development Kit 14