diff options
Diffstat (limited to 'en_US.ISO8859-1/articles/ldap-auth/article.xml')
| -rw-r--r-- | en_US.ISO8859-1/articles/ldap-auth/article.xml | 165 |
1 files changed, 73 insertions, 92 deletions
diff --git a/en_US.ISO8859-1/articles/ldap-auth/article.xml b/en_US.ISO8859-1/articles/ldap-auth/article.xml index 7f055fa72a..d52067546f 100644 --- a/en_US.ISO8859-1/articles/ldap-auth/article.xml +++ b/en_US.ISO8859-1/articles/ldap-auth/article.xml @@ -1,19 +1,14 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN" - "../../../share/xml/freebsd45.dtd"> - -<article lang="en"> - <articleinfo> - <title>LDAP Authentication</title> +<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" + "../../../share/xml/freebsd50.dtd"> +<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> + <info><title>LDAP Authentication</title> + <authorgroup> - <author> - <firstname>Toby</firstname> - <surname>Burress</surname> - <affiliation> + <author><personname><firstname>Toby</firstname><surname>Burress</surname></personname><affiliation> <address><email>kurin@causa-sui.net</email></address> - </affiliation> - </author> + </affiliation></author> </authorgroup> <copyright> @@ -22,7 +17,7 @@ <holder>The FreeBSD Documentation Project</holder> </copyright> - <legalnotice id="trademarks" role="trademarks"> + <legalnotice xml:id="trademarks" role="trademarks"> &tm-attrib.freebsd; &tm-attrib.general; </legalnotice> @@ -38,16 +33,16 @@ where many servers need the same user accounts, for example as a replacement for <application>NIS</application>.</para> </abstract> - </articleinfo> + </info> - <sect1 id="preface"> + <sect1 xml:id="preface"> <title>Preface</title> <para>This document is intended to give the reader enough of an understanding of LDAP to configure an LDAP server. This document will attempt to provide an - explanation of <filename role="package">net/nss_ldap</filename> - and <filename role="package">security/pam_ldap</filename> for use with + explanation of <package>net/nss_ldap</package> + and <package>security/pam_ldap</package> for use with client machines services for use with the LDAP server.</para> <para>When finished, the reader should be able to configure and @@ -65,32 +60,28 @@ analysis.</para> </sect1> - <sect1 id="ldap"> + <sect1 xml:id="ldap"> <title>Configuring LDAP</title> <para>LDAP stands for <quote>Lightweight Directory Access Protocol</quote> and is a subset of the X.500 Directory Access - Protocol. Its most recent specifications are in <ulink - url="http://www.ietf.org/rfc/rfc4510.txt">RFC4510</ulink> and + Protocol. Its most recent specifications are in <link xlink:href="http://www.ietf.org/rfc/rfc4510.txt">RFC4510</link> and friends. Essentially it is a database that expects to be read from more often than it is written to.</para> - <para>The LDAP server <ulink - url="http://www.openldap.org/">OpenLDAP</ulink> will be used in the + <para>The LDAP server <link xlink:href="http://www.openldap.org/">OpenLDAP</link> will be used in the examples in this document; while the principles here should be generally applicable to many different servers, most of the concrete administration is <application>OpenLDAP</application>-specific. There are several - server versions in ports, for example <filename - role="package">net/openldap24-server</filename>. Client servers - will need the corresponding <filename - role="package">net/openldap24-client</filename> libraries.</para> + server versions in ports, for example <package>net/openldap24-server</package>. Client servers + will need the corresponding <package>net/openldap24-client</package> libraries.</para> <para>There are (basically) two areas of the LDAP service which need configuration. The first is setting up a server to receive connections properly, and the second is adding entries to the server's directory so that &os; tools know how to interact with it.</para> - <sect2 id="ldap-connect"> + <sect2 xml:id="ldap-connect"> <title>Setting Up the Server for Connections</title> <note> @@ -100,12 +91,12 @@ documentation.</para> </note> - <sect3 id="ldap-connect-install"> + <sect3 xml:id="ldap-connect-install"> <title>Installing <application>OpenLDAP</application></title> <para>First, install <application>OpenLDAP</application>:</para> - <example id="oldap-install"> + <example xml:id="oldap-install"> <title>Installing <application>OpenLDAP</application></title> <screen>&prompt.root; <userinput>cd /usr/ports/net/openldap24-server</userinput> @@ -117,7 +108,7 @@ <application>OpenLDAP</application> libraries.</para> </sect3> - <sect3 id="ldap-connect-config"> + <sect3 xml:id="ldap-connect-config"> <title>Configuring <application>OpenLDAP</application></title> <para>Next we must configure @@ -179,7 +170,7 @@ TLSCACertificateFile /path/to/your/cacert.crt</programlisting> server. If you simply want a server that runs, you can create a self-signed certificate with OpenSSL:</para> - <example id="genrsa"> + <example xml:id="genrsa"> <title>Generating an RSA key</title> <screen>&prompt.user; <userinput>openssl genrsa -out cert.key 1024</userinput> @@ -204,7 +195,7 @@ e is 65537 (0x10001) <para>Finally, the certificate signing request needs to be signed:</para> - <example id="self-sign"> + <example xml:id="self-sign"> <title>Self-signing the certificate</title> <screen>&prompt.user; <userinput>openssl x509 -req -in cert.csr -days 365 -signkey cert.key -out cert.crt</userinput> @@ -236,16 +227,13 @@ Getting Private key</screen> ldap slapd 3261 7 tcp4 *:389 *:*</screen> </sect3> - <sect3 id="ldap-connect-client"> + <sect3 xml:id="ldap-connect-client"> <title>Configuring the Client</title> - <para>Install the <filename - role="package">net/openldap24-client</filename> port for the + <para>Install the <package>net/openldap24-client</package> port for the <application>OpenLDAP</application> libraries. The client machines will always have <application>OpenLDAP</application> - libraries since that is all <filename - role="package">security/pam_ldap</filename> and <filename - role="package">net/nss_ldap</filename> support, at least for the + libraries since that is all <package>security/pam_ldap</package> and <package>net/nss_ldap</package> support, at least for the moment.</para> <para>The configuration file for the @@ -283,7 +271,7 @@ tls_cacert /path/to/your/cacert.crt</programlisting> </sect3> </sect2> - <sect2 id="ldap-database"> + <sect2 xml:id="ldap-database"> <title>Entries in the Database</title> <para>Authentication against an LDAP directory is generally @@ -300,7 +288,7 @@ tls_cacert /path/to/your/cacert.crt</programlisting> <para>The base entry for our database is <literal>dc=example,dc=org</literal>. The default location for users that most clients seem to expect is something like - <literal>ou=people,<replaceable>base</replaceable></literal>, so + <literal>ou=people,base</literal>, so that is what will be used here. However keep in mind that this is configurable.</para> @@ -366,7 +354,7 @@ cn: tuser</programlisting> <para>To enter these into your database, you can use <command>slapadd</command> or <command>ldapadd</command> on a file containing these entries. Alternatively, you can use - <filename role="package">sysutils/ldapvi</filename>.</para> + <package>sysutils/ldapvi</package>.</para> <para>The <command>ldapsearch</command> utility on the client machine should now return these entries. If it does, your database is @@ -374,25 +362,21 @@ cn: tuser</programlisting> </sect2> </sect1> - <sect1 id="client"> + <sect1 xml:id="client"> <title>Client Configuration</title> <para>The client should already have - <application>OpenLDAP</application> libraries from <xref - linkend="ldap-connect-client"/>, but if you are installing several - client machines you will need to install <filename - role="package">net/openldap24-client</filename> on each of + <application>OpenLDAP</application> libraries from <xref linkend="ldap-connect-client"/>, but if you are installing several + client machines you will need to install <package>net/openldap24-client</package> on each of them.</para> <para>&os; requires two ports to be installed to authenticate - against an LDAP server, <filename - role="package">security/pam_ldap</filename> and <filename - role="package">net/nss_ldap</filename>.</para> + against an LDAP server, <package>security/pam_ldap</package> and <package>net/nss_ldap</package>.</para> - <sect2 id="client-auth"> + <sect2 xml:id="client-auth"> <title>Authentication</title> - <para><filename role="package">security/pam_ldap</filename> is + <para><package>security/pam_ldap</package> is configured via <filename>/usr/local/etc/ldap.conf</filename>.</para> <note> @@ -410,7 +394,7 @@ cn: tuser</programlisting> configuration parameters from <filename>openldap/ldap.conf</filename> to the new <filename>ldap.conf</filename>. Once this is done, we want to - tell <filename role="package">security/pam_ldap</filename> what to + tell <package>security/pam_ldap</package> what to look for on the directory server.</para> <para>We are identifying our users with the <literal>uid</literal> @@ -418,21 +402,20 @@ cn: tuser</programlisting> <literal>pam_login_attribute</literal> directive in <filename>ldap.conf</filename>:</para> - <example id="set-pam-login-attr"> + <example xml:id="set-pam-login-attr"> <title>Setting <literal>pam_login_attribute</literal></title> <programlisting>pam_login_attribute uid</programlisting> </example> - <para>With this set, <filename - role="package">security/pam_ldap</filename> will search the entire + <para>With this set, <package>security/pam_ldap</package> will search the entire LDAP directory under <literal>base</literal> for the value - <literal>uid=<replaceable>username</replaceable></literal>. If it + <literal>uid=username</literal>. If it finds one and only one entry, it will attempt to bind as that user with the password it was given. If it binds correctly, then it will allow access. Otherwise it will fail.</para> - <sect3 id="client-auth-pam"> + <sect3 xml:id="client-auth-pam"> <title>PAM</title> <para>PAM, which stands for <quote>Pluggable Authentication @@ -501,7 +484,7 @@ cn: tuser</programlisting> <para>Your <filename>pam.d/sshd</filename> might then end up looking like this:</para> - <example id="pam"> + <example xml:id="pam"> <title>Sample <filename>pam.d/sshd</filename></title> <programlisting>auth required pam_nologin.so no_warn @@ -525,7 +508,7 @@ account required /usr/local/lib/pam_ldap.so no_warn ignore_a </sect3> </sect2> - <sect2 id="client-nss"> + <sect2 xml:id="client-nss"> <title>Name Service Switch</title> <para><application>NSS</application> is the service that maps @@ -539,9 +522,8 @@ account required /usr/local/lib/pam_ldap.so no_warn ignore_a tell <application>NSS</application> to look there when queried.</para> - <para>The <filename role="package">net/nss_ldap</filename> port - does this. It uses the same configuration file as <filename - role="package">security/pam_ldap</filename>, and should not need + <para>The <package>net/nss_ldap</package> port + does this. It uses the same configuration file as <package>security/pam_ldap</package>, and should not need any extra parameters once it is installed. Instead, what is left is simply to edit <filename>/etc/nsswitch.conf</filename> to take advantage of the directory. Simply replace the following @@ -562,7 +544,7 @@ passwd: files ldap</programlisting> authentication.</para> </sect2> - <sect2 id="caveats"> + <sect2 xml:id="caveats"> <title>Caveats</title> <para>Unfortunately, as of the time this was written &os; did not @@ -570,10 +552,9 @@ passwd: files ldap</programlisting> this, most administrators are left to implement a solution themselves. I provide some examples here. Note that if you write your own password change script, there are some security issues - you should be made aware of; see <xref - linkend="security-passwd"/></para> + you should be made aware of; see <xref linkend="security-passwd"/></para> - <example id="chpw-shell"> + <example xml:id="chpw-shell"> <title>Shell script for changing passwords</title> <programlisting><![CDATA[#!/bin/sh @@ -611,7 +592,7 @@ ldappasswd -D uid="$USER",ou=people,dc=example,dc=org \ that can change LDAP passwords. It sees use both on the command line, and on the web.</para> - <example id="chpw-ruby"> + <example xml:id="chpw-ruby"> <title>Ruby script for changing passwords</title> <programlisting><![CDATA[require 'ldap' @@ -658,7 +639,7 @@ conn.modify(luser, [replace])]]></programlisting> </sect2> </sect1> - <sect1 id="secure"> + <sect1 xml:id="secure"> <title>Security Considerations</title> <para>Now that your machines (and possibly other services) are @@ -672,20 +653,20 @@ conn.modify(luser, [replace])]]></programlisting> continually review your configuration and procedures for improvements.</para> - <sect2 id="secure-readonly"> + <sect2 xml:id="secure-readonly"> <title>Setting attributes read-only</title> <para>Several attributes in LDAP should be read-only. If left writable by the user, for example, a user could change his <literal>uidNumber</literal> attribute to <literal>0</literal> and - get <username>root</username> access!</para> + get <systemitem class="username">root</systemitem> access!</para> <para>To begin with, the <literal>userPassword</literal> 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 <filename>slapd.conf</filename>:</para> - <example id="hide-userpass"> + <example xml:id="hide-userpass"> <title>Hide passwords</title> <programlisting>access to dn.subtree="ou=people,dc=example,dc=org" @@ -709,7 +690,7 @@ access to * changes), such as <literal>uidNumber</literal>. To close this hole, modify the above to</para> - <example id="attrib-readonly"> + <example xml:id="attrib-readonly"> <title>Read-only attributes</title> <programlisting>access to dn.subtree="ou=people,dc=example,dc=org" @@ -730,25 +711,25 @@ access to * users.</para> </sect2> - <sect2 id="secure-root"> - <title><username>Root</username> account definition</title> + <sect2 xml:id="secure-root"> + <title><systemitem class="username">Root</systemitem> account definition</title> - <para>Often the <username>root</username> or manager account for + <para>Often the <systemitem class="username">root</systemitem> or manager account for the LDAP service will be defined in the configuration file. <application>OpenLDAP</application> supports this, for example, and it works, but it can lead to trouble if <filename>slapd.conf</filename> is compromised. It may be better to use this only to bootstrap yourself into LDAP, and then define - a <username>root</username> account there.</para> + a <systemitem class="username">root</systemitem> account there.</para> <para>Even better is to define accounts that have limited - permissions, and omit a <username>root</username> account entirely. + permissions, and omit a <systemitem class="username">root</systemitem> account entirely. For example, users to can add or remove user accounts are added to one group, but they cannot themselves change the membership of this group. Such a security policy would help mitigate the effects of a leaked password.</para> - <sect3 id="manager-acct"> + <sect3 xml:id="manager-acct"> <title>Creating a management group</title> <para>Say you want your IT department to be able to change home @@ -756,7 +737,7 @@ access to * to add or remove users. The way to do this is to add a group for these admins:</para> - <example id="manager-acct-dn"> + <example xml:id="manager-acct-dn"> <title>Creating a management group</title> <programlisting>dn: cn=homemanagement,dc=example,dc=org @@ -771,7 +752,7 @@ memberUid: uid=user2,ou=people,dc=example,dc=org</programlisting> <para>And then change the permissions attributes in <filename>slapd.conf</filename>:</para> - <example id="management-acct-acl"> + <example xml:id="management-acct-acl"> <title>ACLs for a home directory management group</title> <programlisting>access to dn.subtree="ou=people,dc=example,dc=org" @@ -780,19 +761,19 @@ memberUid: uid=user2,ou=people,dc=example,dc=org</programlisting> dnattr=memberUid write</programlisting> </example> - <para>Now <username>tuser</username> and <username>user2</username> + <para>Now <systemitem class="username">tuser</systemitem> and <systemitem class="username">user2</systemitem> can change other users' home directories.</para> <para>In this example we've given a subset of administrative power to certain users without giving them power in other domains. The idea is that soon no single user account has the - power of a <username>root</username> account, but every power - root had is had by at least one user. The <username>root</username> + power of a <systemitem class="username">root</systemitem> account, but every power + root had is had by at least one user. The <systemitem class="username">root</systemitem> account then becomes unnecessary and can be removed.</para> </sect3> </sect2> - <sect2 id="security-passwd"> + <sect2 xml:id="security-passwd"> <title>Password storage</title> <para>By default <application>OpenLDAP</application> will store @@ -807,41 +788,41 @@ memberUid: uid=user2,ou=people,dc=example,dc=org</programlisting> </sect2> </sect1> - <appendix id="useful"> + <appendix xml:id="useful"> <title>Useful Aids</title> <para>There are a few other programs that might be useful, particularly if you have many users and do not want to configure everything manually.</para> - <para><filename role="package">security/pam_mkhomedir</filename> is + <para><package>security/pam_mkhomedir</package> 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.</para> - <para><filename role="package">sysutils/cpu</filename> is a + <para><package>sysutils/cpu</package> 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 <option>-x</option> flag) and SSL (directly).</para> - <para><filename role="package">sysutils/ldapvi</filename> is a great + <para><package>sysutils/ldapvi</package> is a great utility for editing LDAP values in an LDIF-like syntax. The directory (or subsection of the directory) is presented in the editor chosen by the <envar>EDITOR</envar> environment variable. This makes it easy to enable large-scale changes in the directory without having to write a custom tool.</para> - <para><filename role="package">security/openssh-portable</filename> + <para><package>security/openssh-portable</package> has the ability to contact an LDAP server to verify <application>SSH</application> keys. This is extremely nice if you have many servers and do not want to copy your public keys across all of them.</para> </appendix> - <appendix id="ssl-ca"> + <appendix xml:id="ssl-ca"> <title><application>OpenSSL</application> Certificates For LDAP</title> <para>If you are hosting two or more LDAP servers, you will probably @@ -859,7 +840,7 @@ memberUid: uid=user2,ou=people,dc=example,dc=org</programlisting> self-signed certificate and key. The steps for this again are</para> - <example id="make-cert"> + <example xml:id="make-cert"> <title>Creating a certificate</title> <screen>&prompt.user; <userinput>openssl genrsa -out root.key 1024</userinput> @@ -890,7 +871,7 @@ memberUid: uid=user2,ou=people,dc=example,dc=org</programlisting> <option>-CAkey</option> instead of <option>-signkey</option>:</para> - <example id="ca-sign"> + <example xml:id="ca-sign"> <title>Signing as a certificate authority</title> <screen>&prompt.user; <userinput>openssl x509 -req -days 1024 \ |