WORK IN PROGRESS - This HOWTO is not complete! The client setup section works, however.

1. Introduction

This page describes how to set up network-connected Ubuntu machines to support Single Sign On (SSO). SSO is a name for a collection of technologies that allows network users to provide a single set of credentials for all network services. A central location that stores all user, group and password data for the users on your network.

The solution detailed in this guide uses OpenLDAP to provide authorization and MIT Kerberos to provide authentication. This guide is divided in to several sections that describe installation of required server software, testing, and installation of software on the client.

There are three basic functions that a Single Sign On solution must perform:

• Authentication: Verification that a user or server is who they claim to be and providing a mechanism for passing this information throughout the network.
• Accounting: User information and group membership.
• Authorization: Information on what privileges are possessed by authenticated entities on the network

This solution uses Kerberos 5 for authentication and OpenLDAP for accounting.

2. Target Audience

To properly implement the practical steps found in this guide, the reader should be a user of Ubuntu who is comfortable with the use command-line applications, using the Bourne Again SHell (bash) environment, and editing system configuration files with their preferred text editor application. While previous familiarity with OpenLDAP or Kerberos is not required for this guide, the reader is advised to pursue further learning from the resources listed in the Resources section of this guide in order to broaden understanding of the technologies involved in SSO.

3. Authorization

Kerberos is an authentication protocol using a combination of secret-key cryptography and trusted third parties to allow secure authentication to network services over untrusted networks. This guide uses the MIT implementation of Kerberos as the authentication function of SSO.

See the Kerberos wiki page for instructions on installing and configuring MIT Kerberos.

4. Accounting

LDAP is the Lightweight Directory Access Protocol. It is designed to store data records and allow for easy access to the records via a simple network interface. LDAP can provide access to directory type information such as an address book for your email client, or a list of users and groups that have access to services on your network. This guide uses the OpenLDAP package for the accounting function of SSO.

The OpenLDAPServer page has detailed instructions on installing and populating an LDAP directory.

4.1. Securing LDAP Communication

Since you will be using OpenLDAP to provide authentication information to your network, you should encrypt all of the traffic between the server and clients. This will be done using SSL/TLS encryption. In order to do this, you must create keys for the server.

First, you will need a certification authority to sign your certificates. You can use one of the public Certificate Authorities, or create your own.¹ See the OpenSSL page for info on how to create a certificate authority and your own certificates.

Next, import your new CA certificate into /usr/share/ca-certificates, as described on the OpenSSL page, so that other software on your system will recognize your CA as trusted. When you create a certificate for your LDAP server, make sure the Common Name (CN) matches the hostname of the server where you are running slapd. Copy both the public and private key files to /etc/slapd/certs. In the /etc/slapd/certs directory, do the following:

sudo chown root:ldap *.pem
sudo chmod 640 *.pem

4.1.1. Configuring SSL in OpenLDAP

To use your server certificates with OpenLDAP

1. edit the slapd.conf file and include the following lines:

      TLSCACertificateFile /etc/ldap/ssl/cacert.pem
      TLSCertificateFile /etc/ldap/ssl/server_crt.pem
      TLSCertificateKeyFile /etc/ldap/ssl/server_key.pem 

2. edit /etc/default/slapd² and include the following line:

      SLAPD_SERVICES="ldaps://SERVER-NAME" 

   • Note that the above line enables only SSL access to your OpenLDAP server (port 636)

3. Restart slapd

4. You may test the SSL response using: openssl s_client -connect SERVER-NAME:636 -showcerts

5. On the client machine, edit /etc/ldap/ldap.conf and include the following lines:

      BASE    YOUR-BASE
      URI     ldaps://SERVER-NAME
      TLS_REQCERT allow 

   • Don't forget to replace the SERVER-NAME & YOUR-BASE with the correct values.

6. test using ldapsearch -x

4.1.2. LDAP Authentication Modes

4.1.2.1. Authenticated-only

See OpenLDAPServer for details on configuring OpenLDAP. In addition to the general configuration there, you should have the following lines in your slapd.conf. They will allow users to authenticate themselves to the LDAP server using Kerberos.

sasl-secprops noanonymous,noplain,noactive
authz-regexp uid=([^,]*),cn=[^,]*,cn=auth uid=$1,ou=People,dc=example,dc=com

This approach isn't without difficulties, however - you'll have to have either an admin password for the database, or a Kerberos principal that allows you to browse the directory in order to log in!

Not all sites will want to have an admin password for the database in the clear in a file on clients. Of course, anyone with root access to the client can then obtain your LDAP admin password. It's contrary to the Kerberos assumption that the KDC is trusted, but clients are not. For such sites, it is possible to have a 'Kerberized' way of accessing the directory that doesn't require passwords, but it's a bit of extra work. [XXX that isn't documented here yet.]

4.1.2.2. Anonymous Only

As an alternative approach to requiring Kerberos or an admin password to read the directory, you could make the directory readable to all. This is an option you might want to explore on LANs, where having people able to list the directory without authentication probably isn't the end of the world, and the extra effort required to setting up and renewing directory access tickets isn't really necessary. This is a more NIS-like approach to using LDAP as the directory service, but without some of NIS's more serious security problems.

A small change to the above slapd.conf extract allows this.

sasl-secprops none,noplain,noactive                                             
authz-regexp uid=([^,]*),cn=[^,]*,cn=auth uid=$1,ou=People,dc=example,dc=com

As you'll find in slapd.conf(5), the 'none' option turns off the defaults ('noanonymous,noplain', forbidding anonymous and plaintext logins respectively), and then 'noplain' of course turns plaintext authentication back off again. We want anonymous mode.

We'll not be publishing crypt'ed (or otherwise hashed) passwords to everyone. The default slapd.conf has this stanza:

access to attrs=userPassword,shadowLastChange
        by dn="cn=admin,dc=home,dc=ae-35,dc=com" write
        by anonymous auth
        by self write
        by * none

This means that the attribute simply won't be shown to anonymous logins. We don't have to worry about other permissions; because the LDAP-stored password isn't being used, we don't have to worry about letting users write to it in order to change their password.

[XXX This argument doesn't apply to changing the shell...]

5. Testing

5.1. Kerberos

From the KDC, type the following:

$ kinit

Type your password when prompted. If this was successful, you won't receieve any error messages. Next, test that you got a Ticket Granting Ticket (TGT) from the KDC. To do this type the following:

$ klist

The response should look something like this:

Ticket cache: FILE:/tmp/krb5cc_5001_PpRNvF
Default principal: user@SOMEREALM.COM

Valid starting     Expires            Service principal
05/28/06 08:18:09  05/28/06 18:18:09  krbtgt/SOMEREALM.COM@SOMEREALM.COM
        renew until 05/29/06 08:18:06


Kerberos 4 ticket cache: /tmp/tkt5001
klist: You have no tickets cached

Try these same two commands from another machine on your network. If these commands succeed, you have successfully installed the KDC.

5.2. OpenLDAP

• test SASL binds to the OpenLDAP directory

6. Client Installation

LDAPClientAuthentication may well also be of interest, particularly for caching.

6.1. Installing required packages

You need to install these packages on all machines on your network where you want to be able to use SSO. At the command line, type the following:

sudo apt-get install ldap-auth-client libpam-krb5 krb5-user libpam-foreground libsasl2-modules-gssapi-mit

6.1.1. Configuring LDAP

The ldap-auth-config package (depended upon by ldap-auth-client) has a debconf script to help you create the LDAP configuration file. This script will be run automatically when you install the package.

• The first step is to enter the URI for your LDAP server. If you followed this howto's instructions on installing your server, this URI will be ldaps://<your server IP>/.

• Next, you need to enter the DN of your search base. Use the same DN that you used as the base for your user database.

• You will only be using LDAPv3, so choose the default on this screen.

• There's no need for local root to have full privileges over your LDAP server, so answer no here.

• If your LDAP server allows anonymous binds, you can answer 'no' here too. If you're ok with the script dropping a plaintext password in /etc/ldap.secret, then you can enter the password here. Otherwise, you answer 'no', but you have some work to do [XXX which is not documented here yet].

6.1.2. Configuring Kerberos

krb5-config has a debconf script to set up client-side Kerberos properly.

sudo dpkg-reconfigure -plow krb5-config

Enter your realm (EXAMPLE.COM, for example) when prompted. If you have set up DNS records to point to your KDC, answer yes to the relevant question. If not, you will be asked to specify the hostname of your KDC and admin server.

edit /etc/ldap/ldap.conf and include the following lines:

BASE    YOUR-BASE
URI     ldaps://SERVER-NAME
TLS_REQCERT allow

Replace the SERVER-NAME & YOUR-BASE with the correct values.

edit /etc/ldap.conf and include the following lines:

bind_policy soft

6.1.3. Configuring PAM and NSS

auth-client-config gives us an easy way to configure NSS and PAM. It doesn't come with a configuration for LDAP and Kerberos.

edit /etc/auth-client-config/profile.d/krb-auth-config and include the following lines:

[krb5ldap]
nss_passwd=passwd: files ldap
nss_group=group: files ldap
nss_shadow=shadow: files ldap
nss_netgroup=netgroup: files ldap
pam_auth=auth       sufficient   pam_krb5.so
         auth       required     pam_unix.so nullok_secure use_first_pass
pam_account=account    sufficient   pam_krb5.so
            account    required     pam_unix.so
pam_password=password   sufficient   pam_krb5.so
             password   required     pam_unix.so nullok obscure min=4 max=8 md5
pam_session=session    required     pam_unix.so
            session    required     pam_mkhomedir.so skel=/etc/skel/
            session    optional     pam_krb5.so
            session    optional     pam_foreground.so

[krb5ldap.cached]
nss_passwd=passwd: files ldap [NOTFOUND=return] db
nss_group=group: files ldap [NOTFOUND=return] db
nss_shadow=shadow: files ldap
nss_netgroup=netgroup: files ldap
pam_auth=auth   required       pam_env.so
         auth   sufficient     pam_unix.so likeauth nullok
         auth   [default=ignore success=1 service_err=reset] pam_krb5.so use_first_pass
         auth   [default=die success=done] pam_ccreds.so action=validate use_first_pass
         auth   sufficient pam_ccreds.so action=store use_first_pass
         auth   required        pam_deny.so
pam_account=account    sufficient   pam_krb5.so
            account    required     pam_unix.so
pam_password=password   sufficient   pam_krb5.so
             password   required     pam_unix.so nullok obscure min=4 max=8 md5
pam_session=session    required     pam_unix.so
            session    required     pam_mkhomedir.so skel=/etc/skel/
            session    optional     pam_krb5.so
            session    optional     pam_foreground.so

Now we can do the actual configuration. It's probably a good idea to have a root shell open while doing this, just in case something breaks.

sudo auth-client-config -a -p krb5ldap

At this stage, everything should work! Try getent passwd and getent group to check that users and groups from LDAP are appearing properly. Log in as one of the LDAP users, and use klist to confirm that you were automatically granted a TGT. Running passwd should change your Kerberos password.

6.1.3.1. Cached Credentials

sudo apt-get install nss-updatedb libnss-db libpam-cracklib libpam-ccreds

sudo nss_updatedb ldap

sudo auth-client-config -a -p krb5ldap.cached

6.1.4. Troubleshooting

If getent passwd doesn't show your users, you have something wrong with your LDAP configuration. Try using ldapsearch or similar to confirm that you are able to query the LDAP server. If that works, check your settings in /etc/ldap.conf.

If getent passwd shows your users but you can't log in, it's probably a Kerberos problem. Try kinit. It should prompt for your Kerberos password. If that works, check that you have a TGT with klist. If there's no TGT at this point, there's your problem - your client can't talk to your KDC properly. DNS issues are a possibility.

If you still can't log in, head over to your lifesaving root shell, and use auth-client-config to revert the settings.

auth-client-config -a -p krb5ldap -r

You may then debug at a later date without the risk of not being able to log into your system.

7. Application Installation

7.1. Apache2

First of all you need to create a principal and keytab for the webserver:

# sudo kadmin.local
kadmin> addprinc -randkey HTTP/wiki.example.com
kadmin> ktadd -k /etc/apache2/auth/apache2.keytab HTTP/webserver.example.com
kadmin> quit

Make sure the keytab has the right permissions and ownership:

# sudo chowm www-data:www-data /etc/apache2/auth/apache2.keytab
# sudo chmod 400 /etc/apache2/auth/apache2.keytab

Install mod_auth_kerb in your linux installation.

# sudo apt-get install libapache2-mod-auth-kerb

Update your http.conf file:

<Directory /var/www/>
        Options Indexes FollowSymLinks MultiViews
        AllowOverride None
        Order allow,deny
        allow from all

        AuthType Kerberos
        AuthName "Kerberos Login"
        KrbAuthRealm EXAMPLE.COM
        Krb5Keytab /etc/apache2/auth/apache2.keytab
        require valid-user
</Directory>

7.1.1. Further configuration

For configuring SSH servers to accept Kerberos authentication, see AdvancedOpenSSH. For NFS with Kerberos, see NFSv4Howto.

TODO:

• test SASL binds
• information on configuring nss-updatedb and nscd to cache LDAP information

CategorySecurity