From owner-freebsd-doc@FreeBSD.ORG Fri Nov 17 04:00:04 2006 Return-Path: X-Original-To: freebsd-doc@hub.freebsd.org Delivered-To: freebsd-doc@hub.freebsd.org Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 07AF016A47B for ; Fri, 17 Nov 2006 04:00:04 +0000 (UTC) (envelope-from gnats@FreeBSD.org) Received: from freefall.freebsd.org (freefall.freebsd.org [216.136.204.21]) by mx1.FreeBSD.org (Postfix) with ESMTP id 73D4A43D49 for ; Fri, 17 Nov 2006 04:00:03 +0000 (GMT) (envelope-from gnats@FreeBSD.org) Received: from freefall.freebsd.org (gnats@localhost [127.0.0.1]) by freefall.freebsd.org (8.13.4/8.13.4) with ESMTP id kAH403W1027185 for ; Fri, 17 Nov 2006 04:00:03 GMT (envelope-from gnats@freefall.freebsd.org) Received: (from gnats@localhost) by freefall.freebsd.org (8.13.4/8.13.4/Submit) id kAH4039r027179; Fri, 17 Nov 2006 04:00:03 GMT (envelope-from gnats) Resent-Date: Fri, 17 Nov 2006 04:00:03 GMT Resent-Message-Id: <200611170400.kAH4039r027179@freefall.freebsd.org> Resent-From: FreeBSD-gnats-submit@FreeBSD.org (GNATS Filer) Resent-To: freebsd-doc@FreeBSD.org Resent-Reply-To: FreeBSD-gnats-submit@FreeBSD.org, Toby Burress Received: from mx1.FreeBSD.org (mx1.freebsd.org [216.136.204.125]) by hub.freebsd.org (Postfix) with ESMTP id 50BEF16A412 for ; Fri, 17 Nov 2006 03:55:04 +0000 (UTC) (envelope-from kurin@delete.org) Received: from cobalt.delete.org (cobalt.delete.org [198.177.254.162]) by mx1.FreeBSD.org (Postfix) with ESMTP id A2F0643D55 for ; Fri, 17 Nov 2006 03:55:03 +0000 (GMT) (envelope-from kurin@delete.org) Received: from localhost (localhost.delete.org [127.0.0.1]) by cobalt.delete.org (Postfix) with ESMTP id 0DB1584427 for ; Thu, 16 Nov 2006 22:54:53 -0500 (EST) Received: from cobalt.delete.org ([127.0.0.1]) by localhost (cobalt.delete.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id bV9C4hj1HfzF for ; Thu, 16 Nov 2006 22:54:36 -0500 (EST) Received: by cobalt.delete.org (Postfix, from userid 1028) id 5A58684424; Thu, 16 Nov 2006 22:54:36 -0500 (EST) Message-Id: <20061117035436.5A58684424@cobalt.delete.org> Date: Thu, 16 Nov 2006 22:54:36 -0500 (EST) From: Toby Burress To: FreeBSD-gnats-submit@FreeBSD.org X-Send-Pr-Version: 3.113 Cc: Subject: docs/105620: [article] LDAP Authentication X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.5 Precedence: list Reply-To: Toby Burress List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Fri, 17 Nov 2006 04:00:04 -0000 >Number: 105620 >Category: docs >Synopsis: [article] LDAP Authentication >Confidential: no >Severity: non-critical >Priority: low >Responsible: freebsd-doc >State: open >Quarter: >Keywords: >Date-Required: >Class: update >Submitter-Id: current-users >Arrival-Date: Fri Nov 17 04:00:02 GMT 2006 >Closed-Date: >Last-Modified: >Originator: Toby Burress >Release: FreeBSD 5.4-STABLE i386 >Organization: >Environment: >Description: Documentation article for authentication against an LDAP directory. >How-To-Repeat: >Fix: I named it 'ldap-auth' but I dunno whatever's good. %articles.ent; ]>
LDAP Authentication Toby Burress
kurin@causa-sui.net
 $FreeBSD$ 2006 The FreeBSD Documentation Project &tm-attrib.freebsd; &tm-attrib.general; This document is indended to be a guide to using an LDAP server (principally an OpenLDAP server) for authentication on &os;. This is useful for situations where many servers need the same accounts, e.g. as a replacement for NIS. ldap Preface This document is intended to give the reader enough of an understanding of LDAP to configure an LDAP server, as well as an understanding of net/nss_ldap and security/pam_ldap so that they can be configured to use an LDAP server. When finished, the reader should be able to configure and deploy a &os; server that will authenticate against an LDAP directory. This article is not intended to be an exhaustive account of the security, robustness, or best practices for configuring LDAP the other related services discussed. While the author takes care not to do anything dumb, neither does he go out of his way to address security issues. This article should be considered as laying the theoretical groundwork only, and any actual implementation should be accompanied by active thought. For this article, we will have two servers, server.freebsd.org and client.freebsd.org. The LDAP base will be dc=freebsd,dc=org. Configuring LDAP LDAP stands for Lightweight Directory Access Protocol and is a subset of the X.500 DAP protocol. It is most newly codified in RFC4510 and friends. Basically it is a database that expects to be read from more often than it is written to. The LDAP server OpenLDAP will the be used in the examples in this document; while the principles here should be generally applicable among many different servers, most of the concrete administration is OpenLDAP-specific. There are (basically) two areas of the LDAP service which need configuration; the first is setting up the server to receive connections properly, and the second is adding entries to the directory that the &os; tools know how to work with. Setting Up the Server for Connections This section is specific to OpenLDAP. If you are using another server, you will need to consult that server's documentation. You will probably want to use some kind of encryption in your connections to the LDAP server; otherwise your users' passwords will be floating over the ether in what amounts to plain text. The tools we will be using support two very similar kinds of encryption, SSL and TLS. TLS stands for Transportation Layer Security. Services that employ TLS tend to connect on the same ports as those same services without TLS; thus an SMTP server which supports TLS will listen for connections on port 25, and an LDAP server will listen on 389. SSL stands for Secure Sockets Layer, and services that implement SSL do not listen on the same ports as their non-SSL counterparts. Thus SMTPS listens on port 465 (not 45), HTTPS listens on 443, and LDAPS is 636. The reason SSL uses a different port than TLS is because a TLS connection begins as plain text, and switches to encrypted traffic after the STARTTLS directive. SSL connections are encrypted from the start. Other than that there is no difference between the two. We will be configuring OpenLDAP to use SSL; this is indicated solely by the use of the -h "ldaps://" directive when starting the server. Omitted, OpenLDAP would listen for TLS connections on 389. Once OpenLDAP is installed, the following configuration parameters in slapd.conf will enable SSL: security ssf=128 TLSCertificateFile /path/to/your/cert.crt TLSCertificateKeyFile /path/to/your/cert.key TLSCACertificateFile /path/to/your/cacert.crt Here, ssf=128 tells OpenLDAP to require 128-bit encryption for all connections (search + update). This parameter can be configured more exactly to your taste. The cert.crt, cert.key, and cacert.crt are necessary for clients to authenticate you as the valid LDAP server. If you simply want a server that runs, you can create a self-signed certificate with OpenSSL: &prompt.user; openssl genrsa -out cert.key 1024 Generating RSA private key, 1024 bit long modulus ....................++++++ ...++++++ e is 65537 (0x10001) &prompt.user; openssl req -new -key cert.key -out cert.csr At this point you should be prompted for some values. You can enter whatever you like, but it is important that the Common Name value be the fully qualified domain name of the server OpenLDAP will be running on, in our case server.freebsd.org. Otherwise your clients will refuse to connect. Finally, the certificate signing request needs to be signed: &prompt.user; openssl x509 -req -in cert.csr -days 365 -signkey cert.key -out cert.crt Signature ok subject=/C=AU/ST=Some-State/O=Internet Widgits Pty Ltd Getting Private key This will create a self-signed certificate that can be used for the directives in slapd.conf, with cert.crt and cacert.crt being the same file. If you are going to use many OpenLDAP servers (for replication via slurpd) you will want to see to generate a CA key, and use it to sign independent certificates. Once this is done, put the following values in /etc/rc.conf: slapd_flags="-h 'ldaps://'" slapd_enable="YES" and run /usr/local/etc/rc.d/slapd start. This should start OpenLDAP. Confirm that it is listening on 636 with &prompt.user; sockstat -4 -p 636 ldap slapd 3261 7 tcp4 *:636 *:* Finally, the client machines need to be configured to talk to the LDAP server. The client machines will always have OpenLDAP libraries, since that is all security/pam_ldap and net/nss_ldap support, at least for the moment. The configuration file for the OpenLDAP libraries is /usr/local/etc/openldap/ldap.conf. Edit this file to contain the following values: base dc=freebsd,dc=org uri ldaps://server.freebsd.org/ ssl on tls_cacert /path/to/your/cacert.crt It is important that your clients have access to cacert.crt, otherwise they will not be able to connect. At this point you should be able to run ldapsearch on the client machine. If you encounter an error, then something is configured wrong; most likely it is your certificates. Use openssl s_client and openssl s_server to ensure you have them configured and signed properly. Entries in the Database Authentication against an LDAP directory is generally accomplished by trying to bind to the directory as the user in question. This is accomplished by establishing a simple bind on the directory with the dn of the username and the password in that user's userPassword attribute. Thus the first thing we have to do is figure out is where in the directory our users will live. The base entry for our database is dc=freebsd,dc=org. The default location for users that most clients seem to expect is ou=people,base, so that is what will be used here, however keep in mind that this is configurable (actually, it doesn't truly matter at all). So the ldif entry for the people organizational unit will look like: dn: ou=people,dc=freebsd,dc=org objectClass: top objectClass: organizationalUnit ou: people All users will be created as subentries of this organizational unit. Some thought might be given to the object class your users will belong to. Most tools by default will use people, which is fine if you simply want to provide entries to authenticate against. However, if you are going to store user information in the LDAP database as well, you will probably want to use inetOrgPerson. In either case, the relevant schemas need to be loaded in slapd.conf. For this example we will use the person object class. If you are using inetOrgPerson, the steps are basically identical, except that the sn attribute is required. To add a user testuser, the ldif would be: dn: uid=tuser,ou=people,dc=freebsd,dc=org objectClass: person objectClass: posixAccount objectClass: shadowAccount objectClass: top uidNumber: 10000 gidNumber: 10000 homeDirectory: /home/tuser loginShell: /bin/csh uid: tuser cn: tuser I start my LDAP users' UIDs at 10000; you can configure whatever number you wish here, as long as it's less than 65536. We also need group entries. They are as configurable as user entries, but we will use the defaults below: dn: ou=groups,dc=freebsd,dc=org objectClass: top objectClass: organizationalUnit ou: groups dn: cn=tuser,ou=groups,dc=freebsd,dc=org objectClass: posixGroup objectClass: top gidNumber: 10000 cn: tuser To enter these into your database, you can use slapadd or ldapadd on a file containing these entries. Alternatively, you can use sysutils/ldapvi. An ldapsearch on the client machine should now return these entries. If it does, your database is properly configured to be used as an LDAP authentication server. Client Configuration &os; requires two services to be installed to authenticate against an LDAP server correctly, security/pam_ldap and net/nss_ldap. Once these are installed the server will be ready. Authentication security/pam_ldap is configured via /usr/local/etc/ldap.conf. Note that this is a different file than the OpenLDAP library functions' configuration file, /usr/local/etc/openldap/ldap.conf, however it takes many of the same options; in fact it is a superset of that file. For the rest of this section, references to ldap.conf will mean /usr/local/etc/ldap.conf. Thus, first we will want to copy all of our original configuration parameters from openldap/ldap.conf to the new ldap.conf. Once this is done, we want to tell security/pam_ldap what to look for on the directory server. We are identifying our users with the uid attribute. To configure this (though it is the default), set the pam_ldap_attribute directive in ldap.conf. With this set, pam_ldap will search the entire LDAP directory under base for the value uid=username. If it finds one and only one entry, and binds to it correctly, then it will allow access. Otherwise it will fail. PAM PAM, which stands for pluggable authentication modules, is the method by which &os; authenticates most of its sessions. To tell &os; we wish to use an LDAP server, we will have to add the appropriate line to the appropriate PAM file. Most of the time the appropriate PAM file is /etc/pam.d/sshd, if you want to use SSH (remember to set the appropriate options in /etc/ssh/sshd_config, otherwise SSH will not use PAM). To use PAM for authentication, add the line auth sufficient /usr/local/lib/pam_ldap.so no_warn Exactly where this line shows up in the file and which options appear in the fourth column determine the exact behavior of the authentication mechanism; see &man.pam.d.5; With this configuration you should be able to authenticate a user against an LDAP directory, however it is usually not ideal to allow every user in the directory into every client machine. Fortunately there are a few ways to restrict user access. ldap.conf supports a pam_groupdn directive; every account that connects to this machine needs to be a member of the group specified here. So, for example, if you have pam_groupdn cn=production,ou=accessgroups,dc=freebsd,dc=org in ldap.conf, then only members of that group will be able to log in. There are a few things to bear in mind, however. Members of this group are specified in one or more memberUid attributes, and each attribute must have the full distinguished name of the member. So memberUid: someuser will not work; it must be memberUid: uid=someuser,ou=people,dc=freebsd,dc=org. Additionally, this directive is not checked in PAM during authentication, it is checked during account management, so you will need a second line in your PAM files under account. This will require, in turn, cause every user to be in the group listed. You may want to take advantage of the ignore_authinfo_unavail option so that you are not locked out of every computer when the LDAP server is unavailable. Name Service Switch The net/nss_ldap port uses the same configuration file as security/pam_ldap, and should not need any extra parameters once it is installed. Instead, what is left is simply to edit /etc/nsswitch.conf to take advantage of the directory. Simply replace the following lines: group: compat passwd: compat with group: files ldap passwd: files ldap This will allow you to map usernames to UIDs and UIDs to usernames. Congratulations! You should now have working LDAP authentication. Securing LDAP Accounts While it is not strictly necessary, in the sense that authentication will work without it, you will probably want to secure access to some user attributes in your LDAP server. In OpenLDAP, this is accomplished through ACLs in slapd.conf. To begin with, the userPassword attribute should not be world-readable. By default, anyone who can connect to the LDAP server can read this attribute. To disable this, put the following in slapd.conf: access to attrs=userPassword by self write by anonymous auth by * none access to * by self write by * read This will disallow reading of the userPassword attribute, while still allowing users to change their own passwords. There is still one important security hole to close, however. By default, users can change any attribute (except for those which the LDAP schemas themselves deny changes), such as uidNumber. To close this hole, modify the above to access to attrs=userPassword by self write by anonymous auth by * none access to attrs=homeDirectory,uidNumber,gidNumber by * read access to * by self write by * read This will stop users from being able to masquerade as other users. Useful Aids There are a few other programs that might be useful, particularly if you have many users and do not want to configure everything manually. security/pam_mkhomedir is a PAM module that always succeeds; its purpose is to create home directories for users which do not have them. If you have dozens of client servers and hundreds of users, it is much easier to use this and set up skeleton directories than to prepare every home directory. sysutils/cpu is a &man.pw.8;-like utility that can be used to manage users in the LDAP directory. You can call it directly, or wrap scripts around it. It can handle both TLS (with the -x flag) and SSL (directly). OpenSSL Certificates For LDAP If you are hosting two or more LDAP servers, you will probably not want to use self-signed certificates, since each client will have to be configured to work with each certificate. While this is possible, it is not nearly as simple as creating your own certificate authority, and signing your servers' certificates with that. The steps here are presented as they are with very little attempt at explaining what is going on—further explanation can be found in &man.openssl.1; and its friends. To create a certificate authority, we simply need a self-signed certificate and key. The steps for this again are &prompt.user; openssl genrsa -out root.key 1024 &prompt.user; openssl req -new -key root.key -out root.csr &prompt.user; openssl x509 -req -days 1024 -in root.csr -signkey root.key -out root.crt These will be your root CA key and certificate. You will probably want to encrypt the key and store it in a cool, dry place; anyone with access to it can masquerade as one of your LDAP servers. Next, using the first two steps above create a key ldap-server-one.key and certificate signing request ldap-server-one.csr. Once you sign the signing request with root.key, you will be able to use ldap-server-one.* on your LDAP servers. Do not forget to use the fully qualified domain name for the common name attribute when generating the certificate signing request; otherwise clients will reject a connection with you, and it can be very tricky to diagnose. To sign the key, use -CA and -CAkey instead of -signkey: &prompt.user; openssl x509 -req -days 1024 \ -in ldap-server-one.csr -CA root.crt -CAkey root.key \ -out ldap-server-one.crt The resulting file will be the certificate that you can use on your LDAP servers. Finally, for clients to trust all your servers, distribute root.crt (the certificate, not the key!) to each client, and specify it in the TLSCACertificateFile directive in ldap.conf.
>Release-Note: >Audit-Trail: >Unformatted: