EMC Documentum Kerberos SSO Authentication

Transcription

1 A Detailed Review Abstract This white paper introduces and describes a Kerberos-based EMC Documentum environment, and explains how to deploy such a system with single sign-on (SSO) on the Documentum platform. June 2011

2 Copyright 2010, 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. Part Number h A Detailed Review 2

3 Table of Contents Executive summary...5 Introduction...5 Audience... 5 Kerberos authentication...5 Kerberos architecture... 5 Kerberos authentication flow in a DFS-based application... 6 Kerberos authentication flow in a Documentum Web Development Kit-based application... 9 Configuring Kerberos authentication...9 Configuring Kerberos on a Content Server in a Windows/ UNIX environment Modification to error message during Kerberos plug-in initialization Replay cache filename change Workaround for the Kerberos plug-in initialization error in UNIX Prerequisites for WDK-based applications Determining the Service Principal Name (SPN)...12 Specifying the SPN for repositories Specifying the SPN for DFS services Specifying the SPN for WDK-based applications Registering the SPN and generating the keytab file...13 Creating the keytab file for Content Server Reinitializing Content Server Configuring the SPN and keytab file for DFS services Creating the keytab file for WDK-based applications Creating Kerberos user accounts...18 Creating Kerberos users in a repository Configuring LDAP synchronization for Kerberos users Creating a user account for a WDK-based application in the Active Directory Enabling Kerberos for DFS-based applications...23 Enabling Kerberos during DFS service deployment Kerberos and JAAS configuration Kerberos configuration Kerberos keytab file JAAS configuration Using Kerberos authentication in DFS clients Kerberos authentication in a local DFS web application Kerberos authentication in a remote DFS client Enabling Kerberos for WDK-based applications...33 Prerequisites Preparing the client machine and the browser to meet Kerberos SSO setup requirements Creating the JAAS configuration file Configuring the Tomcat application server Configuring the WebLogic application server Configuring the JBoss application server A Detailed Review 3

4 Configuring the WebSphere application server Configuring the custom/app.xml file to enable Kerberos authentication Enabling Kerberos SSO authentication in WDK-based applications Configuring the Kerberos domain name Configuring Kerberos fallback Sample Kerberos configuration in custom/app.xml Configuring EMC CenterStage to enable Kerberos authentication Enabling tracing Kerberos authentication use cases Client platform/browser is not supported All repositories are Kerberos-enabled and the user logs in to the Kerberos domain Client machine is not part of the Kerberos domain Webtop is configured to work with mixed repositories The end user is registered in the KDC but is not part of the Kerberos-enabled repository Setting DES, AES128, and RC4 Kerberos encryption types...46 Conclusion...47 References...47 Glossary Common issues with the configuration of Webtop or TaskSpace for Kerberos authentication. 48 Issue Issue Issue Issue Issue Issue Issue Issue Issue Issue Issue Issue Issue Issue Issue Issue Issue Issue Issue Issue Issue References for troubleshooting Kerberos-based SSO authentication A Detailed Review 4

5 Executive summary Kerberos single sign-on (SSO) is a network authentication protocol designed to provide strong authentication for client/server applications by using secret-key cryptography. The Kerberos protocol uses strong cryptography so that a client can prove its identity to a server (and vice versa) across an insecure network connection. After a client and the server have used Kerberos to prove their identities, they can also encrypt all of their communications to ensure privacy and data integrity. Kerberos provides secure and reliable authentication to multiple applications that use Kerberos for authentication. In most distributed network systems, a password is used to prove a user's identity, and this password is transmitted over the network from the client machine to the machine that the user wants to access. So, a mechanism that prevents anyone from intercepting or eavesdropping on the transmitted plain passwords is vital for security. In addition, another pain point while using passwords for authentication is that the password must be supplied every time a connection is requested to the remote machine. Kerberos helps users avoid this issue and solves the central problem of using passwords for authentication without sending them over the network. EMC Documentum supports the Kerberos SSO authentication feature using Microsoft Active Server Domain Services for Kerberos Key Distribution Center (KDC) services. When using a thick client or a Web-based client, users are automatically signed in and authenticated based on their Windows credentials. For example, if Kerberos SSO is configured on a Documentum system, clients requesting services from the Documentum repository will send a service ticket that the Documentum system uses to validate the clients rather than prompting the user to provide login credentials. Introduction This white paper discusses end-to-end Kerberos SSO implementations on systems using Documentum 6.6 and later, including usage scenarios, code samples, and FAQs. Audience This white paper is intended for customers, partners, and consultants who are planning to set up and configure SSO for Documentum using Kerberos in a Windows domain. Kerberos authentication Kerberos architecture Kerberos operates by encrypting data with a symmetric key. A symmetric key is a type of authentication where both the client and server use a single encryption/decryption key to send or receive data. When working with the encryption key, the details are sent to a KDC, instead of being sent directly between each computer. Figure 1 describes how Kerberos authentication is used to verify the credentials of Documentum clients. A Detailed Review 5

6 Figure 1. Kerberos in a Documentum environment On a Documentum system, the Kerberos authentication process involves the following steps: 1. A Documentum user logs in to a client computer that is in the Kerberos domain by specifying Windows login credentials, such as a username and password, and accesses a Documentum application from the client. The local computer/client sends the login credentials and the service name of the application to the Key Distribution Center (KDC) for identification. 2. The Kerberos authentication service/server (AS) component at the KDC receives the request from the client, verifies whether the client is the computer it claims to be, and generates a Ticket Granting Ticket (TGT). 3. When the user wants to access a Documentum client in the domain, the client sends the TGT to the KDC to obtain a Service Ticket (ST) for the service, using the Service Principal Name (SPN). Note: It is mandatory that the SPN of all services are registered in the KDC. The KDC can provide the Service Ticket only for a registered service. 4. The KDC Ticket Granting Service (TGS) authenticates the TGT and generates an ST. 5. The client running the Documentum application uses the relevant DFC-based API and provides the username and ST as password. 6. The Documentum Foundation Classes (DFC) pass the login information to the Content Server service. 7. The Content Server service validates the ST and authenticates the user. 8. If authentication is enabled, the Content Server service sends the acknowledged ticket to DFC. 9. DFC sends the acknowledged ticket back to the client to validate the Content Server service. A session is established and no further authentication is required. Kerberos authentication flow in a DFS-based application Documentum Foundation Services (DFS provides two distinct modes to satisfy Kerberos authentication requirements: a local mode and a remote mode. A Detailed Review 6

7 A local mode assumes both the DFS client and the DFS service exist in the same Java Virtual Machine (JVM). The client can be part of a web application. Figure 2 illustrates how Kerberos authentication is used for DFS local mode. Figure 2. DFS Kerberos SSO flow with local mode The authentication process shown in Figure 2 is as follows: 1. A remote user requires a Service Ticket (ST) with Ticket Granting Ticket (TGT) and the application s Service Principal Name (SPN). 2. The KDC returns an ST for the application. 3. The web application client sends a web request with the Kerberos Simple and Protected GSSAPI Negotiation Mechanism (SPNEGO) token in the HTTP header. Negotiation may occur between the web browser and server. 4. The web server extracts the SPNEGO token from the HTTP header and accepts it with the Kerberos utility; a new TGT is generated for the authentication to DFS. The DFS service gets a TGT from a BinaryIdentity and passes it to DFC LoginInfo. 5. DFC initializes the Content Server ST with the TGT and logs in to the Content Server. 6. The Content Server validates the ST and returns a repository session. 7. The web server handles the web request and talks to the Content Server as a DFS local client. The web page content is returned to the web client. A remote invocation assumes the client and the server reside in separate JVMs. For DFS, communication between client and server relies on Simple Object Access Protocol (SOAP), and login information will be sent over the wire as SOAP WS-Security headers. A Detailed Review 7

8 Figure 3 illustrates how Kerberos authentication is used for DFS remote mode. (1) Ticket-Granting Ticket (TGT) + DFS SPN (2) Service Ticket (ST) for DFS SPN KDC (4) Accept ST and new TGT KeyTab File Content Server (3) SOAP Request, passing ST through JAX-WS handler WCF Behavior (5) DFC LoginInfo with Content Server ST (6) Repository Session (7) SOAP Response DFS Remote Client DFS Server * DFS extracts Kerberos ST from SOAP Header, validates it with a Kerberos Utility, and generates a new TGT for DFC login. * DFC initializes Content Server ST and logins with it to get a repository session. * Keytab file can be used for validation of long-term key. Figure 3. DFS Kerberos SSO flow with remote mode The authentication process in Figure 3 is as follows: 1. A remote user requires an ST with TGT and DFS SPN. 2. KDC returns an ST for a DFS service. 3. DFS remote client sends out a SOAP request, serializing ST as a binary token in the Java API for XML Web Services (JAX-WS) handler or Windows Communication Foundation (WCF) behavior; negotiation is not supported. 4. DFS extracts Kerberos ST from the SOAP header, validates it with the Kerberos utility, and generates a new TGT for DFC login. 5. DFC initializes the Content Server ST with the TGT and logs in to the Content Server. 6. The Content Server validates the ST and returns a repository session. 7. The DFS server handles the request with the repository session and returns the SOAP response. A Detailed Review 8

9 Kerberos authentication flow in a Documentum Web Development Kit-based application Figure 4. Documentum Webtop Kerberos SSO flow Figure 4 illustrates a Kerberos single sign-on authentication process in Documentum Webtop. The authentication steps are as follows: 1. The Webtop user logs in to a machine that is in the Kerberos domain. 2. A Ticket Granting Ticket (TGT) is generated. 3. The user opens a browser (IE/Firefox) and accesses the Webtop URL. 4. Webtop verifies whether the user has already been authenticated. If the user has not been authenticated, Webtop displays Error 401 with WWW-Authenticate:Negotiate in the http header. 5. Using the TGT, the browser sends a request to obtain a Service Ticket (ST) for Webtop. The browser wraps the ST in the SPNEGO token and sends it to Webtop in the http header. 6. Webtop passes the SPNEGO token to DFC to obtain the ST. DFC validates the ST. Webtop displays the Repositories selection page. The Webtop user selects a repository. DFC then sends a request for an ST for the repository by impersonating the user and passes the user information and the ST to the Content Server. 7. The Content Server validates the ticket using the Kerberos plug-in and returns a repository session. 8. Webtop obtains a repository session and returns to the Webtop Main page. Configuring Kerberos authentication The Kerberos authentication plug-in that enables Kerberos support for KDC services is automatically installed with Content Server. You must complete all additional steps to enable Kerberos SSO on Content A Detailed Review 9

10 Server, LDAP servers, DFS servers, DFS clients, and WDK-based applications subsequent to Content Server installation. Depending on the specific Documentum server/client environment that you use for Kerberos authentication, you must configure the Kerberos authentication by: Creating a Kerberos domain and adding all servers and clients that are participating in Kerberos authentication to the Kerberos domain. Choosing a Service Principal Name (SPN). A Kerberos SPN uniquely identifies a service that uses Kerberos authentication. Registering the SPN on the Active Directory and generating a keytab file. The keytab file contains name/value pairs consisting of an SPN and a long-term key derived from a password. Both the service and the KDC must have knowledge of the keytab file. Creating Kerberos users, either manually or by synchronizing with an LDAP directory server. Enabling Kerberos support on the DFS server and remote DFS clients, if applicable. You can configure the DFS 6.6 web services to use the server-side JAX-WS handlers that interface with the Content Server Kerberos implementation. The DFS 6.6 SDK includes new classes that support Kerberos authentication for local Java clients, remote Java clients, and.net clients. DFS SOAP clients that do not use the support classes in the SDK can authenticate using WS-Security headers that comply with the Kerberos Token Profile 1.1 specification. Enabling Kerberos support in WDK-based applications, if applicable. Configuring Kerberos on a Content Server in a Windows/ UNIX environment To configure Kerberos on a Windows/UNIX environment: 1. Install Content Server The $DOCUMENTUM/dba/auth directory is created and the Kerberos plug-in file is copied there. In Windows, the plug-in filename is dm_kerberos.dll. In all UNIX platforms except HP-UX Risc, the name of the plug-in file is libkerberos.so. In HP-UX Risc, the plug-in filename is libkerberos.sl. The MIT Kerberos binaries are automatically copied in the $DM_HOME/bin directory. 3. To include the Windows/UNIX machine in the AD machine domain, include the following information in the C:\windows\krb5.ini (windows) /etc/krb5.conf (or /usr/local/etc/krb5.conf in UNIX) file: Under the [realms] tag, include the following: QA2008.COM = {kdc = admin_server = } Under the [domain_realm] tag, include the following:.qa2008.com = QA2008.COM Under the [libdefaults] tag: comment the following line: default_realm = EXAMPLE.COM and include the following: default_realm = QA2008.COM 4. Copy keytab files to the $DOCUMENTUM/dba/auth/Kerberos folder and restart the docbase using the following command: /dm_start (docbasename) -otrace_authentication This command enables an authentication trace in the dm_krb_docbasename.log file. 5. Set any supported encryption standard entries in the /etc/krb5.conf (or /usr/local/etc/krb5.conf) file. A Detailed Review 10

11 For example: default_tkt_enctypes = aes128-cts default_tgs_enctypes = aes128-cts The supported encryption protocols are: DES rc4-hmac AES 128 The above encryption types must be specified in the Kerberos configuration file for default_tkt_enctypes and default_tgs_enctypes tags under the libdefaults section. Modification to error message during Kerberos plug-in initialization The following updated error message is displayed during plug-in initialization when the keytab file is not present. Thu Mar 10 12:51: [DM_SESSION_I_AUTH_PLUGIN_LOAD_INIT]info: "Authentication plugin ( 'dm_krb' ) was disabled. This is expected if no keytab file(s) at location /home/dctm/dba/auth/kerberos). Please refer the content server installation guide. This is valid for both Windows and UNIX. Replay cache filename change Replay cache is used to detect duplicate authentication requests. When the Kerberos protocol processes a request, it makes an entry in the replay cache. If it processes a later request that matches an entry already in the replay cache, it returns an error to the Content Server. The replay cache is periodically purged to remove requests with expired lifetimes. The replay cache should not be shared between processes since this could result in false replay errors caused by different requests with the same timestamp. The replay cache filename is the repository name. Its default location is pointed by %TEMP% or %TMP% or C:\ for Windows, and by $TMPDIR for UNIX, or by the KRB5RCACHEDIR environment variable. For example, if the repository name is testenv, the replay cache filename is testenv. Workaround for the Kerberos plug-in initialization error in UNIX If you see the following Kerberos plug-in initialization error message: Error message: [DM_SESSION_E_AUTH_PLUGIN_LOAD_INIT_ERROR]error: "Failed to load Authentication Plugin /export/space1/documentum/dba/auth/libkerberos.so. Plugin initialization returned error: '5 Either allocation failed or Kerberos context creation failed'." Set the LD_PRELOAD environment variable to include the MIT Kerberos binaries so that the loader preloads them before it loads the other binaries. For Linux and Solaris, add libkrb5.so.dm.3 and libgssapi_krb5.so.dm.2 to LD_PRELOAD For HP-UX Risc and HP Itanium, add libkrb5.dm.3 and libgssapi_krb5.dm.2 to LD_PRELOAD For AIX, add libkrb5.so and libgssapi_krb5.so to LD_PRELOAD A Detailed Review 11

12 For example, in the C shell for Linux, the syntax would be: setenv LD_PRELOAD libkrb5.so.dm.3:libgssapi_krb5.so.dm.2 Note: The MIT binaries are located in $DM_HOME/bin directory. If LD_PRELOAD contains values, you can append new values to it. Prerequisites for WDK-based applications Active Directory machine: Ensure that the Active Directory machine uses Windows Server 2003 or later to support the Kerberos 5 authentication protocol. Add the required computers and users to the Active Directory. Refer to the Microsoft help for setting up an Active Directory and Kerberos domain. Content Server machine: Verify that the Content Server machine is running Windows Server 2003 or later. Add the machine to the Kerberos domain and then install Documentum 6.6 Content Server. Application server machine: Ensure that the application server machine is running on a server with Windows 2003 or later. Install the relevant application server after adding the machine to the Kerberos domain. You can deploy the WDK-based application on the machine. For more information about deploying Webtop on an application server, see the Web Development Kit and Webtop 6.6 Deployment Guide. Install a supported browser: IE6, IE7, IE8, Firefox 2.x, Firefox 3.0.x, or Firefox 3.5.x. Client machine: Ensure that the client machine is on a Windows XP or later platform. Install a supported browser: IE6, IE7, IE8, Firefox 2.x, Firefox 3.0.x, or Firefox 3.5.x, which you can configure to access Webtop with Kerberos SSO support.. Register Webtop as a Service Principal in the KDC. For more information, see the Web Development Kit and Webtop 6.6 Deployment Guide. Determining the Service Principal Name (SPN) A Kerberos Service Principal Name (SPN) uniquely identifies a service that uses Kerberos authentication. The SPN format varies depending on the service that the Kerberos uses for authentication. At the very least, you should configure the SPN for the repository on the Content Server. The following section describes how to configure the SPN for repositories, DFS services, and WDK-based applications. Specifying the SPN for repositories EMC recommends the following SPN format for registering a repository on the KDC service: SPN=service-name/docbase-name@domain Where service-name is the service that is constant for Content Server. For example: CS/REPO1@MYDOMAIN.COM Where CS is the service, REPO1 is repository name, and MYDOMAIN.COM is the domain where the Content Server SPN is registered. This convention uniquely identifies each SPN across all repositories. Specifying the SPN for DFS services The recommended SPN format for DFS core services is: DFS/host:port@realm A Detailed Review 12

13 We recommend using a hostname rather than an IP address as the host string, such as myhost.mydomain.com. The realm name, or the Kerberos configuration file, is the name of the Kerberos realm (see Enabling Kerberos for DFS-based applications ). Unless you need to include a service name in the SPN, EMC recommends using the same format for custom DFS services as well. This approach requires fewer configurations for the Active Directory since you do not need separate user accounts for every module/service. It also means that you can access all services on a host:port using the same ST. This approach is consistent with the way the SPNEGO protocol builds an SPN for a web application. Specifying the SPN for WDK-based applications The recommended format for WDK-based applications, such as Webtop, is: <service>/<fully qualified hostname> Unlike Kerberos principal names, account names on Windows 2003 or Windows 2008 are not multipart names. Therefore administrators cannot directly create an account name in the HTTP/hostname.dns.com format. The only option for Windows 2003 or Windows 2008 systems is to create a principal instance using Service Principal Name mappings. In this case, the administrator needs to create an account with a meaningful name and hostname, and add Service Principal Name mapping for HTTP/hostname.dns.com. Registering the SPN and generating the keytab file To use Kerberos SSO you need to register a Service Principal Name (SPN) on an Active Directory using the Windows Server Ktpass utility. The Ktpass utility enables an administrator to configure a service as a security principal in the Active Directory. This procedure produces a keytab file, which contains the name/value pairs consisting of an SPN and a long-term key derived from a password. Both the service and the KDC service must recognize the keytab file. The length of the keytab filename depends on the OS filename limitation. The name of the file uses the following format: <repo_name>.<xxxx>.keytab Where <repo_name> is the name of the repository for which the SPN is registered. <xxxx> can be any string that makes the filename unique. This unique name is required because users can register the Content Server in multiple trusted domains. Creating the keytab file for Content Server In the following procedures, a user is registered on the KDC service to act as the service principal for the service. This user maps to the SPN and is distinct from users who need to be authenticated to use the service. There are two recommended procedures for registering the SPNs. The simplest approach is to create a single SPN mapped to an Active Directory user, which sets a single password for the SPN. To create a single SPN mapped to a user: 1. Log in to the machine that runs the KDC service. 2. Create a user in the Active Directory. 3. Using the user you created in the preceding step, set an SPN and create a keytab file using the ktpass utility as follows: ktpass /pass <password> -out <keytab-file> -princ <SPN> A Detailed Review 13

14 -crypto ALL +DumpSalt -ptype KRB5_NT_PRINCIPAL /mapop set /mapuser <user-name> EMC recommends that you map the SPN service with all the supported encryption types when you generate keytab files. This is valid for both Windows and UNIX. If you want to generate a keytab file using a particular encryption protocol, for example DES-CBC- MD5, use the ktpass utility as follows: ktpass /pass <password> -out <keytab-file> -princ <SPN> -crypto DES-CBC-MD5 +DumpSalt -ptype KRB5_NT_PRINCIPAL +desonly /mapop set /mapuser <user-name> For supported encryption protocols, refer to the section Configuring Kerberos on a Content Server in a Windows/ UNIX environment. In a Windows 2008 environment, you must run the setspn command in the following format to provide Kerberos delegation privileges for the new user: setspn -A CS/<reponame>@domain.com domain.com\<csusername> 4. After you register the SPN for the user, the Delegation tab is displayed when you view properties of the new user in the User Properties dialog box. Select the Trust this user for delegation to any service (Kerberos only) option. 5. Copy the keytab file to the $DOCUMENTUM/dba/auth/Kerberos/ folder on the Content Server. This folder is created during Content Server installation. An alternate approach is to register multiple SPNs mapped to a single Active Directory user. To create multiple SPNs mapped to a single user: 1. Log in to the machine that runs the KDC service. 2. Create a user in the Active Directory. 3. Set an SPN and create a keytab file using the ktpass utility with the user you created in the preceding step, using the following syntax: ktpass /pass <password> -out <keytab-file> -princ <SPN> -crypto DES-CBC-MD5 +DumpSalt -ptype KRB5_NT_PRINCIPAL +desonly /mapop set /mapuser <user-name> 4. Set another SPN using the setspn utility and set <user-name> to the user you created in step 2. setspn -A <SPN> <user-name> In a Windows 2008 environment, you must run the setspn command in the following format to provide Kerberos delegation privileges for the new user: setspn -A CS/<reponame>@domain.com domain.com\<csusername> A Detailed Review 14

15 After you register the user SPN, the Delegation tab is displayed when you view properties of the new user in the User Properties dialog box. Select the Trust this user for delegation to any service (Kerberos only) checkbox. 5. Run the ktpass utility for the second SPN. Use the salt and key version number (kvno) that were created in step 3, using the following syntax: ktpass /pass <password> -out <keytab-file> -princ <SPN> -crypto DES-CBC-MD5 +DumpSalt -ptype KRB5_NT_PRINCIPAL +desonly /mapop set +RawSalt <salt> -in <keytab-file> -kvno <number> 6. Copy the keytab file to the $DOCUMENTUM/dba/auth/Kerberos/ folder on the Content Server. This folder is created during Content Server installation. Windows 2008 account names are not multipart as Kerberos principal names. As a result, administrators cannot directly create an account named HTTP/hostname.dns.com. Such a principal instance is created using service principal name mappings. In this case, an account is created with a meaningful name and hostname, and a service principal name mapping is added to HTTP/hostname.dns.com. Reinitializing Content Server The reinitialize server function initializes the Kerberos plug-in, which reloads the SPNs from the repository s keytab file. This command enables you to update the Kerberos system without restarting Content Server. Reinitialization is required if a new SPN has been registered and copied to the repository. However, this step is not required if you have changed the password on an existing SPN. Administrators can invoke the reinitialize server function using Documentum Administrator by selecting the Re-Initialize Server option on the Info tab of the Server Configuration Properties dialog box. Configuring the SPN and keytab file for DFS services To enable authentication of the DFS services on the KDC, you need to register the DFS SPN on the Active Server KDC using the Microsoft ktpass utility. As you may also be registering an SPN for Content Server on the same machine, you can choose to register the DFS SPN and other SPNs to the same user account. In some cases it may also be useful to register multiple DFS SPNs to the same account. For example, you can achieve load-balanced environments support for Kerberos by joining all load-balanced nodes into a single account and assigning a single SPN to the cluster. If you need a different SPN to access the service (for example, based on the service host IP rather than the load balancer name) you can also register this SPN with the same account. Windows 2008 account names are not multipart as Kerberos principal names. As a result, administrators cannot directly create an account named HTTP/hostname.dns.com. Such a principal instance is created using service principal name mappings. In this case, an account is created with a meaningful name and hostname, and a service principal name mapping is added to HTTP/hostname.dns.com. The following procedure explains how to register an SPN using one-to-one mapping between the SPN and the user account, or a many-to-one mapping where multiple SPNs are registered to one user account. Note: For reference information on the ktpass utility see To configure the SPN and keytab file: 1. Create a user for the DFS service in Active Directory. This is optional, as you can use an existing account. A Detailed Review 15

16 2. Do one of the following: Map SPN(s) to usernames using a one-to-one mapping. Map multiple SPNs to a username using many-to-one mapping. 3. Copy the keytab file to the host computer where the DFS services are installed. To map an SPN to a username (one-to-one mapping): Using the Microsoft ktpass utility, map the service SPN to the user account and generate a keytab file for the service. ktpass /pass <password> -out <keytab-file> -princ <SPN> -crypto DES-CBC-MD5 +DumpSalt -ptype KRB5_NT_PRINCIPAL +desonly /mapop set /mapuser <user-name> In a Windows 2008 environment, you must run the setspn command in the following format to ensure that the Delegation tab is included in the User Properties dialog box: setspn A DFS/myhost.mydomain.com:8080@SRV01.COM After you register the user SPN, view the properties of the new user in the User Properties dialog box. Click the Delegation tab and select the Trust this user for delegation to any service (Kerberos only) checkbox to provide Kerberos delegation privileges to the new user. Note: Make sure that you do not map the same SPN to more than one user account. To map an SPN to a username (many-to-one mapping): 1. Using the Microsoft ktpass utility, map the first SPN to the user account and generate a keytab file, using syntax like the following: ktpass /pass <password> -out <keytab-file> -princ <SPN> -crypto DES-CBC-MD5 +DumpSalt -ptype KRB5_NT_PRINCIPAL +desonly /mapop set /mapuser <user-name> Note the output to the console. Look for the salt string and the key version number (vno). You need them in a succeeding step. 2. Using the setspn utility, set the next SPN, mapping to the same user account: setspn -A <SPN> <user-name> In a Windows 2008 environment, you must run the setspn command in the following format to ensure that the Delegation tab is included in the User Properties dialog box: setspn A DFS/myhost.mydomain.com:8080@SRV01.COM After you register the SPN for the user, view the properties of the new user in the User Properties dialog box. Click the Delegation tab and select the Trust this user for delegation to any service (Kerberos only) checkbox to provide Kerberos delegation privileges to the new user. 3. Run the ktpass utility for the second SPN without setting with the same user. Use the salt and key version number (kvno) that were output in step 1 of this procedure. ktpass /pass <password> -out <keytab-file> -princ <SPN> -crypto DES-CBC-MD5 +DumpSalt -ptype KRB5_NT_PRINCIPAL +desonly /mapop set +RawSalt <salt> -in <keytab-file> -kvno <vno> 4. Repeat steps 2 and 3 for each additional SPN. A Detailed Review 16

17 Creating the keytab file for WDK-based applications After specifying that the SPN for the application server (on which Webtop is deployed) use Kerberos, the administrator must create a keytab (key table) for the Webtop application. Webtop requires the keytab file to authenticate itself to the Key Distribution Center (KDC). The administrator must register the application as a Kerberos principal in the Active Directory to enable the application to participate in Kerberos authentication. A Kerberos principal is a regular account on the Active Directory. For example, you can name the principal, "name@your.realm". The realm name follows the "@" character in the principal. The application server/web server that hosts the application does not have to belong to the same Kerberos domain. Both the Active Directory and the application server can belong to different network domains. However, the application server must have access to the Kerberos domain network. For example, if the Kerberos domain REALM is WDKBLR.COM and the host machine where the application server is running is WDKAPPS.WDKBLR.COM, then register the application Kerberos principal in the wdkapps.wdkblr.com@wdkblr.com Active Directory. The administrator must use the ktpass command line tool to register the SPN service as a security principal in the Windows Server Active Directory, and to create a keytab file on the KDC. This keytab file (ktpass.exe) is bundled with the Windows 2008 Resource Toolkit package and must be installed separately. Run ktpass.exe on the Active Directory Server machine and when the keytab file is generated, move it to the <webtop_installation>/web-inf folder on the application server machine by running the ktpass command in the following format: ktpass /pass <password> -out <keytab-file> -princ <SPN> -crypto AES128- CTS +DumpSalt -ptype KRB5_NT_PRINCIPAL +aesonly /mapop set /mapuser <user-name> Where: password - Password of the user keytab-file - Location to save the keytab file SPN - The SPN framed by the browser in the following format: HTTP/hostname.dns.com@REALM (E.g. HTTP/wdkapps.wdkblr.com@WDKBLR.COM) user-name - User name (E.g. wtuser) For example, you can run the ktpass command using the following parameters: ktpass /pass <password> -out webtop.keytab princ HTTP/wdkapps.wdkblr.com@wdkblr.COM crypto AES128-CTS +DumpSalt -ptype KRB5_NT_PRINCIPAL +aesonly /mapop set /mapuser webtop_wdkapps This command generates the webtop_wdkapps.keytab file on the Active Directory machine. Copy this file to the <webtop_installation>/web-inf folder on the application server machine. After generating the keytab file, view the Properties of the new user to verify the SPN registered to the user as indicated in Figure 5. A Detailed Review 17

18 Figure 5. User logon name field displays the registered SPN Creating Kerberos user accounts Kerberos SSO can only authenticate users who are registered as Kerberos users in the Active Directory and in a Content Server repository. WDK-based applications must have a user account in the Active Directory. The following options are available for creating Kerberos users in a repository: Create the user account manually, both in the Active Directory and in the repository. Synchronize the users from the Active Directory using LDAPSynchronization, and then modify the User Login Domain in the LDAP configuration object, as described in the Configuring LDAP synchronization for Kerberos users section. Creating Kerberos users in a repository Only the installation owner, system administrator, or superuser can create users in a Content Server repository. If an LDAP server authenticates a user, only a superuser can modify the user s LDAP-mapped attributes. To create a Kerberos user account: 1. Start Documentum Administrator and connect to the repository where you want to create new users. 2. Navigate to Administration > User Management > Users. 3. Do one of the following: To create a new user, select File > New > User. The New User page is displayed. To modify an existing user, select the user, then select View > Properties > Info. The User Properties page is displayed. 4. Enter the user information on the New User or modify the user information on the User Properties page. For a detailed description of all fields, refer to the Documentum Administrator User Guide. For Kerberos users, you should use different values for the User Login Domain and the User Source fields rather than the ones you use for user accounts that do not use Kerberos authentication. User Login Domain The domain in which the user is authenticated. This is typically a Windows domain or the name of the LDAP server that you used for authentication. If you are using Kerberos authentication with LDAP synchronization, you must set the user login domain to the short domain name, as described in the section Configuring LDAP synchronization for Kerberos users. User Source Specifies how to the server authenticates the username and password. For Kerberos users, the value must be set to dm_krb. A Detailed Review 18

19 5. Click OK. Configuring LDAP synchronization for Kerberos users You can implement LDAP synchronization in conjunction with Kerberos SSO in two ways: Using an existing LDAP configuration to authenticate Kerberos users. Creating a new LDAP configuration to authenticate Kerberos users. To use an existing LDAP configuration to authenticate Kerberos users: 1. Modify the user login domain attribute in the user object of all Kerberos users to use the short domain name instead of the name of the LDAP server. For example, if a Kerberos user is part of the wdkdomain.com domain, change the user login domain attribute to wdkdomain. 2. Change the user source attribute in the user object to dm_krb for all Kerberos users who are synchronized with LDAP, if the password is not in plug-in format. Changing the user source attribute is optional. 3. Run the LDAP synchronization job. To create a new LDAP configuration to authenticate Kerberos users: 1. Create an LDAP configuration object. Use the short domain name as the LDAP configuration object name. For example, if Kerberos users are part of the wdkdomain.com domain, create an LDAP configuration object using wdkdomain as the LDAP configuration object name. 2. Change the user source attribute in the user object to dm_krb for all Kerberos users who are synchronized with LDAP. 3. Run the LDAP synchronization job. Creating a user account for a WDK-based application in the Active Directory You must create a user account for any WDK-based application in the Active Directory to map to the Service Principal Name (SPN). To create a user for Webtop in Active Directory: 1. On the Active Directory machine, navigate to Start > Programs > Administrative Tools > Active Directory Users and Computers. The Active Directory Users and Computers console is displayed. A Detailed Review 19

20 Figure 6. The Active Directory Users and Computers console 2. Right-click the Users node, select New > User. The New Object - User wizard is displayed. 3. Specify the new user s login name details, and click Next. Figure 7. Specifying the name of the new user 4. Specify the new user s password and click Next. A Detailed Review 20

21 Figure 8. Specifying the password for the new user 5. Click Finish. The new user is created and listed in the Users node. Figure 9. The new user entry is displayed in the list of users 6. Right-click the new user, and select Properties. The <User> Properties dialog box is displayed. 7. Click the Account tab. 8. Select one or both of the following encryption algorithms under Account options based on the encryption algorithms you require: Select the Use DES encryption types for this account checkbox. A Detailed Review 21

22 Figure 10. Properties set for the new Webtop user in the Account tab on a non- Windows 2008 machine On a Windows 2008 machine, select the This account supports Kerberos AES 128 bit encryption account checkbox. Figure 11. Property set for the new Webtop user in the Account tab on a Windows 2008 machine In addition, on a Windows 2008 machine, click the Delegation tab and select the Trust this user for delegation to any service (Kerberos only) checkbox. A Detailed Review 22

23 Figure 12. Property set for the new Webtop user in the Delegation tab on a Windows 2008 machine 9. Click OK. Note: To specify that the user comply with the Kerberos protocol, the encryption type must be DES or AES. Enabling Kerberos for DFS-based applications The DFS 6.6 web services can be configured to use server-side JAX-WS handlers that interface with the Content Server Kerberos implementation. The DFS 6.6 SDK includes new classes that support Kerberos authentication for local Java clients, remote Java clients, and.net clients. DFS SOAP clients that do not use the support classes in the SDK can be authenticated using WS-Security headers that comply with the Kerberos Token Profile 1.1 specification. Enabling Kerberos during DFS service deployment To enable Kerberos authentication in remote DFS services, you must add specific libraries to the DFS archive prior to deploying and configuring server-side JAX-WS handlers in deployment descriptors. This procedure applies to the core services delivered with the DFS product, and to custom services that are upgraded to the DFS 6.6 (or later) runtime. To enable Kerberos support in remote DFS services: 1. Open the services EAR file and locate APP-INF/classes/authorized-service-handler-chain.xml. If you are deploying a WAR file, locate WEB-INF/classes/authorized-service-handler-chain.xml. 2. Insert a descriptor for the Kerberos Token Profile 1.1 support handler before the Context Local Registry handler, as shown below, and then save the file. <handler-chains xmlns=" <handler-chain> A Detailed Review 23

24 <handler> <handler-name>authorization</handler-name> <handler-class> com.emc.documentum.fs.rt.impl.handler.authorizationhandler </handler-class> </handler> <handler> <handler-name>kerberos Token Profile 1.1 Support</handler-name> <handler-class> com.emc.documentum.fs.rt.handlers.kerberostokenserverhandler </handler-class> </handler> <handler> <handler-name>context Local Registry</handler-name> <handler-class> com.emc.documentum.fs.rt.impl.handler.servercontexthandler </handler-class> </handler> </handler-chain> </handler-chains> 3. In the web.xml deployment descriptor, specify env-entry settings (you can insert these anywhere inside the <web-app> element). If you are deploying an EAR file, you need to modify the web.xml for each module; for example emc-dfs.ear/services-core.war/web-inf/web.xml. The setting for the DFS service SPN name is mandatory. <env-entry> <description> Mandatory property defining the SPN of the DFS module serviced by the handler. The SPN is defined at deployment time, when the KDC is configured. The KDC realm is required as part of the SPN. </description> <env-entry-name>dfs.spn</env-entry-name> <env-entry-type>java.lang.string</env-entry-type> </env-entry> <env-entry> <description> Optional, path and name of the JAAS config file. If not specified here, this location can be set in a JVM command line parameter: Djava.security.auth.login.config=/path/to/JAAS.config </description> <env-entry-name>jaas.config</env-entry-name> <env-entry-type>java.lang.string</env-entry-type> <env-entry-value>c:/krbclient.conf</env-entry-value> </env-entry> <env-entry> <description> Optional, path and name of the Kerberos config file. By default, the login module tries to locate it in: 1. The file referenced by the Java property java.security.krb5.conf 2. $java.home/lib/security/krb5.conf 3. c:\winnt\krb5.ini on Microsoft Windows platforms 4. /etc/krb5/krb5.conf on UNIX platforms A Detailed Review 24

25 5. /etc/krb5.conf on Linux platforms. </description> <env-entry-name>krb5.config</env-entry-name> <env-entry-type>java.lang.string</env-entry-type> <env-entry-value>c:/winnt/krb5.ini</env-entry-value> </env-entry> 4. Add krbutil.jar and jcifs-krb jar from the SDK to APP-INF/lib (in EAR files) or WEB-INF.lib (in WAR files). Add commons-codec-1.3.jar and commons-lang-2.4.jar to the same location if they are not already there. 5. Repackage and redeploy the archive. Kerberos and JAAS configuration To enable Kerberos support on the DFS server, the following files are required: Kerberos configuration file Kerberos keytab file JAAS configuration Kerberos configuration The Kerberos configuration file must include Kerberos-specific settings such as the KDC address and default realm name. The realm name, shown below, includes the KDC and administration server addresses. [libdefaults] default_realm = SRV01.COM forwardable = true ticket_lifetime = 24h clockskew = [realms] SRV01.COM = { kdc = myhost.mydomain.com admin_server = myhost.mydomain.com } You can specify the location of this file in the web.xml deployment descriptors, or you can place it in a location that you choose, as described in the sample web.xml shown in the section Configuring the SPN and keytab file for DFS services. Kerberos keytab file The Kerberos keytab file is generated on the Active Directory using the Windows Server ktpass utility. This file is then copied to the DFS server machine (the machine where the Kerberos ST will be validated). You,must specify the location of the keytab file in the JAAS configuration, as described in JAAS configuration section. JAAS configuration The JAAS configuration file entry contains JAAS specific settings such as the LoginContext name (which is also the name of the configuration entry), settings for the Kerberos login module, the DFS Service Principal Name, and the location of the keytab file. The location and format of the JAAS configuration settings vary depending on the application server environment. Unless otherwise specified, you can specify a configuration file setting in a JVM command A Detailed Review 25

26 line parameter like -Djava.security.auth.login.config=/path/to/JAAS.config, or in a web.xml env-entry, as described in the Enabling Kerberos during DFS service deployment section. In each of the configuration files, the LoginContext corresponds with the DFS SPN by replacing separator characters in the SPN with hyphen characters, and omitting segment. For example, with this SPN: DFS/myhost.mydomain.com:8080@SRV01.COM the JAAS configuration entry name (that is, the LoginContext name) will be: DFS-myhost-mydomain-com-8080 Make sure that the SPN in the JAAS configuration matches the SPN defined in web.xml. For more information, see the Enabling Kerberos during DFS service deployment section.. The following sections provide details specific to the application servers that you can use. Tomcat and WebLogic Tomcat and WebLogic will accept the following format for the JAAS configuration: DFS-myhost-mydomain-com-8080 { com.sun.security.auth.module.krb5loginmodule required debug=true principal="dfs/myhost.mydomain.com:8080@srv01.com" refreshkrb5config=true usekeytab=true storekey=true donotprompt=true useticketcache=false isinitiator=false keytab="c:/dfsuser.keytab"; }; JBoss In the JBoss application server, JAAS configuration settings are provided in a file called login-config.xml in a directory similar to JBOSS_HOME/server/DctmServer_DFS/. The settings have the following format: <application-policy name = "DFS-myhost-mydomain-com-8080"> <authentication> <login-module code = "com.sun.security.auth.module.krb5loginmodule" flag = "required"> <module-option name = "principal">dfs/myhost.mydomain.com:8080@srv01.com</module-option> <module-option name = "usekeytab">true</module-option> <module-option name = "storekey">true</module-option> <module-option name = "donotprompt">true</module-option> <module-option name = "useticketcache">false</module-option> <module-option name = "isinitiator">false</module-option> <module-option name = "keytab">c:/dfsuser.keytab</module-option> </login-module> </authentication> </application-policy> WebSphere The WebSphere JAAS configuration file is named wsjaas.conf and is located in a directory similar to WEBSPHERE_HOME/AppServer1/profiles/AppSrv01/properties/. WebSphere does not use the -Djava.security.auth.login.config system property to point to an alternative JAAS configuration file; A Detailed Review 26

27 however, you can add and modify a new JAAS login configuration using the administrative console, as described in the IBM WebSphere documentation. You can also perform a WebSphere JAAS configuration using the Administrative Console. With WebSphere 7, you can navigate to the JAAS configuration dialog box using Security > Global security > Java Authentication and Authorization Service. With WebSphere 6, you can navigate using Security > Secure administration, applications, and infrastructure > Java Authentication and Authorization Service. The Kerberos entry has the following format: DFS-myhost-mydomain-com-8080 { com.ibm.security.auth.module.krb5loginmodule required debug=true credstype="both" usekeytab="file:c:/kerberos.keytab" principal="dfs/myhost.mydomain.com:8080@srv01.com"; }; With WebSphere you also need to add the following line to the Kerberos configuration file: [libdefaults] default_keytab_name = FILE:c:/kerberos.keytab Using Kerberos authentication in DFS clients The DFS Kerberos API deals specifically with transferring authentication information to the DFS service, using either a remote web service call or a local Java API call. The API does not obtain Kerberos tickets from the Kerberos Key Distribution Center (KDC). Because DFS applications are multi-tiered, Kerberos integration is based on delegated authentication. You must be able to forward all Kerberos tokens provided to DFS through the API web services. The local Java API accepts only Kerberos Ticket Granting Tickets (TGTs). This section focuses on using the DFS Kerberos API to integrate DFS-based local and remote DFS users with DFS services that interact with Content Server instances that are enabled for Kerberos authentication. General information about Kerberos, as well as details about obtaining service tickets from a Kerberos KDC, are outside the scope of this documentation. For more information pertaining to Kerberos, see the information on the following websites. For general information on Kerberos, refer to: For information on the Java GSS API: For additional information on Kerberos single sign-on in Java refer to A Detailed Review 27