One of the most common processes a company's IT infrastructure goes through is the configuration of their authentication system. An authentication system allows multiple servers and workstations in an office to share authentication information such as user names and passwords. Other operating systems provide product offerings which get this job done: Microsoft Active Directory, for example. These products are most usually just a collection of services and protocols bundled together behind a easy to use interface.

The Linux desktop lacks this sort of interface.

Use Cases

  • A small company wants to set up a centralized office service to hold users and passwords. They want to configure their workstations to use this information when processing logins.

The system administrator begins by setting up a central server and installing Linux on it. The administrator completes this process and fires up a Domain Configuration Utility. This utility asks the administrator simple questions about some properties on his network. For instance, the location of his DNS server or weither he wants to set up one on his own. After completing this process the administrator has a server ready to process logins.

  • The system administrator goes to a client workstation and launches the Domain Configuration Utility, either manually, or as part of the desktop setup procedure. The Domain Configuration Utility detects the domain settings automatically using the current DNS server. If the settings are not present, they are asked for. They are confirmed with the administrator. The Administrator is prompted for his Domain Password. The machines information is created on the domain. The machine then has it's local configuration altered to refer to the domain server for authentication purposes.

Now users logging into the machine can login using their domain user name and password.

  • The system administer wants to set up a second server for his network to handle more volume. He sets up the server as in step one, but joins it to the domain as a client, as in step 2. When the Domain Configuration Utility is run his options differ slightly from step one. Instead of creating a new domain, the server is promoting itself to a server of the current domain. Hopefully all of the required information is known. If not he's prompted.

The administrators login is requested, the server checks for all the services as in step 1. Sets up a local LDAP server and a local Kerberos KDC. Replication is set up. DNS is modified with the proper SRV records. If any of this can't be done, the process is described to the user.


The protocols underlying the ideal authentication system are all well understood. The focus will be on the design of the interface for configuration of such a system and the "common scenarios". The proposed system is simply a combination of LDAP, Kerberos 5, DNS and DHCP working together. Relying on these technologies allows us to interoperate with the most common system (Active Directory) as well as many custom configurations.

The three common scenarios are listed below, and coorespond to the 3 use cases above.

  • Creating a new domain.
  • Joining to an existing domain.
  • Becoming a secondary server of an existing domain.

These can be broken down into logical steps:

  • Becoming a server.
  • Becoming a client.

The order which you do the above steps determines which of the three scenarios the server is involved in. If you become a server first, then you are creating a new domain. If you become a client of an existing domain, and THEN become a server, then you are a secondary server. If you become a client and then a server, you are becoming a replica domain server.

Even though it may be considered backwards we will go over the client procedure first.

Client Configuration

The client procedure should be available both as a GUI program, a curses program and a command line program. The GUI program would be listed in whatever desktop menu is used for system configuration. It will require root access. The Curses program is used to do configuration immediatly after install, or for a server which does not have a graphical GUI. The command line option is for automation.

The first thing the client configuration program should do is verify the state of the local system and weither additional programs are required. Required are: kerberos libraries, kerberos administration libraries, ldap client libraries, NSS support for LDAP and PAM support for Kerberos 5.

The program should then attempt to probe the local system and various network properties to discover potential configuration information. Attempt to use the local DNS, assigned by DHCP or manually, to locate the SRV records for both Kerberos 5 and LDAP. None of this information should be hard coded into the local information EXCEPT the Kerberos Realm name. If the local DNS server is not set up correctly, prompt for the information to be hard coded. Make sure to describe the process to the user. He needs to know that he looses flexibility by hard coding this information on the clients. The configuration information should ideally be stored ONLY in the specific configuration files for the specific services in question: /etc/krb5.conf, /etc/ldap/ldap.conf.

The user should now be prompted for a Kerberos principal and password to authenticate with the KDC by. After entering this information it should be used to attempt to create a new host principal for the local machine or locate an existing one. The name of the principal should follow the Kerberos standards of "host/${fqdn}@${REALM}". Allow the user to override this step and specify a pre-existing host principal name. Allowing the user to specify a custom host principal makes joining Active Directory and other pre-configured Kerberos setups possible. The password for the new principal is set randomlly. The principal is then added to the local keytab. A startup script is created that changes the password of the Kerberos principal at bootup.

After the Kerberos configuration is complete the system needs to attempt to configure the required LDAP options. The wizard connects to the LDAP server specified by the configuration step and attempts to locate an existing host object. Authentication to the server is done using GSSAPI over SASL, using the keytab just created in the previous step. Location of an existing object can be done in a variety of ways: searching by the Kerberos principal or host name. If the object is not found it can either be created or the user can be prompted to locate it. Permission to modify the LDAP object is checked. It is required that the local system be able to modify it's own LDAP object. The LDAP object's information is populated or refreshed. This includes the obvious information such as the host name. The DN of the system's LDAP object should be stored locally. Information about the LDAP directory layout is now retrieved. This includes discovering what prefix User, Groups and Computers are stored/created in. This information should be stored locally in both /etc/libnss-ldap.conf and /etc/pam_ldap.conf or a centralized file linked to these two locations (in the Debian case). It is worth noting the both NSS and PAM can share the same configuration file, ignoring each other's entries. (Note: There's a bug ( open for this -Andrew)

The last step in the process is to alter the NSS and PAM configuration to refer to the remote system for authentication information. This is done by adding "ldap" to the /etc/nsswitch.conf file and the pam_krb5 module information to /etc/pam.d/common-*.

At this point the client has been successfully joined to the domain.

Client Software

I (Michiel Eghuizen) have made a script that can make from your workstation a domain members. It works on Ubuntu Breezy/Dapper and Edgy. I needed this functionality, because of the project we've been doing. For the dutch people, they can find some background information on this site: Linux clients binnen domein.

It uses the following client software:

  • Samba
  • pam_mount
  • Libnss
  • Winbind
  • PAM

It communicates with Samba and not with LDAP. It can also connect with Active Directory (not tested). It needs a shitload of fixes, but it's a begin. I hope someone has the time and knowledge to correct this script.

Here you can find a link to the script: PDC-Client-0.9 *updated*

A problem I found in the script but not yet solved is, the script doesn't copy nsswitch.conf, so you need to do that one by hand.

Server Configuration

As discussed above there are two aspects to server configuration which share a lot of proceedures.

The server configuration only NEEDS to be available as a Curses tool. Of course, having a graphically managed server is an idea other operating systems have done. It's not important currently.

The first step of the server configuration is to make sure the neccassary services are installed: Kerberos 5, OpenLDAP and optionally Bind.

At this point the configuration deviates a little bit depending on weither the system is joined to a domain or not. First, lets consider the situation where we aren't joined to an existing domain.

If we are not a member of an existing domain the user needs to enter some information. He can select an advanced mode or a simple mode. The simple mode he is asked for one peice of information: a DNS domain name. The DNS domain name is "transformed" into a Kerberos Realm (capitilized) and a LDAP DN: components seperated. The user can also choose advanced and enter both peices of information on his own. The default domain name used in simple mode is the DNS name the host currently has.

If we are a member, most of this information is already known.

The user is asked to provide the administrator password. The language differs a bit if we are already in a domain.

Configuration is done. The utility begins to do the actual set up work.

If we are creating a new domain a new Kerberos database is created. The proper default principals are created using the password provided. OpenLDAP is configured with a new database. The hierarchy is imported from a default LDIF template. The configuration is edited to import the proper schemas and use the proper ACLs. If the user said he wants to set up a new DNS server Bind is configured. A new zone is created with the proper domain name. The proper SRV records are inserted into it. All the services are restarted.

Otherwise, if we are becoming a replica, the services are configured appropriatly. I'm leaving this part undefined as we have no way to actually configure a remote server other than telling the user to.

At this point, we have a domain that we can now join. The client join code should be now run prepopulated with the neccassary information. The system should be joined to itself.

From NiallSheridan Wed Feb 9 13:46:47 +0000 2005 From: Niall Sheridan Date: Wed, 09 Feb 2005 13:46:47 +0000 Subject: Authconfig Message-ID: <>

Redhat's authconfig application does the client configuration (i.e. modifying the pam.d/* files to auth properly. It's something I've always missed in Debian (and now Ubuntu)

From GheRivero Sun Mar 6 23:37:11 +0000 2005 From: Ghe Rivero Date: Sun, 06 Mar 2005 23:37:11 +0000 Subject: Kerberos Integration System Message-ID: <>

KIS project at

From GheRivero Sun Apr 17 10:23:02 +0100 2005 From: Ghe Rivero Date: Sun, 17 Apr 2005 10:23:02 +0100 Subject: AuthConfig Message-ID: <20050417102302+0100@>

Authconfig, within some other useful utilities (like libuser) are on the way. Most parts are working at this moment but there are some small issues already.

From ThomasMathiesen Mon May 9 12:38:29 +0100 2005 From: Thomas Mathiesen Date: Mon, 09 May 2005 12:38:29 +0100 Subject: Linux Enterprise Directory Message-ID: <20050509123829+0100@>

I've setup a new project to build a directory server and scripts to add clients in a so-called Linux Enterprise Directory. I'll be using openldap on CentOS 4 and Ubuntu 5.04 (clients). See if you would like to help.

See the authtool utility that shipped with Feisty: FeistyNetworkAuthentication. -NealMcBurnett

DomainAuthenticationUtility (last edited 2008-08-06 16:38:34 by localhost)