Feature #164
Updated by Daniel Curtis over 10 years ago
LDAP and Kerberos together make for a great combination. Kerberos is used to manage credentials securely (authentication) while LDAP is used for holding authoritative information about the accounts, such as what they're allowed to access (authorization), the user's full name and uid. You can also add in helpful things such as an external email address or a room number in a structured way. Most other LDAP setups involve in storing passwords in the LDAP directory itself using the userPassword attribute. While this is ok for a basic setup, one can do much better with just a little effort. h2. Overview This guide is intended as a Debian-focused update to excellent guides, such as http://aput.net/~jheiss/krbldap/howto.html . Many of the workarounds have been fixed in recent releases of Debian, however there are still a few places one can easily get snagged. The goal of this document is to create a Single Sign-On (SSO) system without using NIS or passwords stored in LDAP. This includes a client setup which can successfully use Kerberos for authentication and LDAP for authorization. With LDAP comes many solutions to very similar problems. Many people use LDAP due to an existing Active Directory setup, so certain tools need to be used to deal with its quirks. As this guide starts from scratch, it can be done as simply as possible. By far the simplest way to integrate Kerberos + LDAP together on one system is to use PAM (authentication) and NSS (authorization). This document was originally written based on experience with Debian/etch and Debian/lenny. Please update accordingly. As of posting this, this method still works even into Debian/wheezy. h2. Kerberos server There are plenty of guides for setting up a Kerberos server on Debian. You can refer to Feature #163 for assistance with this. Once you have a KDC set up with a test principal, come back to this document. h2. LDAP Server See Feature #162 to get your server set up. h3. Getting your feet wet with LDAP A very helpful tool for getting one's feet wet with LDAP is @phpldapadmin@. While it's certainly no replacement for a proper account management system, it lets you create accounts and tinker with attributes while conforming to the schemas. h3. LDAP data structure Starting an LDAP server from scratch can be a bit daunting, as it starts out as a blank, unstructured slate. One tool to help get started is the migrationtools package. If one is familiar with @/etc/passwd@ and @/etc/group@, one can see how that then translates to the world of LDAP using @/usr/share/migrationtools/migrate_passwd.pl@ and friends. See LDAP/MigrationTools for more information. These tools create *posixGroup* and *posixAccount* objects which the NSS module below is familiar with. The common hierarchical structure of *ou=Users,dc=example,dc=com* and *ou=Groups,dc=example,dc=com* seems to work quite well for most software out-of-the-box. h2. Kerberos client Install the following packages: <pre> krb5-config krb5-clients krb5-user </pre> The Kerberos client setup is pretty straightforward using the krb5-config package's config. If you're having trouble, check the following: * ensure krb5.conf is set properly. Things to check for: * ensure your domain is mapped in the domain_realm section at the bottom; this is used by the GSSAPI LDAP integration and will cause weird problems if you happen to be in a subdomain of any of the defaults. * ensure your default_realm is proper * ensure your realm is defined in the realms section You can test that Kerberos is set up properly by doing: <pre> kinit -p USERNAME klist </pre> If everything's working fine, you should see a ticket when you klist. h2. Client Login Setup To set up a machine for logins using this style of LDAP+Kerberos, you need to set up PAM and NSS. PAM Instead of using LDAP PAM as described in LDAP/PAM, set up PAM to authenticate using Kerberos. Install libpam-krb5 and then proceed to @/usr/share/doc/libpam-krb5/README.Debian.gz@ which has great directions to get going. If your Kerberos environment was properly set up above, then you should have logins working nicely. > When you initially install either package, you will have the option to > choose to automatically configure your PAM configuration to include it. > If you do so, a standard set of PAM options will be used that will work > for most users. If those options do not work for you or if you can't use > automatic PAM configuration for some reason (such as another PAM module > that doesn't support it), see below. > > For a system where user account authentication should be handled primarily > through Kerberos and password changes should be made against Kerberos, > with fallback to local authentication, the following basic configuration > should work. In /etc/pam.d/common-auth, put: > > auth sufficient pam_krb5.so minimum_uid=1000 > auth required pam_unix.so try_first_pass nullok_secure > > In /etc/pam.d/common-session: > > session optional pam_krb5.so minimum_uid=1000 > session required pam_unix.so > > In /etc/pam.d/common-account: > > account required pam_krb5.so minimum_uid=1000 > account required pam_unix.so > > (Note that the account function of pam_krb5.so will return ignore if the > user didn't log in via Kerberos, so this is will still allow access via a > local password. It will ensure that, if the user did log in via Kerberos, > their Kerberos authentication is checked against ~/.k5login if present.) > > Finally, in /etc/pam.d/common-password: > > password sufficient pam_krb5.so minimum_uid=1000 > password required pam_unix.so nullok obscure sha512 > > Note the minimum_uid=1000 on all of these lines. This is optional, but > normally sites do not create a single root@example.com Kerberos principal > and use it for authentication to root accounts, and normally you don't > want to allow Kerberos authentication to system accounts. Also, trying to > do Kerberos authentication when the network is down may cause delays or > timeouts, and this way such authentication is never attempted for a root > login. On Debian systems, regular user accounts normally start at UID > 1000; you may need to change this for local policy. > > This configuration will still require that users be listed in /etc/shadow, > since otherwise the pam_unix account module will fail. Normally, accounts > that should only use Kerberos authentication should be created with > adduser --disabled-password. If you don't want the accounts to be listed > in /etc/shadow at all (if, for example, you're using some other source > than files for your nsswitch configuration), you can mark the pam_krb5 > account module as sufficient rather than required so that pam_unix isn't > run. This will mean that you won't be able to disable accounts locally. > > If you have local passwords for Kerberos users and want to synchronize the > local and Kerberos password on password change, instead use an > /etc/pam.d/common-password configuration of: > > password requisite pam_krb5.so minimum_uid=1000 > password required pam_unix.so try_first_pass use_authtok obscure sha512 > > If you regularly use ticket forwarding (such as with Kerberos rlogin or > ssh with GSSAPI support), you may wish to add the "forwardable" option to > the pam_krb5.so line in /etc/pam.d/common-auth or equivalently set > forwardable in /etc/krb5.conf (in either [libdefaults] for all Kerberos > applications or in a pam group in [appdefaults] just for the PAM module). > > The above configurations assume that one can generate a person's Kerberos > credential by appending the default realm to the local username. If this > is not the case for your system, make sure that every account for which > this is not the case has a .k5login file in their home directory listing > the Kerberos principals that should have access (or which is empty if none > should). Otherwise, someone will be able to access that account if they > know the password of the Kerberos principal in the default realm with the > same name. In this situation, you will probably also want to add the > "search_k5login" option to the pam_krb5.so line in /etc/pam.d/common-auth; > see the pam_krb5(5) man page for more information. h3. Creating home directory on login Include this in @/etc/pam.d/common-session@ if you want to automatically create home directories when users first login: <pre> sudo vi /etc/pam.d/common-session </pre> > ... > session required pam_mkhomedir.so skel=/etc/skel umask=0022 > ... h2. NSS See LDAP/NSS to get started. There is nothing special you need to do beyond ensure that you properly configure @/etc/libnss-ldap.conf@. @libnss-ldap@ seems to work well for simple setups. This page describes the steps needed to get user names, groups and other information that is usually stored in flat files in /etc or NIS from an LDAP server. This information is exposed through NSS (Name Services Switch) as configured in /etc/nsswitch.conf. The following databases can be served from LDAP: *aliases* aliases (mail aliases, ignored by most mail daemons) *ethers* daemons), ethers (ethernet numbers) *group* numbers), group (groups of users) *hosts* users), hosts (host names and numbers) *netgroup* numbers), netgroup (host and user groups used for access controls) *networks* controls), networks (network names and numbers) *passwd* (users) *protocols* numbers), passwd (users), protocols (network protocols) *rpc* protocols), rpc (remote procedure call names and numbers) *services* numbers), services (network service names and numbers) *shadow* and shadow (shadow user passwords) passwords). There are currently two packages available to configure NSS lookups through LDAP: the @libnss-ldap@ libnss-ldap package and the @libnss-ldapd@ libnss-ldapd package. Which one to choose depends on the needs. In general @libnss-ldapd@ libnss-ldapd is simpler but newer and @libnss-ldap@ libnss-ldap is more mature but more complex. Also @libnss-ldap@ libnss-ldap has some known issues with serving host information and lookups during boot which should be addressed in @libnss-ldapd@. libnss-ldapd. In addition, @libnss-ldap@ libnss-ldap breaks setuid programs (su, sudo) when using LDAP+SSL (see http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=579647 ). h3. On running nscd For debugging it is recommended to not to run nscd (the Name Service Caching Daemon) because nscd can mask problems by serving entries from it's cache. Either don't install the nscd package until it is clear that everything is functional or stop nscd with <pre> /etc/init.d/nscd stop </pre> However, running nscd is required when using @libnss-ldap@ and permissions of @/etc/libnss-ldap.conf@ do not allow normal users to read the file (e.g. when using the bindpw option). Certain versions of @libnss-ldap@ have been known to set restrictive permissions on this file. Note that not all NSS lookups will go through nscd (only passwd, group and host) so this may not work in all circumstances. For production use it is recommended to run nscd as it saves on doing lookups to the LDAP server. You may consider tuning the time-to-live values of the cache in @/etc/nscd.conf@ if you need to pick up changes in the LDAP directory quickly (through the defaults are fine in most circumstances). h2. NSS Setup with @libnss-ldap@ Install the package: <pre> apt-get install libnss-ldap </pre> Be sure to read the docs that are installed in @/usr/share/doc/libnss-ldap/@ If you plan to do hostname lookups through LDAP you should add the hostname of your LDAP server in @/etc/hosts@ (even if you use an IP address to configure the connection to the server). Without this nasty things happen on bootup as things attempt to use LDAP which recurses on itself looking up the hostname. Edit @/etc/libnss-ldap.conf@ to include al least the following (replace the values with options that are specific to your environment): > # Your LDAP server. Must be resolvable without using LDAP. > uri ldap://10.0.0.1 > # The distinguished name of the search base. > base dc=<your>,dc=<domain> If you specified @rootbinddn@ you need to put the LDAP admin password in @/etc/ldap.secret@ with mode 600. Edit /etc/nsswitch.conf to use add LDAP to the services you want to have enabled (be careful to put LDAP *after* "files"): > passwd: files ldap > group: files ldap > shadow: files ldap > > hosts: files dns ldap > networks: files ldap > > protocols: db files > services: db files > ethers: db files > rpc: db files > > netgroup: nis h2. NSS Setup with @libnss-ldapd@ An alternative is to use libnss-ldapd. This software has been developed to fix some of the shortcomings of libnss-ldap, see the nss-ldapd homepage for more details. Install the package with: # apt-get install libnss-ldapd Most of the configuration for common setups is performed during installation. The following questions are generally asked: the URI of the LDAP server - you should specify ldap://10.0.0.1 or whatever the IP address of your LDAP server is (it's better to avoid host names because of potential problems with DNS or other NSS modules) the base DN of your LDAP database (optional) name and credentials to use to bind to the LDAP database for which services to enable libnss-ldapd (you should probably select passwd, shadow and group and maybe others if you need them) libnss-ldapd provides reasonable defaults for most values (looking at environment and possibly existing configurations). This should be enough to enable NSS lookups through LDAP in most common cases. If you have a more unusual setup or require more configuration (e.g. SSL/TLS certificates, SASL/Kerberos configuration, etc) see the @nss-ldapd.conf@ manual page and documentation in @/usr/share/doc/libnss-ldapd@. @nslcd@ should be restarted if any changes are made to @/etc/nss-ldapd.conf@. h3. Verify that NSS is operational Check that NSS is seeing things from LDAP using getent: <pre> getent passwd </pre> should show you accounts from LDAP that are not in the @/etc/passwd@ file. Similar tests can be done with the group, shadow and other in @/etc/nsswitch.conf@ configured databases. Be sure to also run some tests as non-root users. Also try rebooting to see if NSS lookups are performed correctly during boot. Note that @getent@ shadow should only return data for root users. Also, passwords are generally not returned unless the LDAP server has been configured to return this data and are in a supported format. If pam_ldap is used (see LDAP/PAM) it is not needed to expose passwords from the LDAP server. When using the @libnss-ldapd@ package debugging can be done by starting @nslcd@ (the connection daemon) in debugging mode (remember to stop nscd when debugging): <pre> /etc/init.d/nscd stop /etc/init.d/nslcd stop nslcd -d </pre> Further debugging can be done with the ldapsearch utility from the ldap-utils package. You can search for all the information that is available for a single user: <pre> ldapsearch -h <ldapserver> -b dc=<your>,dc=<domain> -x uid=<username> </pre> Specify the @-D@ and @-W@ options to log in if the @binddn@ or @rootbinddn@ options are used. h2. Offline caching of NSS with nscd While contineous LDAP connectivity can be assumed for workstations and servers in a LAN, laptop users often do not have network connectivity. From a system administrators point of view it is tempting to create local users on the laptop but this causes trouble when these laptops have to access domain resources like network shares (NFS, sshfs, Samba, etc.) back in the office (with a stable network connection). Many of these network shares rely on a central name service database like LDAP because of user and group information and permissions on the share. NSCD is often used to cache NSS information, so that the LDAP server does not have to be queried for every request (which has also an impact on the speed of the answer). NSCD can also be used to serve these requests while there is no network connectivity. In short: NSCD is configured to cache the information much longer than the default values from Debian (Lenny) Recipe: NSCD has a configuration file @/etc/nscd.conf@ There are two configuration options which have to be altered in order to use the pseudo-offline capability: > reload-count unlimited > positive-time-to-live <service> #number of second The positive-time-to-live has to be configured for at least the passwd and group service. To cache user and group information for 30 days, you would use: > positive-time-to-live passwd 2592000 > positive-time-to-live group 2592000 h3. Caveats: When configured for offline mode, NSCS's NSS information is not updated for a long period of time. This can be troublesome depending on the time-to-live setting, because changes in the LDAP database are not known to the system because it uses the cached information. For now, I have only one workaround with which I am not too happy: manually cleaning the cache when online again with: <pre> nscd -i passwd nscd -i group </pre> I guess this could be automated in some way (when the LDAP server is reachable again) but I am not sure if this is the right way. *NOTE*:If you're having trouble authenticating when everything else seems fine, try doing @/etc/init.d/nscd restart@ or stopping the daemon entirely. It can get in the way when first setting up LDAP.