Kerberos Authentication

The Kerberos Authentication addon allows your users to log in to the Nuxeo Platform by authenticating to a Kerberos server (eg. Active Directory).

Here's an how-to to help you configure the SPNEGO/Kerberos authentication for the Nuxeo Platform. Note that this it starts with OS relative guidelines.

Setting up Your Kerberos Server

Before you install and configure Kerberos on your Nuxeo Platform, you need to set up your Kerberos server and create credentials for the Nuxeo server.

On Linux

1. Configure Kerberos for your server and client. For example in a Debian-based Linux server install krb5-kdc and krb5-admin-server, and setup a realm (with krb5_newrealm).
2. Create a service principal and set its service principal name to HTTP/@REALM.

3. Export the service principal keytab In MIT Kerberos. Using kadmin, type the following commands (servername is the name of the Nuxeo Platform server):

   add_principal HTTP/servername (type in a password)
   

   Principal format

   The service principal MUST be formed as followed: uppercase HTTP slash the canonical (DNS-wise) name of the server. Any other names will not work (especially, aliases).

   ktadd -k /tmp/keytab HTTP/servername
   

   You may create as many principals you want and add their keys to the same keytab, e.g. HTTP/nuxeo@COMPANY and HTTP/nuxeo.company.com@COMPANY.

On Windows

1. In Microsoft Active Directory, create a user. Option "password does not expire" must be checked and "user must change password" unchecked.

2. In a command-line window, register the service principal name(s) you want this user to respond to (generally the server name in its short and fully qualified forms and it corresponds to the Nuxeo Platform server name).

   Service principal name format

   The service principal has to correspond to the server's canonical name in DNS.

   setspn -a HTTP/servername@REALM <username>
   setspn -a HTTP/fully.qualified.servername@REALM <username>
   

3. Check the SPNs with the command:

   setspn -l <username>
   

4. Export the keytab.

   ktpass /out C:\temp\http.keytab /princ HTTP/servername@REALM /mapuser domain\username /pass password /crypto RC4-HMAC-NT /ptype KRB5_NT_PRINCIPAL /kvno 0
   

   /mapuser and /pass should not be strictly necessary after setspn, but better be safe than sorry.

Setting up Kerberos on Your Nuxeo Server

1. Copy the keytab on your Nuxeo server.

2. Configure krb5.conf (/etc/krb5.conf or C:\Windows\krb5.ini, depending on the OS).

   Note that on Linux servers, while it is not strictly necessary, you should really install the MIT Kerberos user tools (krb5-user in Debian-like). This will setup a basic krb5.conf and give you debugging tools.

   The krb5.conf should minimally contain:

    [libdefaults]
           default_realm = REALM
        [realms]
             REALM = {
                  kdc = <kdc>
                  admin_server = <admin_server>
             }
        [domain_realm]
             domain = REALM
             .domain = REALM
   

   • kdc and admin_server are the names of your kdc and admin servers (duh). On Windows, both are your AD server. On Linux, kdc is where you've installed krb5-kdc and admin_server in where you've installed krb5-admin-server. Usually it's the same machine.
   • domain is the DNS domain you want to map to a realm. In Linux clients, specifying the realm is necessary. It's not on Windows, but again, better be safe than sorry.

3. Test the Kerberos installation. On Linux servers, you can test it with the command:

   kinit -k -t /path/to/keytab HTTP/servername@REALM
   

   There should be no errors and klist should list a krbtgt for your service. On my machine that looks like this:

   Ticket cache: FILE:/tmp/krb5cc_1000
   Default principal: HTTP/loremipsum@LOREMIPSUM
   Valid starting     Expires            Service principal
   15/12/12 11:35:36  15/12/12 21:35:36  krbtgt/LOREMIPSUM@LOREMIPSUM
     renew until 16/12/12 11:35:36
   

4. If you use your server as a Kerberos client too (e.g. it's a development machine!), delete the tgt with the command kdestroy.

Configuring the Nuxeo Platform

Using the Nuxeo Package

1. Add the following options in your nuxeo.conf:

   • kerberos.principal=_your kerberos principal_

   • kerberos.keytab=_/path/to/your/kerberos.keytab_

     Note: You must have configured the Kerberos setup in nuxeo.conf before installing the package. Otherwise package installation will fail.

2. Install the Nuxeo Kerberos addon. This addon requires no specific installation steps. It can be installed like any other package with nuxeoctl command line or from the Update Center.
   If you use the Admin Center, you will have to restart the server twice due to NXP-15592.

Manually

Configuring Java

To enable Kerberos, you need to use a login configuration implementation. You have two ways of doing this. Either change the default Java configuration or use JAVA_OPTS. Take a look at JAAS documentation for more details.

Changing the default JRE configuration

1. In $JAVA_HOME/jre/lib/security/java.security, find the login config url (it's commented out by default):

      #login.config.url.1=file:${user.home}/.java.login.config
   

2. Set this to a regular file, e.g. /opt/nuxeo/java.login.config.

Giving a Custom Login File as Java Argument

In nuxeo.conf, add the following line:

JAVA_OPTS=$JAVA_OPTS -Djava.security.auth.login.config=./java.login.config

Note that using one equal sign appends or overrides parts of the default java.security file, whereas using two equal signs completely overrides the default java.security file content.

JAVA_OPTS=$JAVA_OPTS -Djava.security.auth.login.config==./java.login.config

Configuring JAAS

If you have installed the Nuxeo Package, this file is already available at $NUXEO_HOME/java.login.config.

Open the java.login.config file you've setup and add the following configuration:

   Nuxeo {
  com.sun.security.auth.module.Krb5LoginModule required
  debug=true
  storeKey=true
  useKeyTab=true
  keyTab="/complete/path/to/keytab"
  principal="HTTP/servername@REALM";
 };

Configuring Nuxeo

1. Deploy the bundle in $NUXEO_HOME/nxserver/bundles.

2. Create a $NUXEO_HOME/nxserver/config/kerberos-config.xml with the following content:

   <?xml version="1.0"?>
    <component name="Kerberos-config">
     <require>org.nuxeo.ecm.platform.ui.web.auth.WebEngineConfig</require>
     <require>org.nuxeo.ecm.platform.ui.web.auth.defaultConfig</require>
     <require>org.nuxeo.ecm.platform.login.Kerberos</require>
     <documentation> This Authentication Plugin uses Kerberos to assert user identity. </documentation>
     <extension target="org.nuxeo.ecm.platform.ui.web.auth.service.PluggableAuthenticationService" point="authenticators">
      <authenticationPlugin name="KRB5_AUTH" enabled="true" class="org.nuxeo.ecm.platform.ui.web.auth.krb5.Krb5Authenticator">
       <loginModulePlugin>Trusting_LM</loginModulePlugin>
      </authenticationPlugin>
     </extension>
     <extension target="org.nuxeo.ecm.platform.ui.web.auth.service.PluggableAuthenticationService" point="chain">
      <authenticationChain>
       <plugins>
        <plugin>BASIC_AUTH</plugin>
        <plugin>KRB5_AUTH</plugin>
        <plugin>FORM_AUTH</plugin>
       </plugins>
      </authenticationChain>
     </extension>
     </component>
   

   For now we assume all configuration - realm, kdc, server principal, etc. − lives in the server's standard configuration, i.e. either java.login.config or krb5.conf. An interesting update would be to make these configurable in Nuxeo.

3. Start Nuxeo.

Configuring the Clients

On Windows:

• If the client is IE or Chrome, no further configuration should be necessary. Just ensure your Nuxeo server is in the Local intranet or Trusted sites security zone.
• If the client is Firefox, go to about:config, search for network.negotiate-auth.trusted-uris and set it to your full server URL.

On Linux, if the client is Firefox:

1. Go to about:config.
2. Search for network.negotiate-auth.trusted-uris and set it to your full server URL.
3. Configure krb5.conf as above.
4. Get a Kerberos ticket with kinit.

In the browser, type http://nuxeo_server:8080/nuxeo and… you should be authenticated!

Note

The authenticator supports a magic request header to disable it. Simply set the X-Skip-Kerberos request header and Nuxeo will move on to the next filter on the list. This is useful if you want integrated authentication from within a corporate network but not from outside: simply setup two Apache virtual hosts with an "internal" URL and an "external" URL. In the external virtual host, add the following directive:

RequestHeader set X-Skip-Kerberos true

and this will move on to form authentication.

Troubleshooting

If you have issues with the configuration of Kerberos in your environment, here is a few steps or tips that might help you finding the source of the issue.

Exception Realm not local to kdc while getting initial credentials while testing the kinit

• The Real defined in the keytab file is probably incorrect. If you are using AD, by default, the real name is the DNS domain name (not the Netbios domain name) in upper case

Exception Cannot create LoginContext, disabling Kerberos module during startup of the Nuxeo Platform server

• In the file java.login.config, verify that keytab file's path is properly set.
• In the file java.login.config, verify that the principal set is correct.

Tips for troubleshooting :

• It is possible to get the values of the principals present in the keytab file by executing the command kutil. More details on the Oracle documentation.
• To enable the debug mode in the logs for Kerberos, edit the nuxeo.conf file to add -Dsun.security.krb5.debug=true

More troubleshooting tips on the Oracle documentation.

Upgrade Notes

If you are upgrading from a version of the package lower than 1.3.0 (i.e. from Nuxeo 5.x), remove the -Djava.security.auth.login.config=xxx option from your nuxeo.conf: it is now automatically added by the package.

---