# Kerberos

A backport of 2.0 new Kerberos authentication module has been done for 1.9.14. See Kerberos to see how to use it.

## Presentation

This documentation will explain how to use Active Directory as Kerberos server, and provide transparent authentication to AD domain users to LL::NG.

We will present several architectures:

- Single LL::NG server linked to one AD domain
- LL::NG cluster linked to one AD domain
- LL::NG cluster linked to two AD domains

## Prerequisites

### Example values

We will use the following values in our examples

- EXAMPLE.COM: First AD domain
- ACME.COM: Second AD domain
- auth.example.com: DNS of the LL::NG portal
- authpwd.example.com: DNS of the LL::NG portal (to failback to a form based authentication)
- node1.example.com: DNS of the first LL::NG portal server (in cluster mode)
- node2.example.com: DNS of the second LL::NG portal server (in cluster mode)
- ad.example.com: DNS of First Active Directory
- ad.acme.com: DNS of Second Active Directory
- KERB_AUTH: AD account to generate the keytab for LL::NG server (in single mode)
- KERB_NODE1: AD account to generate the keytab for the first LL::NG server (in cluster mode)
- KERB_NODE2: AD account to generate the keytab for the second LL::NG server (in cluster mode)

### Server time

It is mandatory that LL::NG servers and AD servers have the same time. It is recommended to use NTP to do this.

### DNS

All names must be registered in the DNS server (which is Active Directory). The reverse DNS should also work for all the names.

### AD accounts

It is recommended to create an AD account for each LL::NG server. Each account will hold the Service Principal Name (SPN) of the LL::NG server.

It should be possible to have the same account for all SPN, but this may require some manipulations on AD (command setspn) that are not documented here.

### Web browser configuration

#### Firefox

Type `about:config` in a tab and search for `trusted`. Then edit the property `network.negotiate-auth.trusted-uris` and set value `example.com`.

#### Internet Explorer

Add `https://auth.example.com` as trusted site.

Check into security parameters that Kerberos authentication is allowed.

### Apache Kerberos module installation

On CentOS/RHEL:

    yum install mod_auth_kerb

On Debian/Ubuntu:

    apt-get install libapache2-mod-auth-kerb

The module must be loaded by Apache (LoadModule directive).

## Single LL::NG Server / Single AD domain

### Client Kerberos configuration

On LL::NG server, edit `/etc/krb5.conf`:

    [libdefaults]
     default_realm = EXAMPLE.COM
     dns_lookup_kdc = false
     dns_lookup_realm = no
     ticket_lifetime = 24h
     forwardable = yes
     renewable = true

    [realms]
     EXAMPLE.COM = {
      kdc = ad.example.com
      admin_server = ad.example.com
     }

    [domain_realm]
     .example.com = EXAMPLE.COM
     example.com = EXAMPLE.COM

You can check that Kerberos is working by trying to get a ticket for a user of the domain (for example coudot):

    kinit coudot@EXAMPLE.COM

You should be prompted to enter password. Then list the tickets:

    klist -e

You should see a krbtgt ticket:

    Valid starting     Expires            Service principal
    06/04/15 15:43:24  06/05/15 01:43:29  krbtgt/EXAMPLE.COM@EXAMPLE.COM
            renew until 06/05/15 15:43:24, Etype (skey, tkt): aes256-cts-hmac-sha1-96, aes256-cts-hmac-sha1-96

You can then close the Kerberos session:

    kdestroy

### Obtain keytab file

You have to run this command on Active Directory:

    ktpass -princ HTTP/auth.example.com@EXAMPLE.COM -mapuser KERB_AUTH@EXAMPLE.COM -crypto DES-CBC-MD5 -ptype KRB5_NT_PRINCIPAL -mapOp set -pass <PASSWORD> -out c:\auth.keytab

The values passed in -crypto and -ptype depend on the Active Directory version and the windows version of the workstations. You can for example use RC4-HMAC-NT as crypto protocol if DES is not supported by workstations (this the case by default for Window 8 for example).

The file `auth.keytab` should then be copied (with a secure media) to the Linux server (for example in `/etc/lemonldap-ng`).

Change rights on keytab file:

    chown apache /etc/lemonldap-ng/auth.keytab
    chmod 600 /etc/lemonldap-ng/auth.keytab

You can check the validity of the keytab file by trying to request a service ticket, and compare the result with the keytab content.

Open a Kerberos session (like done in the previous step):

    kinit coudot@example.com

Request a service ticket:

    kvno HTTP/auth.example.com@EXAMPLE.COM

The result of the command should be:

    HTTP/auth.example.com@EXAMPLE.COM: kvno = 3

Read the service ticket:

    klist -e

You should see this kind of ticket:

    06/04/15 16:28:49  06/05/15 02:28:11  HTTP/auth.example.com@EXAMPLE.COM
            renew until 06/05/15 16:28:07, Etype (skey, tkt): arcfour-hmac, arcfour-hmac

You can close the Kerberos session:

    kdestroy

Now you can compare the above result with the same request done trough the keytab file:

    klist -e -k -t /etc/lemonldap-ng/auth.keytab

The result of the command should be:

    Keytab name: FILE:/etc/lemonldap-ng/auth.keytab
    KVNO Timestamp         Principal
    ---- ----------------- --------------------------------------------------------
       3 01/01/70 01:00:00 HTTP/auth.example.com@EXAMPLE.COM (arcfour-hmac)

The important things to check are:

- KVNO must be the same
- Principal names must be the same
- Encryption types must be the same

### Configuration of LemonLDAP::NG

See Apache authentication module configuration.

### Configuration of portal virtual host

First, copy the current portal virtual host definition into a new one. Use `authpwd` server name for this virtual host:

    <VirtualHost *>
        ServerName authpwd.example.com

        ...

    </VirtualHost>

This virtual host will be used by clients that fail to use the Kerberos protocol.

Then, modify the main portal virtual host to load the Apache Kerberos authentication module :

    <VirtualHost *>
      ServerName auth.example.com

      DocumentRoot /var/lib/lemonldap-ng/portal/

      <Directory /var/lib/lemonldap-ng/portal/>
        Order allow,deny
        Allow from all
        Options +ExecCGI +FollowSymLinks
      </Directory>

      ErrorDocument 401 /login.pl
      <LocationMatch ^/(?!login.pl)>
        <IfModule auth_kerb_module>
          AuthType Kerberos
          KrbMethodNegotiate On
          KrbMethodK5Passwd Off
          KrbAuthRealms EXAMPLE.COM
          Krb5KeyTab /etc/lemonldap-ng/auth.keytab
          KrbVerifyKDC Off
          KrbServiceName HTTP/auth.example.com
          require valid-user
        </IfModule>
      </LocationMatch>

    </VirtualHost>

### Redirection script

Create a redirection script, called login.pl:

    vi /var/lib/lemonldap-ng/portal/login.pl

    #!/usr/bin/perl
    use CGI ':cgi-lib';
    use strict;
    use CGI::Carp 'fatalsToBrowser';
    my $uri = $ENV{"REQUEST_URI"};
    print CGI::header(-Refresh => '0; URL=https://authpwd.example.com'.$uri);
    exit(0);

The redirection script is needed if you use a failaback authentication. If not, you can just keep a single virtual host (the authentication will fail if Kerberos negotiation do not succeed).

## LL::NG Cluster / Single AD domain

### Client Kerberos configuration

The client Kerberos configuration is the same as a single LL::NG server.

### Obtain keytab file

You need to get a keytab for each LL::NG node.

Commands on Active Directory will be:

    ktpass -princ HTTP/node1.example.com@EXAMPLE.COM -mapuser KERB_NODE1@EXAMPLE.COM -crypto DES-CBC-MD5 -ptype KRB5_NT_PRINCIPAL -mapOp set -pass <PASSWORD> -out c:\authnode1.keytab
    ktpass -princ HTTP/node2.example.com@EXAMPLE.COM -mapuser KERB_NODE2@EXAMPLE.COM -crypto DES-CBC-MD5 -ptype KRB5_NT_PRINCIPAL -mapOp set -pass <PASSWORD> -out c:\authnode2.keytab

Copy the generated keytab on each node (rename it as auth.keytab to have the same Apache configuration on each node).

Change rights on keytab file:

    chown apache /etc/lemonldap-ng/auth.keytab
    chmod 600 /etc/lemonldap-ng/auth.keytab

You can do the same check for the keytab as with the single LL::NG server. Just use node1.example.com and node2.example.com instead of auth.example.com.

### Configuration of LemonLDAP::NG

The configuration is the same as a single LL::NG server.

### Configuration of portal virtual host

The only change in Apache configuration is in the `KrbServiceName`, it should be set to Any:

        KrbServiceName Any

## LL::NG Cluster / Two AD domains

### Client Kerberos configuration

The two domains must be defined in `/etc/krb5.conf`:

    [libdefaults]
     default_realm = EXAMPLE.COM
     dns_lookup_kdc = false
     dns_lookup_realm = no
     ticket_lifetime = 24h
     forwardable = yes
     renewable = true

    [realms]
     EXAMPLE.COM = {
      kdc = ad.example.com
      admin_server = ad.example.com
      default_domain = EXAMPLE.COM
     }
     ACME.COM = {
      kdc = ad.acme.com
      admin_server = ad.acme.com
      }

    [domain_realm]
     .example.com = EXAMPLE.COM
     example.com = EXAMPLE.COM
     .acme.com = ACME.COM
     acme.com = ACME.COM

You should then be able to open a Kerberos session on each domain:

    kinit coudot@EXAMPLE.COM
    klist -e
    kdestroy

    kinit coudot@ACME.COM
    klist -e
    kdestroy

### Obtain keytab file

You need to obtain a keytab for each node on each domain. This means the ktpass commands should be run on both AD.

Then you will have 2 keytab files for each node, for example:

- node1-example.keytab
- node1-acme.keytab

You need to concatenate the keytab files, thanks to `ktutil` command:

    ktutil
    ktutil: read_kt node1-example.keytab
    ktutil: read_kt node1-acme.keytab
    ktutil: write_kt /etc/lemonldap-ng/auth.keytab
    ktutil: quit

You can then remove the original keytab files and protect the final keytab file:

    chown apache /etc/lemonldap-ng/auth.keytab
    chmod 600 /etc/lemonldap-ng/auth.keytab

### Configuration of LemonLDAP::NG

The configuration is the same as a single LL::NG server.

### Configuration of portal virtual host

The configuration is the same as with a single AD domain.

## Other resources

You can check these documentations to get more information:

- http://modauthkerb.sourceforge.net/configure.html
- http://www.grolmsnet.de/kerbtut/