Configuring the CIFS and web servers for Kerberos/AD integration

[resplin]

Obsolete Pages{{Obsolete}}

The official documentation is at: http://docs.alfresco.com

AuthenticationKerberosInstallation
2.x3.03.1

This page describes configuration methods prior to Alfresco Version 3.2. Refer to Alfresco Authentication Subsystems for Alfresco Versions 3.2 and up.

To enable Kerberos support against Active Directory in the Alfresco CIFS and web servers requires that the servers have a Kerberos service ticket.

The following instructions detail how to setup accounts under Active Directory for use by the Alfresco CIFS and web servers to allow single sign-on for CIFS and web clients :-

Table of Contents

• 1 Users in AD


• 2 Key tables


• 3 Service Principal Names (SPN)


• 4 key tables on alfresco


• 5 krb5.ini/krb5.conf files


• 6 Java (JVM) setup
  
  
  
  • 6.1 JBoss 5
  
  
  • 6.2 Other Environments
  
  


• 7 CIFS and the file-servers.xml/file-servers-custom.xml files


• 8 HTTP and the web.xml file


• 9 Webdav and the web.xml file


• 10 kerberos and web scripts


• 11 kerberos client configuration
  
  
  
  • 11.1 Firefox
  
  
  • 11.2 Chrome
  
  


• 12 debugging

Users in AD

Create a user account for the Alfresco CIFS server using the Active Directory Users and Computers application. Use the Action->New->User menu, then enter the full name as 'Alfresco CIFS' and the user logon name as 'alfrescocifs'. Click Next, enter a password, enable 'Password never expires' and disable 'User must change password at next logon'. Click Finish.
Right click the new user account name, select Properties, go to the Account tab and enable the Use DES encryption types for this account and Do not require Kerberos preauthentication options in the Account Options section.

Create a user account for the Alfresco web server as in step 1 using the full name 'Alfresco HTTP' and user logon name as 'alfrescohttp'.

Key tables

Use the ktpass utility to generate key tables for the CIFS and web servers. The ktpass utility is a free download from the Microsoft site, and is also part of the Win2003 Resource Kit. The ktpass command can only be run from the Active Directory server.

ktpass -princ cifs/<cifs-server-name>.<domain>@<realm> -pass <password> -mapuser <domainnetbios>\alfrescocifs
-crypto DES-CBC-MD5 -ptype KRB5_NT_PRINCIPAL -mapop set +desonly -out c:\temp\alfrescocifs.keytab

ktpass -princ HTTP/<web-server-name>.<domain>@<realm> -pass <password> -mapuser <domainnetbios>\alfrescohttp
-crypto DES-CBC-MD5 -ptype KRB5_NT_PRINCIPAL -mapop set +desonly -out c:\temp\alfrescohttp.keytab

The principal should be specified using the server name and domain in lowercase with the realm in uppercase. The service types should match cifs and HTTP. Eg. cifs/server.alfresco.org@ALFRESCO.ORG.

The realm should be the domain upper cased; example if the domain is alfresco.org then the realm should be ALFRESCO.ORG

<domain> is the DNS domain, example alfresco.org
<domainnetbios> is the netbios name, example alfresco

Note: Some versions of the ktpass command can generate invalid keytab files, download the latest version of the resource kit tools from the Microsoft site to avoid any problems.

Service Principal Names (SPN)

Create the Service Principal Names (SPN) for the Alfresco CIFS and web server using the setspn utility. The setspn utility is a free download from the Microsoft site, and is also part of the Win2003 Resource Kit.

setspn -a cifs/<cifs-server-name> alfrescocifs
setspn -a cifs/<cifs-server-name>.<domain> alfrescocifs

setspn -a HTTP/<web-server-name> alfrescohttp
setspn -a HTTP/<web-server-name>.<domain> alfrescohttp

<cifs-server-name> is the NetBIOS name of the Alfresco CIFS server when running on an Active Directory client or the host name for a client that is not an Active Directory client, ie. not logged onto the domain.

<web-server-name> is the host name that is running the Alfresco server.

Some versions of the ktpass command will add the SPN for the principal so you may only need to add the NetBIOS/short name versions of the SPNs. Use the setspn -l <account-name> command to check if the ktpass' command set the SPN.

You can list the SPNs for a server using :-

setspn -l <account-name>

That is:

setspn -l alfrescocifs
setspn -l alfrescohttp

Note: the servicePrincipalName (SPN) attribute is a multivalued, nonlinked attribute within the Active Directory directory. It can thus also be shown with standard LDAP clients. For instance the commands below show how to use the 'ldapsearch' tool to check the servicePrincipalName and userPrincipalName of the created users. The example below assumes the AD server is at IP 10.69.69.99, the domain is 'example.foo', and the alfresco server name is 'madona'.

ldapsearch -h 10.69.69.99 -x -D 'CN=Administrator,CN=Users,DC=example,DC=foo' \
-W -b 'DC=example,DC=foo' '(servicePrincipalName=cifs*)' 

will show

# Alfresco CIFS, example.foo
dn: CN=Alfresco CIFS,DC=example,DC=foo
...
userPrincipalName: cifs/madona.example.foo@EXAMPLE.FOO
servicePrincipalName: cifs/madona
servicePrincipalName: cifs/madona.example.foo
...

and

ldapsearch -h 10.69.69.99 -x -D 'CN=Administrator,CN=Users,DC=example,DC=foo' \
-W -b 'DC=example,DC=foo' '(servicePrincipalName=HTTP*)'

will show

# Alfresco HTTP, example.foo
dn: CN=Alfresco HTTP,DC=example,DC=foo
...
userPrincipalName: HTTP/madona.example.foo@EXAMPLE.FOO
servicePrincipalName: HTTP/madona
servicePrincipalName: HTTP/madona.example.foo
...

key tables on alfresco

Copy the key table files created in step 3 to the server where Alfresco will run. Copy the files to a protected area such as C:\etc\ or /etc.

krb5.ini/krb5.conf files

Setup the Kerberos ini file, the default location is C:\WINNT\krb5.ini or /etc/krb5.conf.

[libdefaults]
 default_realm = ALFRESCO.ORG


[realms]
 ALFRESCO.ORG = {
  kdc = adsrv.alfresco.org
  admin_server = adsrv.alfresco.org
 }


[domain_realm]
 adsrv.alfresco.org = ALFRESCO.ORG
 .adsrv.alfresco.org = ALFRESCO.ORG

Note: The realm should be specified in uppercase.

Java (JVM) setup

JBoss 5

Edit $JBOSS_HOME/server/default/conf/login-config.xml and add the following entries inside the <policy> tag.

 <application-policy name='AlfrescoCIFS'>
   <authentication>
     <login-module code='com.sun.security.auth.module.Krb5LoginModule' flag='required'>
       <module-option name='debug'>true</module-option>
       <module-option name='storeKey'>true</module-option>
       <module-option name='useKeyTab'>true</module-option>
       <module-option name='keyTab'>C:/etc/alfrescocifs.keytab</module-option>
       <module-option name='principal'>cifs/<cifs-server-name>.domain</module-option>
     </login-module>
   </authentication>
 </application-policy> 

 <application-policy name='AlfrescoHTTP'>
   <authentication>
     <login-module code='com.sun.security.auth.module.Krb5LoginModule' flag='required'>
       <module-option name='debug'>true</module-option>
       <module-option name='storeKey'>true</module-option>
       <module-option name='useKeyTab'>true</module-option>
       <module-option name='keyTab'>C:/etc/alfrescohttp.keytab</module-option>
       <module-option name='principal'>HTTP/<web-server-name>.<domain></module-option>
     </login-module>
   </authentication>
 </application-policy>

Other Environments

Set up the Java login configuration file. This would usually be in the JRE\lib\security folder. Create a file named java.login.config with the following entries :-

AlfrescoCIFS {
   com.sun.security.auth.module.Krb5LoginModule required
   storeKey=true
   useKeyTab=true
   keyTab='C:/etc/alfrescocifs.keytab'
   principal='cifs/<cifs-server-name>.<domain>';
};

AlfrescoHTTP {
   com.sun.security.auth.module.Krb5LoginModule required
   storeKey=true
   useKeyTab=true
   keyTab='C:/etc/alfrescohttp.keytab'
   principal='HTTP/<web-server-name>.<domain>';
};

Enable the login config file in the main Java security configuration file, usually at JRE\lib\security\java.security. Add the following line :-

login.config.url.1=file:${java.home}/lib/security/java.login.config

CIFS and the file-servers.xml/file-servers-custom.xml files

Configure the Alfresco CIFS server to use the Kerberos authenticator in the file-servers.xml file :-

<config evaluator='string-compare' condition='Filesystem Security'>
  <authenticator type='enterprise'>
    <KDC>adsrv.alfresco.org</KDC>
    <Realm>ALFRESCO.ORG</Realm>
    <Password>...</Password>
    <Principal>...</Principal>
  </authenticator>
</config>

<KDC> specifies the IP address or DNS name of the Active Directory server.
<Realm> is the Kerberos realm.
<Password> is the account password used when creating the alfrescocifs account in step 1.
<Principal> is the value used for the ktpass -princ parameter. I.e. if you typed 'ktpass -princ cifs/<web-server-name>.<domain>@<realm>', then you need to enter 'cifs/<web-server-name>.<domain>'
The optional <LoginEntry> specifies the login configuration file entry name, this defaults to AlfrescoCIFS.

Note: The Principal setting has been removed from recent versions as we can now get that value automatically after the server side Kerberos logon during startup.

Note: in 3.X versions of alfresco, the kerberos authentication section is now within the 'CIFS Server' section and not in the 'Filesystem Security' section anymore. Please look at the file-servers.xml file to custom your file-servers-custom.xml

 <alfresco-config area='file-servers'>


   <config evaluator='string-compare' condition='CIFS Server'>
.
.
.

     <authenticator type='enterprise'>
         <KDC>ad.alfresco.org</KDC>
         <Realm>ALFRESCO.ORG</Realm>
         <Password>password</Password>

         <kerberosDebug/>
         <Debug/>
      </authenticator>
.
.
.
</config>
.
.
.

In 3.X you don't need to specify <Principal> now as alfresco gets that during the initialization code after the server side logon.

HTTP and the web.xml file

Configure the Alfresco web server to use the Kerberos authentication web filter, in the web.xml file :-

  <filter>
     <filter-name>Authentication Filter</filter-name>
     <filter-class>org.alfresco.web.app.servlet.KerberosAuthenticationFilter</filter-class>
     <init-param>
       <param-name>KDC</param-name>
       <param-value>adsrv.alfresco.org</param-value>
     </init-param>
     <init-param>
       <param-name>Realm</param-name>
       <param-value>ALFRESCO.ORG</param-value>
     </init-param>
     <init-param>
       <param-name>Password</param-name>
       <param-value>...</param-value>
     </init-param>
     <init-param>
       <param-name>Principal</param-name>
       <param-value>...</param-value>
     </init-param>
  </filter>

Webdav and the web.xml file

Configure the Alfresco WebDAV server to use the Kerberos authentication web filter. in the web.xml file :-

  <filter>
     <filter-name>WebDAV Authentication Filter</filter-name>
     <filter-class>org.alfresco.repo.webdav.auth.KerberosAuthenticationFilter</filter-class>
     <init-param>
       <param-name>KDC</param-name>
       <param-value>adsrv.alfresco.org</param-value>
     </init-param>
     <init-param>
       <param-name>Realm</param-name>
       <param-value>ALFRESCO.ORG</param-value>
     </init-param>
     <init-param>
       <param-name>Password</param-name>
       <param-value>...</param-value>
     </init-param>
     <init-param>
       <param-name>Principal</param-name>
       <param-value>...</param-value>
     </init-param>
  </filter>

For version 2.2SP1 and 2.1SP5 and above two new Enterprise CIFS authenticator configuration options have been introduced:

1. <kerberosDebug/> Enable the Sun JGSS/Kerberos debug output. This sets up the Java properties sun.security.jgss.debug=true and sun.security.krb5.debug=true
   
2. <disableNTLM/> Do not advertise NTLMSSP support in SPNEGO mechTypes list.
   

They should be inserted within the <authenticator/> tag.

kerberos and web scripts

In the 2.1, 2.2, 3.0 and 3.1 branches, the '/wcservice/*' and '/wcs/*' mappings should be filtered in the web.xml to use kerberos.

This means that you will need to uncomment all the mppings as you would do for NTLM and change the two mappings below from:

  <filter-mapping>
     <filter-name>WebScript NTLM Authentication Filter</filter-name>
     <url-pattern>/wcservice/*</url-pattern>
  </filter-mapping>
  
  <filter-mapping>
     <filter-name>WebScript NTLM Authentication Filter</filter-name>
     <url-pattern>/wcs/*</url-pattern>
  </filter-mapping>

to

  <filter-mapping>
     <filter-name>Authentication Filter</filter-name>
     <url-pattern>/wcservice/*</url-pattern>
  </filter-mapping>
  
  <filter-mapping>
     <filter-name>Authentication Filter</filter-name>
     <url-pattern>/wcs/*</url-pattern>
  </filter-mapping>

kerberos client configuration

Firefox

When using firefox on Windows as client, you will need to add your alfresco server name to the network.negotiate-auth.trusted-uris variable
You can access the variable going to the special URL: about:config

When using firefox under Linux, you will need to add your alfresco server name to network.negotiate-auth.trusted-uris as above but you will need in addition to get a kerberos ticket using the kinit command. Note that the ticket can correspond to a different user than your linux username

 kinit user1

where user1 is an active directory user.
Note that if the client and the server are on the same machine, you will need to go to the eternl interface. The loopback interface won't be able to authenticate.
You can view your tickets using klist.

Chrome

1) create a ticket on the linux client:

kinit -f -p user1

klist
Ticket cache: FILE:/tmp/krb5cc_1000
Default principal: user1@EXAMPLE.FOO

Valid starting    Expires           Service principal
14/12/2012 12:10  14/12/2012 22:10  krbtgt/EXAMPLE.FOO@EXAMPLE.FOO
renew until 15/12/2012 12:10

2) To use alfresco explorer:

chromium --auth-server-whitelist=madona:8080 http://madona:8080/alfresco

3) To use share:

chromium --auth-server-whitelist=madona:8080 --auth-negotiate-delegate-whitelist=madona:8080 http://madona:8080/alfresco

Links:

http://dev.chromium.org/developers/design-documents/http-authentication
http://askubuntu.com/questions/61100/use-generated-kerberos-tickets-in-chromium-browser

To enable Kerberos for Chrome on Windows:

Create the following registry key with your server.domain listed as follows:

[HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Google\Chrome]
'AuthNegotiateDelegateWhitelist'='myserver,myotherserver,*.mydomain.local'

See:  http://dev.chromium.org/administrators/policy-list-3#AuthNegotiateDelegateWhitelist

debugging

You can debug kerberos issues using the log4j properties below:

log4j.logger.org.alfresco.web.app.servlet.KerberosAuthenticationFilter=debug
log4j.logger.org.alfresco.repo.webdav.auth.KerberosAuthenticationFilter=debug

A sample login output follows:

18:46:27,915 DEBUG [app.servlet.KerberosAuthenticationFilter] New Kerberos auth request from 192.168.4.95 (192.168.4.95:38750)
18:46:28,063 DEBUG [app.servlet.KerberosAuthenticationFilter] User user1 logged on via Kerberos

For cifs you can as described above use:

<kerberosDebug/> in the <authenticator> section

It enables the Sun JGSS/Kerberos debug output. This sets up the Java properties sun.security.jgss.debug=true and sun.security.krb5.debug=true