Kerberos configuration for DFS 6.7 SP1

In my last post, I explained how to configure Kerberos for a CS 6.7 SP1. Unfortunately if you only configure the Content Server, it will almost be useless… If you want this configuration to be useful, then you will also have to configure the Kerberos SSO for the Documentum Foundation Services (DFS). That’s why in this blog post I will describe step by step what need to be done for that purpose.
So what are the pre-requisites to setup the Kerberos SSO for the Documentum Foundation Services? Well of course you will need an application server for your DFS, a Content Server that is already installed and an Active Directory to generate the keytab(s). Just to let you know, I used (for the DFS) a Tomcat application server that is on the Content Server’s machine and an Active Directory on a Windows Server 2008 R2. Let’s define the following properties:

• Active Directory – user = dfskrb
• Active Directory – password = ##dfskrb_pwd##
• Active Directory – domain = DOMAIN.COM
• Active Directory – hostname1 = adsrv1.domain.com
• Active Directory – hostname2 = adsrv2.domain.com
• Alias of the DFS’ host = csdfs.domain.com (can be a Load Balancer alias)
• $CATALINA_HOME = /opt/tomcat

I. Active Directory prerequisites

As always when working with Kerberos on an Active Directory, the first thing to do is to create a user. So let’s create this user with the following properties:

• User name: dfskrb
• Support AES 128 bits encryption
• This account MUST NOT support AES 256 bits encryption. I set it that way because the Content Server doesn’t support AES 256 bits encryption so I disabled it for the DFS part too.
• Trust for Delegation to any service (Kerberos Only)
• Password never expires
• Account never expires
• Account not locked

Once the user has been created, you can proceed with the keytab creation using the comment prompt on the Active Directory host:

For the Content Server part, the name of the “princ” (SPN) has to be “CS/##repository_name##”. For the DFS part, the EMC documentation ask you to generate a keytab with a SPN that is “DFS/##dfs_url##:##dfs_port##”. In fact, if you are going to use only one DFS url/port, then you don’t need to add the port in the SPN of the DFS.
Regarding the name of the keytab, for the Content Server part, it has to be “##repository_name##.keytab” for the Content Server to be able to automatically recognize it during the server re-initialization. For the DFS part, the name of the keytab isn’t important because you will have to configure it manually.

II. Configuration of the Documentum Foundation Services side

So let’s start the configuration of the Kerberos SSO for the DFS. The first thing to do is of course to transfer the keytab created previously (dfs.keytab) from the Active Directory to the host of the DFS (a Linux in my case). There are no specific locations for this keytab so you just have to put it somewhere and remember this location. For this example, I will create a folder that will contain all elements that are required. Please make sure that the keytab belongs to the Documentum installation owner (user and group) on the file system with the appropriate permissions (640).

[dmadmin ~]$ echo $CATALINA_HOME
/opt/tomcat
[dmadmin ~]$ mkdir /opt/kerberos
[dmadmin ~]$ mv ~/dfs.keytab /opt/kerberos
[dmadmin ~]$ chmod 640 /opt/kerberos/dfs.keytab

Create the file “/opt/kerberos/jaasDfs.conf” with the following content:

[dmadmin ~]$ cat /opt/kerberos/jaasDfs.conf
DFS-csdfs-domain-com {
com.sun.security.auth.module.Krb5LoginModule required
debug=true
principal="DFS/[email protected]"
realm="DOMAIN.COM"
refreshKrb5Config=true
noTGT=true
useKeyTab=true
storeKey=true
doNotPrompt=true
useTicketCache=false
isInitiator=false
keyTab="/opt/kerberos/dfs.keytab";
};

The first line of this file jaasDfs.conf is the name of the “module”. This name is derived from the SPN (or principal) of the DFS: take the SPN, keep the uppercase/lowercase characters, remove the REALM (everything that is after the at-sign (included)) and replaced all special characters (slash, back-slash, point, colon, aso…) with a simple dash “-“.
The next thing to do is to modify the DFS war file. So let’s create a backup of this file and prepare its modification:

[dmadmin ~]$ cd $CATALINA_HOME/webapps/
[dmadmin ~]$ cp emc-dfs.war emc-dfs.war.bck_$(date +%Y%m%d)
[dmadmin ~]$ cp emc-dfs.war /tmp/
[dmadmin ~]$ cd /tmp
[dmadmin ~]$ unzip emc-dfs.war -d /tmp/emc-dfs


The setup of the Kerberos SSO requires some jar files that aren’t necessarily present on a default installation. For that purpose, you can copy these jar files from the Content Server to the new dfs:

[dmadmin ~]$ cp $DOCUMENTUM/product/dfc6.7/dfc/jcifs-krb5-1.3.1.jar /tmp/emc-dfs/WEB-INF/lib/
[dmadmin ~]$ cp $DOCUMENTUM/product/dfc6.7/dfc/krbutil.jar /tmp/emc-dfs/WEB-INF/lib/
[dmadmin ~]$ cp $DOCUMENTUM/product/dfc6.7/dfc/vsj-license.jar /tmp/emc-dfs/WEB-INF/lib/
[dmadmin ~]$ cp $DOCUMENTUM/product/dfc6.7/dfc/vsj-standard-3.3.jar /tmp/emc-dfs/WEB-INF/lib/
[dmadmin ~]$ cp $DOCUMENTUM/product/dfc6.7/dfc/questFixForJDK7.jar /tmp/emc-dfs/WEB-INF/lib/

Once done, a Kerberos handler must be added to the DFS. For that purpose, open the file authorized-service-handler-chain.xml, locate the XML comment that start with “Any handler using ContextFactory” and add the following lines just before this comment:

Then, some Kerberos specific configurations must be added to the web.xml file. For that purpose, open this file and add the following lines at the end, just before the web-app end tag (before the last line):

In the above configuration, only the “env-entry-value” for each “env-entry” section should be changed to match your environment. As you can see, the krb5.conf file referenced here is in /opt/kerberos. You can use the same krb5.conf file as the one used for the Content Server or you can specify a separate file. As this file can be the same for the Content Server and the DFS I will not set it here but just check my last post to get more information about that.
So the configuration is now over and you can just repackage and re-deploy the new DFS:

[dmadmin ~]$ cd /tmp/emc-dfs/
[dmadmin ~]$ jar -cvf emc-dfs.war *
[dmadmin ~]$ $CATALINA_HOME/bin/shutdown.sh
[dmadmin ~]$ mv emc-dfs.war $CATALINA_HOME/webapps/
[dmadmin ~]$ cd $CATALINA_HOME
[dmadmin ~]$ rm -Rf emc-dfs/
[dmadmin ~]$ $CATALINA_HOME/bin/startup.sh

Once done, the Tomcat application server should have been started and the new version of the DFS WAR file should have been deployed. If the Content Server and the DFS are properly setup to use the Kerberos SSO, then you should be able to execute a .NET or Java code to get a Kerberos Ticket for the DFS and work with the DFS features.