/[gentoo]/xml/htdocs/doc/en/ldap-howto.xml
Gentoo

Contents of /xml/htdocs/doc/en/ldap-howto.xml

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.43 - (hide annotations) (download) (as text)
Mon Apr 18 02:01:11 2011 UTC (3 years, 3 months ago) by nightmorph
Branch: MAIN
Changes since 1.42: +5 -6 lines
File MIME type: application/xml
webmin was removed from portage. without notifying the GDP, as usual.

1 swift 1.1 <?xml version='1.0' encoding='UTF-8'?>
2 nightmorph 1.43 <!-- $Header: /var/cvsroot/gentoo/xml/htdocs/doc/en/ldap-howto.xml,v 1.42 2010/07/13 19:40:28 nightmorph Exp $ -->
3 swift 1.1 <!DOCTYPE guide SYSTEM "/dtd/guide.dtd">
4    
5 nightmorph 1.40 <guide disclaimer="draft">
6 bennyc 1.5 <title>Gentoo Guide to OpenLDAP Authentication</title>
7 swift 1.1
8     <author title="Author">
9 swift 1.26 <mail link="sj7trunks@pendulus.net">Benjamin Coles</mail>
10 swift 1.1 </author>
11     <author title="Editor">
12 nightmorph 1.35 <mail link="swift@gentoo.org">Sven Vermeulen</mail>
13 swift 1.1 </author>
14     <author title="Editor">
15     <mail link="tseng@gentoo.org">Brandon Hale</mail>
16     </author>
17 bennyc 1.5 <author title="Editor">
18     <mail link="bennyc@gentoo.org">Benny Chuang</mail>
19     </author>
20 nightmorph 1.36 <author title="Editor">
21     <mail link="jokey"/>
22     </author>
23 nightmorph 1.40 <author title="Editor">
24     <mail link="nightmorph"/>
25     </author>
26 swift 1.1
27     <abstract>
28     This guide introduces the basics of LDAP and shows you how to setup
29 bennyc 1.5 OpenLDAP for authentication purposes between a group of Gentoo boxes.
30 swift 1.1 </abstract>
31    
32 swift 1.27 <!-- The content of this document is licensed under the CC-BY-SA license -->
33     <!-- See http://creativecommons.org/licenses/by-sa/2.5 -->
34 swift 1.10 <license/>
35    
36 nightmorph 1.43 <version>5</version>
37     <date>2011-04-17</date>
38 swift 1.1
39     <chapter>
40     <title>Getting Started with OpenLDAP</title>
41     <section>
42     <title>What is LDAP?</title>
43     <body>
44    
45     <p>
46     LDAP stands for <e>Lightweight Directory Access Protocol</e>. Based on
47     X.500 it encompasses most of its primary functions, but lacks the more
48     esoteric functions that X.500 has. Now what is this X.500 and why is there an
49     LDAP?
50     </p>
51    
52     <p>
53     X.500 is a model for Directory Services in the OSI concept. It contains
54     namespace definitions and the protocols for querying and updating the
55     directory. However, X.500 has been found to be overkill in many situations.
56     Enter LDAP. Like X.500 it provides a data/namespace model for the
57     directory and a protocol too. However, LDAP is designed to run directly
58     over the TCP/IP stack. See LDAP as a slim-down version of X.500.
59     </p>
60    
61     </body>
62     </section>
63    
64     <section>
65     <title>I don't get it. What is a directory?</title>
66     <body>
67    
68     <p>
69     A directory is a specialized database designed for frequent queries but
70     infrequent updates. Unlike general databases they don't contain
71     transaction support or roll-back functionality. Directories are easily
72     replicated to increase availability and reliability. When directories
73     are replicated, temporary inconsistencies are allowed as long as they
74 swift 1.37 get synchronised eventually.
75 swift 1.1 </p>
76    
77     </body>
78     </section>
79    
80     <section>
81     <title>How is information structured?</title>
82     <body>
83    
84     <p>
85     All information inside a directory is structured hierarchically. Even
86     more, if you want to enter data inside a directory, the directory must
87     know how to store this data inside a tree. Lets take a look at a
88     fictional company and an Internet-like tree:
89     </p>
90    
91     <pre caption = "Organisational structure for GenFic, a Fictional Gentoo company">
92     dc: com
93     |
94     dc: genfic <comment>(Organisation)</comment>
95     / \
96 nightmorph 1.40 ou: People servers <comment>(Organisational Units)</comment>
97 swift 1.37 / \ ..
98 nightmorph 1.40 uid: .. John <comment>(OU-specific data)</comment>
99 swift 1.1 </pre>
100    
101     <p>
102     Since you don't feed data to the database in this ascii-art like manner,
103     every node of such a tree must be defined. To name such nodes, LDAP uses
104     a naming scheme. Most LDAP distributions (including OpenLDAP) already
105     contain quite a number of predefined (and general approved) schemes,
106     such as the inetorgperson, a frequently used scheme to define users.
107     </p>
108    
109     <p>
110     Interested users are encouraged to read the <uri
111 nightmorph 1.41 link="http://www.openldap.org/doc/admin24/">OpenLDAP Admin Guide</uri>.
112 swift 1.1 </p>
113    
114     </body>
115     </section>
116 swift 1.21 <section>
117     <title>So... What's the Use?</title>
118     <body>
119    
120     <p>
121     LDAP can be used for various things. This document focuses on centralised user
122     management, keeping all user accounts in a single LDAP location (which doesn't
123     mean that it's housed on a single server, LDAP supports high availability and
124     redundancy), yet other goals can be achieved using LDAP as well.
125     </p>
126    
127     <ul>
128     <li>Public Key Infrastructure</li>
129     <li>Shared Calendar</li>
130     <li>Shared Addressbook</li>
131     <li>Storage for DHCP, DNS, ...</li>
132     <li>
133     System Class Configuration Directives (keeping track of several server
134     configurations)
135     </li>
136     <li>...</li>
137     </ul>
138 swift 1.1
139 swift 1.21 </body>
140     </section>
141 swift 1.1 </chapter>
142    
143     <chapter>
144     <title>Configuring OpenLDAP</title>
145     <section>
146     <title>Initial Configuration</title>
147     <body>
148    
149     <note>
150     In this document we use the genfic.com address as an example. You will
151     ofcourse have to change this. However, make sure that the top node is an
152     official top level domain (net, com, cc, be, ...).
153     </note>
154    
155     <p>
156 nightmorph 1.39 Let's first emerge OpenLDAP:
157 swift 1.1 </p>
158    
159     <pre caption="Install OpenLDAP">
160 nightmorph 1.39 # <i>emerge openldap</i>
161 swift 1.1 </pre>
162    
163     <p>
164 nightmorph 1.36 Now generate an encrypted password we'll use later on:
165     </p>
166    
167     <pre caption="Generate password">
168 nightmorph 1.39 # <i>slappasswd</i>
169 nightmorph 1.36 New password: my-password
170     Re-enter new password: my-password
171     {SSHA}EzP6I82DZRnW+ou6lyiXHGxSpSOw2XO4
172     </pre>
173    
174     <p>
175     Now edit the LDAP Server config at <path>/etc/openldap/slapd.conf</path>:
176 swift 1.1 </p>
177    
178     <pre caption="/etc/openldap/slapd.conf">
179 nightmorph 1.36 <comment># Include the needed data schemes below core.schema</comment>
180 swift 1.1 include /etc/openldap/schema/cosine.schema
181     include /etc/openldap/schema/inetorgperson.schema
182     include /etc/openldap/schema/nis.schema
183    
184 nightmorph 1.36 <comment>Uncomment modulepath and hdb module</comment>
185     # Load dynamic backend modules:
186     modulepath /usr/lib/openldap/openldap
187     # moduleload back_shell.so
188     # moduleload back_relay.so
189     # moduleload back_perl.so
190     # moduleload back_passwd.so
191     # moduleload back_null.so
192     # moduleload back_monitor.so
193     # moduleload back_meta.so
194     moduleload back_hdb.so
195     # moduleload back_dnssrv.so
196    
197     <comment># Uncomment sample access restrictions (Note: maintain indentation!)</comment>
198     access to dn.base="" by * read
199     access to dn.base="cn=Subschema" by * read
200     access to *
201     by self write
202     by users read
203     by anonymous auth
204 swift 1.1
205    
206 nightmorph 1.36 <comment># BDB Database definition</comment>
207 swift 1.1
208 nightmorph 1.36 database hdb
209 swift 1.1 suffix "dc=genfic,dc=com"
210 nightmorph 1.36 checkpoint 32 30 # &lt;kbyte&gt; &lt;min&gt;
211 swift 1.1 rootdn "cn=Manager,dc=genfic,dc=com"
212 nightmorph 1.36 rootpw <i>{SSHA}EzP6I82DZRnW+ou6lyiXHGxSpSOw2XO4</i>
213 swift 1.1 directory /var/lib/openldap-ldbm
214     index objectClass eq
215     </pre>
216    
217     <p>
218 nightmorph 1.36 Next we edit the LDAP Client configuration file:
219 swift 1.1 </p>
220    
221     <pre caption="/etc/openldap/ldap.conf">
222     # <i>nano -w /etc/openldap/ldap.conf</i>
223 neysx 1.23 <comment>(Add the following...)</comment>
224 swift 1.1
225 swift 1.6 BASE dc=genfic, dc=com
226 nightmorph 1.36 URI ldap://auth.genfic.com:389/
227 swift 1.6 TLS_REQCERT allow
228 swift 1.1 </pre>
229    
230     <p>
231 nightmorph 1.42 Now edit <path>/etc/conf.d/slapd</path> and uncomment the following OPTS line:
232 swift 1.1 </p>
233    
234     <pre caption="/etc/conf.d/slapd">
235 nightmorph 1.36 <comment># Note: we don't use cn=config here, so stay with this line:</comment>
236 nightmorph 1.42 OPTS="-F /etc/openldap/slapd.d -h 'ldaps:// ldap:// ldapi://%2fvar%2frun%2fopenldap%2fslapd.sock'"
237 swift 1.1 </pre>
238    
239     <p>
240     Start slapd:
241     </p>
242    
243     <pre caption = "Starting SLAPd">
244     # <i>/etc/init.d/slapd start</i>
245     </pre>
246    
247     <p>
248     You can test with the following command:
249     </p>
250    
251     <pre caption = "Test the SLAPd daemon">
252 nightmorph 1.38 # <i>ldapsearch -x -D "cn=Manager,dc=genfic,dc=com" -W</i>
253 swift 1.1 </pre>
254    
255     <p>
256     If you receive an error, try adding <c>-d 255</c> to increase the
257     verbosity and solve the issue you have.
258     </p>
259    
260     </body>
261     </section>
262     </chapter>
263    
264     <chapter>
265 nightmorph 1.36 <title>Client Configuration</title>
266 swift 1.1 <section>
267 nightmorph 1.36 <title>Migrate existing data to ldap</title>
268 swift 1.1 <body>
269    
270     <p>
271 nightmorph 1.36 Go to <uri
272     link="http://www.padl.com/OSS/MigrationTools.html">http://www.padl.com/OSS/MigrationTools.html</uri>
273     and fetch the scripts there. Configuration is stated on the page. We don't ship
274     this anymore because the scripts are a potential security hole if you leave
275     them on the system after porting. When you've finished migrating your data,
276     continue to the next section.
277 swift 1.19 </p>
278    
279 swift 1.1 </body>
280     </section>
281     <section>
282     <title>Configuring PAM</title>
283     <body>
284    
285     <p>
286 swift 1.20 First, we will configure PAM to allow LDAP authorization. Install
287 jkt 1.32 <c>sys-auth/pam_ldap</c> so that PAM supports LDAP authorization, and
288     <c>sys-auth/nss_ldap</c> so that your system can cope with LDAP servers for
289 swift 1.20 additional information (used by <path>nsswitch.conf</path>).
290     </p>
291    
292     <pre caption="Installing pam_ldap and nss_ldap">
293     # <i>emerge pam_ldap nss_ldap</i>
294     </pre>
295    
296     <p>
297 swift 1.37 Now add the following lines in the right places to
298     <path>/etc/pam.d/system-auth</path>:
299 swift 1.1 </p>
300    
301     <pre caption="/etc/pam.d/system-auth">
302 nightmorph 1.36 <comment># Note: only add them. Don't kill stuff already in there or your box won't let you login again!</comment>
303    
304     auth sufficient pam_ldap.so use_first_pass
305     account sufficient pam_ldap.so
306     password sufficient pam_ldap.so use_authtok use_first_pass
307     session optional pam_ldap.so
308    
309     <comment># Example file:</comment>
310     #%PAM-1.0
311    
312     auth required pam_env.so
313     auth sufficient pam_unix.so try_first_pass likeauth nullok
314     <i>auth sufficient pam_ldap.so use_first_pass</i>
315     auth required pam_deny.so
316    
317     <i>account sufficient pam_ldap.so</i>
318     account required pam_unix.so
319    
320     password required pam_cracklib.so difok=2 minlen=8 dcredit=2 ocredit=2 try_first_pass retry=3
321     password sufficient pam_unix.so try_first_pass use_authtok nullok md5 shadow
322     <i>password sufficient pam_ldap.so use_authtok use_first_pass</i>
323     password required pam_deny.so
324    
325     session required pam_limits.so
326     session required pam_unix.so
327     <i>session optional pam_ldap.so</i>
328    
329 swift 1.1 </pre>
330    
331     <p>
332     Now change <path>/etc/ldap.conf</path> to read:
333     </p>
334    
335     <pre caption="/etc/ldap.conf">
336     <comment>#host 127.0.0.1</comment>
337     <comment>#base dc=padl,dc=com</comment>
338    
339     suffix "dc=genfic,dc=com"
340     <comment>#rootbinddn uid=root,ou=People,dc=genfic,dc=com</comment>
341    
342 nightmorph 1.36 uri ldap://auth.genfic.com/
343 swift 1.1 pam_password exop
344    
345     ldap_version 3
346     pam_filter objectclass=posixAccount
347     pam_login_attribute uid
348     pam_member_attribute memberuid
349     nss_base_passwd ou=People,dc=genfic,dc=com
350     nss_base_shadow ou=People,dc=genfic,dc=com
351     nss_base_group ou=Group,dc=genfic,dc=com
352     nss_base_hosts ou=Hosts,dc=genfic,dc=com
353    
354     scope one
355     </pre>
356    
357     <p>
358 swift 1.37 Next, copy over the (OpenLDAP) <path>ldap.conf</path> file from the server to
359 swift 1.27 the client so the clients are aware of the LDAP environment:
360     </p>
361    
362     <pre caption="Copying over the OpenLDAP ldap.conf">
363     <comment>(Substitute ldap-server with your LDAP server name)</comment>
364     # <i>scp ldap-server:/etc/openldap/ldap.conf /etc/openldap</i>
365     </pre>
366    
367     <p>
368 swift 1.1 Finally, configure your clients so that they check the LDAP for system
369     accounts:
370     </p>
371    
372     <pre caption="/etc/nsswitch.conf">
373     passwd: files ldap
374     group: files ldap
375 swift 1.3 shadow: files ldap
376 swift 1.1 </pre>
377    
378     <p>
379     To test the changes, type:
380     </p>
381    
382     <pre caption="Testing LDAP Auth">
383     # <i>getent passwd|grep 0:0</i>
384    
385 neysx 1.23 <comment>(You should get two entries back:)</comment>
386 swift 1.37 root:x:0:0:root:/root:/bin/bash
387 swift 1.1 root:x:0:0:root:/root:/bin/bash
388     </pre>
389    
390     <p>
391     If you noticed one of the lines you pasted into your <path>/etc/ldap.conf</path>
392 swift 1.37 was commented out (the <c>rootbinddn</c> line): you don't need it unless you
393     want to change a user's password as superuser. In this case you need to echo
394     the root password to <path>/etc/ldap.secret</path> in plaintext. This is
395     <brite>DANGEROUS</brite> and should be chmoded to 600. What I do is keep that
396     file blank and when I need to change someones password thats both in the ldap
397     and <path>/etc/passwd</path> I put the pass in there for 10 seconds while I
398 swift 1.1 change it and remove it when I'm done.
399     </p>
400    
401     </body>
402     </section>
403 swift 1.20 </chapter>
404 swift 1.1
405 swift 1.20 <chapter>
406     <title>LDAP Server Security Settings</title>
407 swift 1.1 <section>
408     <title>OpenLDAP permissions</title>
409     <body>
410    
411     <p>
412     If we take a look at <path>/etc/openldap/slapd.conf</path> you'll see
413     that you can specify the ACLs (permissions if you like) of what data
414     users can read and/or write:
415     </p>
416    
417     <pre caption="/etc/openldap/slapd.conf">
418     access to *
419 nightmorph 1.40 by dn="uid=root,ou=People,dc=genfic,dc=com" write
420 swift 1.1 by users read
421     by anonymous auth
422 swift 1.15
423 swift 1.8 access to attrs=userPassword,gecos,description,loginShell
424     by self write
425 swift 1.1 </pre>
426    
427     <p>
428 swift 1.37 This gives you access to everything a user should be able to change. If it's
429     your information, then you got write access to it; if it's another user their
430     information then you can read it; anonymous people can send a login/pass to get
431     logged in. There are four levels, ranking them from lowest to greatest: <c>auth
432 swift 1.8 search read write</c>.
433 swift 1.1 </p>
434    
435     <p>
436     The next ACL is a bit more secure as it blocks normal users to read
437     other people their shadowed password:
438     </p>
439    
440     <pre caption="/etc/openldap/slapd.conf">
441 swift 1.22 access to attrs="userPassword"
442 nightmorph 1.40 by dn="uid=root,ou=People,dc=genfic,dc=com" write
443 swift 1.15 by dn="uid=John,ou=People,dc=genfic,dc=com" write
444 swift 1.1 by anonymous auth
445     by self write
446 swift 1.15 by * none
447 swift 1.37
448 swift 1.1 access to *
449     by dn="uid=root,ou=People,dc=genfic,dc=com" write
450 nightmorph 1.40 by dn="uid=John,ou=People,dc=genfic,dc=com" write
451 fox2mike 1.30 by * search
452 swift 1.1 </pre>
453    
454     <p>
455     This example gives root and John access to read/write/search
456 swift 1.37 for everything in the the tree below <path>dc=genfic,dc=com</path>. This also
457     lets users change their own <path>userPassword</path>'s. As for the ending
458     statement everyone else just has a search ability meaning they can fill in a
459     search filter, but can't read the search results. Now you can have multiple
460     acls but the rule of the thumb is it processes from bottom up, so your
461 swift 1.1 toplevel should be the most restrictive ones.
462     </p>
463    
464     </body>
465     </section>
466     </chapter>
467    
468     <chapter>
469     <title>Working with OpenLDAP</title>
470     <section>
471     <title>Maintaining the directory</title>
472     <body>
473    
474     <p>
475 nightmorph 1.36 You can start using the directory to authenticate users in
476 nightmorph 1.43 apache/proftpd/qmail/samba. You can manage it with phpldapadmin, diradm,
477     jxplorer, or lat, which provide easy management interfaces.
478 swift 1.1 </p>
479    
480     </body>
481     </section>
482     </chapter>
483    
484     <chapter>
485     <title>Acknowledgements</title>
486     <section>
487     <body>
488    
489     <p>
490 swift 1.37 We would like to thank Matt Heler for lending us his box for the purpose of
491 swift 1.1 this guide. Thanks also go to the cool guys in #ldap @ irc.freenode.net
492     </p>
493    
494     </body>
495     </section>
496     </chapter>
497     </guide>

  ViewVC Help
Powered by ViewVC 1.1.20