Linux Active Directory How-To

For Mandriva Linux, GPL, 2006
Herman Oosthuysen, Aerospace Software Ltd.

1. Scope

This document briefly describes how to configure a GNU/Linux machine to authenticate users against a Microsoft Server 2003 Active Directory Server.

The idea is to use the Windows 2003 ADS to authenticate a foreign user and allow him to use a Linux machine which is a member of the Windows domain, without having to create him a user account manually on the Linux machine. This is very useful when you have large numbers of machines and users.

If everything works as it should, then you only need to configure the users on the Active Directory machine. The users can then walk up to any machine on the network and log on. If a user never used that machine before, a user account will be magically created. This magical trick is known as Single Sign-On (SSO).

This whole process is rather complicated and relies on a number of subsystems working together:

Pluggable Authentication Modules (PAM)
Server Message Block (SMB, Samba)
WinBIND (part of Samba)
Kerberos 5 (By MIT, with Microsoft compatibility hacks)

Note that most documentation on the web, is written for Samba authentication to a NT4 domain. There is precious little information on authenticating to an ADS domain. Therefore, most of the available documentation is either wrong or misleading. Also, since Microsoft is very secretive about everything, you won't find any useful information on their web site either the most useful information is on the Samba project web site at http://www.samba.org, but even that needs to be read carefully, since it mostly concerns NT4.

The biggest problem is configuring Samba and determining exactly what identifiers and spelling to use where, since Kerberos and NETBIOS are fond of upper case, while everything else prefers lower case. Of course, nothing works, until every last little detail is correct, so these and other subtleties can lead to many hours of happy debugging and experimentation before it will suddenly begin to work.

Just about every imaginable error message was discovered the hard way and they were all documented below. Of course, since you will be following this great guide, you won't ever see them - let's hope anyway.

Note that everything here was tested on Linux, but it should also apply almost directly to Solaris, since Samba is cross platform.

Note to Redhat RHEL 5 users: Upgrade Samba to version 3.0.26a or later. The 3.0.23c version shipped with RHEL5 is bad news with ADS. You can take the Fedora RPMs from the Samba FTP server and rebuild the SRC RPM, then it will work - no changes required, just rebuild it on RHEL5.

2. Referenced Documents

Chapter 6. Domain Membership Part II. Server Configuration Basics, http://us4.samba.org/samba/docs/man/Samba-HOWTO-Collection/domain-member.html#ads-member
Chapter 24. Winbind: Use of Domain Accounts Part III. Advanced Configuration, http://us4.samba.org/samba/docs/man/Samba-HOWTO-Collection/winbind.html
Kerberos Administration Guide, http://web.mit.edu/kerberos/krb5-1.3/krb5-1.3/doc/krb5-admin.html
Linux PAM, http://www.kernel.org/pub/linux/libs/pam/

3. Configuration

We want to use the Windows 2003 Active Directory Server (ADS) to authenticate a foreign user and allow him to use a Linux machine which is a member of the Windows domain. Initially, the user jdoe doesn't exist on the Linux machine. We want to use Winbind and Samba to assign a UID and GID from a pool of reserved numbers and create a home directory automatically under /home/winnt for this foreign user. This will (hopefully) allow jdoe to walk up to the Linux machine, log in and use it to run X applications, without ever having been configured on it.

This guide assumes that you already have a Windows ADS running. First verify a few things on the Windows 2003 ADS machine and note that the NETBIOS Workgroup must be UPPERCASE:

NETBIOS Workgroup: MSWRKGRP
Domain name: example.com
Fully qualified hostname: msads.example.com
User name defined in ADS: jdoe
User password: jdoe123
User primary group: winusergrp
Administrator name: Administrator
Administrator password: SuperSecret

This illustrates some weird points. A Windows XP machine can seemingly establish a machine account without having the Administrator name and password, but for a Linux machine as client, you need to have that, else you cannot join the domain. Goodness knows why that is so, but it looks like a huge security hole in Windows.

Rather confusingly, the MS Windows NETBIOS workgroup, is also referred to as the domain name, or short domain name in MS Windows documentation. The NETBIOS workgroup is actually used more often than the real domain name, so when in doubt, use the NETBIOS workgroup, since it will usually be the correct one for the occasion.

The MS Windows username, will become workgroup+username (eg. MSWRKGRP+jdoe) on Linux and the Windows primary group, will become workgroup+groupname (eg. MSWRKGRP+winusergrp) on Linux.

3.1 Kerberos

Kerberos is configured in the file /etc/krb5.conf. Verify the following lines and note the UPPERCASE domain name:

[libdefaults]

 default_realm = EXAMPLE.COM

[realms]

 EXAMPLE.COM = {

  kdc = msads.example.com

[domain_realms]

 .kerberos.server = EXAMPLE.COM

Note that Kerberos requires that the clocks of the machines in the domain are synchronized in time. The default maximum skew allowed is 5 minutes. Windows and Linux handles time differently. UNIX is UTC based and Windows is local time zone based, so be careful.

3.2 Nsswitch Configuration

Verify the following lines in /etc/nsswitch.conf:

passwd:        files    winbind

shadow:        files    winbind

group:        files    winbind

You may need to run ldconfig to set up the winbind libraries:

# ldconfig -v | grep winbind

Since nothing was working at the time, I cannot tell whether that was really a required step.

3.3 Samba Configuration

Here's the [global] section from smb.conf:

[global]

workgroup = MSWRKGRP

realm = EXAMPLE.COM

preferred master = no

server string = Samba Server

security = ADS

encrypt passwords = yes

log level = 3

log file = /var/log/samba/%m

max log size = 50

winbind separator = +

winbind use default domain = yes

printcap name = cups

printing = cups

idmap uid = 10000-20000

idmap gid = 10000-20000

winbind enum users = yes

winbind enum groups = yes

template homedir = /home/winnt/%D/%U

template shell = /bin/false

add machine script = /usr/sbin/useradd -d /var/lib/nobody -g 100 -s /bin/false -M %u

password server = msads.example.com

The /bin/false shell will prevent foreign domain users from opening a command shell and is recommended for security.

The default Winbind separator is a backslash, but that doesn't work well, since it is a reserved character. The general rule is to change it to a '+'.

3.4 Ethernet Configuration

You have to set the ADS machine as (one of) the DNS in /etc/resolv.conf, to enable the Linux machine to find the Kerberos and LDAP servers on the ADS. Verify the ethernet and DNS settings with ifconfig and nslookup.

3.5 Join the Domain

First restart the network and Samba:

# service network restart

# service smb restart

Verify that smbd and nmbd is running with

# ps e

Try to join the Windows domain:

# net ads join -S msads.example.com -U Administrator%SuperSecret

or use the short form (Samba will broadcast, search and join):

# net ads join -U Administrator%SuperSecret

You should get the message: "Joined LINUX1 to realm EXAMPLE.COM", at which point most joyfull celebrations are in order.

Now you can start the Winbind daemon with the maximum debug information:

# winbindd -d 10

Watch /var/log/messages for errors:

# tail -f /var/log/messages

You can investigate the domain records with:

# wbinfo -u

# whinfo -g

# getent password

# getent group

With those utilities, you should be able to see the user names and groups in the domain that you just joined. User MSWRKGRP+jdoe and the group MSWRKGRP+winusergrp should be listed.

3.6 Kerberos Error Messages

If you get the message: Cannot find KDC for requested realm, then either the password server in smb.conf is wrong, or the DNS setting in resolv.conf is wrong.

If you get the message: KRB5 error code 68 while getting initial credentials, then the Linux machine can talk to the ADS machine, but your Kerberos realm name in smb.conf is wrong.

If you get the message: The workgroup in smb.conf does not match the short domain name obtained from the server, then you did not specify the NETBIOS name properly in the workgroup setting in smb.conf. Verify it on the ADS machine in the Control Panel, System, General dialogue.

Note that the workgroup and realm must be defined in upper case.

If you get the message: Failed: Clock skew too great, then adjust the time to be the same as on the ADS machine. They should be within five minutes of each other and do verify the time zones as well. It appears that Kerberos cannot authenticate to a server in a different time zone.

The domain join operation verifies the machine trust account with the Kerberos server, so at this point we know that Kerberos is essentially working, but we still haven't authenticated an actual user.

You can run a manual Kerberos user test:

# kinit jdoe@EXAMPLE.COM

If you get no response, then it is working and even more joyous celebrations are in order.

3.7 PAM Configuration

Whenever a new user logs in, we need to create a home directory on the fly, if it doesn't exist already. This is done with the module pam_mkhomedir. The configuration files for PAM, is in /etc/pam.d. Look for the files /etc/pam.d/gdm and /etc/pam.d/samba.

Modify them as follows, with the addition of two lines (each should be the first in its group):

auth    sufficient     pam_winbind.so

session    required    pam_mkhomedir.so    skel=/etc/skel     umask=0022

This will allow a user to log in either from another machine into Samba, or on the Linux machine itself using a Graphical Display Manager. If you need a user to log in using SSH, then you would have to modify the /etc/pam.d/sshd file as well (and you'll have to set the template shell to /bin/bash in /etc/samba/smb.conf).

Create the base directory and primary group for winnt logins:

# mkdir -p /home/winnt/MSWRKGRP

# mkgroup MSWRKGRP+winusergrp

# chown root:MSWRKGRP+winusergrp /home/winnt/MSWRKGRP

3.8 Winbind Errors

You can see the Winbind error messages with:

# tail -f /var/log/messages

If you get the message: idmap Fatal Error: UID range full!, then the idmap cache is confused and needs to be deleted. Since we painfully discovered all the previous configuration errors, it was inevitable that we would get this one too.

First stop Samba and Winbind with:

# service smb stop

# service winbind stop

Then delete the following files:

/etc/samba/secrets.tdb

/etc/samba/smbpasswd

/var/cache/samba/winbindd_idmap.tdb

Now rejoin the domain with:

# net ads join -U Administrator%SuperSecret

Restart Winbind and Samba:

# service winbind start

# service smb start

and if you now do

# wbinfo -u

# wbinfo -g

# getent password

# getent group

The user jdoe and group winusergrp should be visible in the domain MSWRKGRP.

3.9 Single Sign-On Login

The holy grail of MS Windows ADS Single Sign-On is finally within reach. Click Start, Switch User, Start New Session and log in as user MSWRKGRP+jdoe with password jdoe123 and the system should pop up a little window indicating that a new home directory is being created for this user and after a little while, you should be presented with a graphical desktop.

Open a console and look at the present working directory. It should be /home/winnt/MSWRKGRP/jdoe. If you touch a new file, then it should be created with the username MSWRKGRP+jdoe and group MSWRKGRP+winusergrp.

3.10 Debugging with smbclient

The smbclient program is useful for additional tests, since it shows the regular Windows NT error messages. When all else fails, try some smbclient commands and see what the system tells you.

This command should list all shares:

# smbclient -k -L //localhost -N

This command should log into the jdoe share /home/winnt/MSWRKGRP/jdoe:

# smbclient -k //localhost/jdoe -U MSWRKGRP+jdoe%jdoe123

Hopefully, that will get you going.

4.0 NOTES

Subsequent experience showed a few more very serious issues. Active Directory is an LDAP server and the Linux LDAP client is influenced by the /etc/ldap.conf file. If you leave it at the default settings, then LDAP queries can cause a severe system slowdown and can cause winbindd to crash. The following two settings will prevent this and will speed the system up enormously:

File /etc/ldap.conf:
referrals no
bind policy soft

Active Directory causes an enormous amount of network traffic. You can speed things up significantly by adding the address of the server to /etc/hosts, since that will eliminate the DNS lookups.

The /etc/samba/smb.conf file is checked by smbd and nmbd at regular intervals. Optimize the file by keeping the commented settings in smb.conf.master and generating a short version using testparm:

# testparm -s smb.conf.master > smb.conf

If you don't use a smartcard for authentication and see references to winscard whenever you log in, remove the 'coolkey' package.

Have fun!
Herman