Differences between revisions 13 and 26 (spanning 13 versions)
Revision 13 as of 2009-02-24 19:02:42
Size: 5631
Editor: StevePomeroy
Comment:
Revision 26 as of 2011-06-14 20:48:52
Size: 6633
Editor: StevePomeroy
Comment:
Deletions are marked like this. Additions are marked like this.
Line 3: Line 3:
[[TableOfContents(2)]] <<TableOfContents(2)>>
Line 5: Line 5:
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 external email address. 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. 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.
Line 9: Line 11:
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. 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.
Line 13: Line 15:
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 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). 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).
Line 21: Line 23:
= LDAP Server =

See [[LDAP/OpenLDAPSetup]] to get your server set up.

== 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.

== 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.
Line 26: Line 42:
The Kerberos client setup is pretty straightforward using the `krb5-config` package's config. For `libpam-krb5`, you will have to modify your `/etc/pam.d/common-*` files according to `/usr/share/doc/libpam-krb5/README.Debian`. The Kerberos client setup is pretty straightforward using the `krb5-config` package's config.
Line 34: Line 50:
= LDAP Server = You can test that Kerberos is set up properly by doing:
{{{
kinit -p USERNAME
klist
}}}
Line 36: Line 56:
See ["LDAP/OpenLDAPSetup"] to get your server set up. If everything's working fine, you should see a ticket when you `klist`.
Line 38: Line 58:
== Getting your feet wet with LDAP == = Client Login Setup =
Line 40: Line 60:
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. To set up a machine for logins using this style of LDAP+Kerberos, you need to set up PAM and NSS.
Line 42: Line 62:
== LDAP data structure == == PAM ==
Line 44: Line 64:
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. 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.
Line 46: Line 66:
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. Read over [[LDAP/PAM]]. While LDAP isn't used for authentication, there are some handy tricks listed there for setting up login access restriction.
Line 48: Line 68:
= PAM = == NSS ==
Line 50: Line 70:
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` which has great directions to get going. If your Kerberos environment was properly set up above, then you should have logins working nicely. See [[LDAP/NSS]] to get started. There is nothing special you need to do beyond ensure that you properly configure `/etc/libnss-ldap.conf`.
Line 52: Line 72:
Read over ["LDAP/PAM"]. While LDAP isn't used for authentication, there are some handy tricks listed there for setting up login access restriction. `libnss-ldap` seems to work well for simple setups.
Line 54: Line 74:
= NSS = 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.
Line 56: Line 76:
See ["LDAP/NSS"] to get started. There is nothing special you need to do beyond ensure that you properly configure `/etc/libnss-ldap.conf`. Once NSS is set up, restart SSH:
{{{
/etc/init.d/ssh restart
}}}
Line 66: Line 89:
 * Set up SSL. You never want to do Basic authentication across the wild 'net without some SSL protecting it. [http://www.debian-administration.org/articles/349 d-a.org article]  * Set up SSL. You never want to do Basic authentication across the wild 'net without some SSL protecting it. [[http://www.debian-administration.org/articles/349|d-a.org article]]
Line 71: Line 94:
    # the below line is due to
    # "Bad file descriptor: Could not open password file: (null)"
    # causing auth. to fail.
    AuthBasicAuthoritative off

    # turn on PAM auth.
Line 74: Line 103:
    AuthGROUP_Enabled on
    require valid-user

    ## Restricting to a specific user
    # AuthGROUP_Enabled off
    # require user fred

    ## Restricting based on groups
    ## make sure to turn off the below line if you don't use "require group"
    # AuthGROUP_Enabled on
    # require group coolkids

LDAP + Kerberos

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.

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. A number of common clients are shown, such as a standard shell login and Apache2 integration.

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.

Kerberos server

There are plenty of guides for setting up a Kerberos server on Debian. Once you have a KDC set up with a test principal, come back to this document.

LDAP Server

See LDAP/OpenLDAPSetup to get your server set up.

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.

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.

Kerberos client

Install the following packages:

  • krb5-config krb5-clients krb5-user

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:

kinit -p USERNAME
klist

If everything's working fine, you should see a ticket when you klist.

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.

Read over LDAP/PAM. While LDAP isn't used for authentication, there are some handy tricks listed there for setting up login access restriction.

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.

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.

Once NSS is set up, restart SSH:

/etc/init.d/ssh restart

Apache2

Basic authentication over SSL

Basic + SSL is a quick way to set up restricted access to websites. It's not the best, usability wise (this is usually the fault of most browsers for not exposing identity management at all), but it works well enough for most internal-use cases.

  • Set up PAM. Ensure that you can login to the server using LDAP + Kerberos credentials
  • install libapache2-mod-auth-pam libapache2-mod-auth-sys-group and then a2enmod auth_pam auth_sys_group

  • Set up SSL. You never want to do Basic authentication across the wild 'net without some SSL protecting it. d-a.org article

  • In your virtual host for your given site, you can restrict a path as follows:

<Location /restrictedpath>
    # the below line is due to
    # "Bad file descriptor: Could not open password file: (null)"
    # causing auth. to fail.
    AuthBasicAuthoritative off

    # turn on PAM auth.
    AuthPAM_Enabled on
    AuthType basic
    AuthName "Example.com Restricted Login"

    ## Restricting to a specific user
    # AuthGROUP_Enabled off
    # require user fred

    ## Restricting based on groups
    ## make sure to turn off the below line if you don't use "require group"
    # AuthGROUP_Enabled on
    # require group coolkids
</Location>

Other options are to use libapache2-mod-auth-kerb or libapache2-mod-authn-sasl, but neither of those provide group information from LDAP. It might be possible to pull that in using the authnz_ldap that comes with Apache2, but that module seems quite intent on performing the authentication phase, which is in our case is supposed to be handled by Kerberos, not LDAP.