4b5179acc7cd331da31417f8dc6257fcb4816040
[samba.git] / docs / docbook / projdoc / PAM-Authentication-And-Samba.xml
1 <chapter id="pam">
2 <chapterinfo>
3         &author.jht;
4     <pubdate> (Jun 21 2001) </pubdate>
5 </chapterinfo>
6  
7 <title>PAM Configuration for Centrally Managed Authentication</title>
8
9 <sect1>
10 <title>Samba and PAM</title>
11
12 <para>
13 A number of Unix systems (eg: Sun Solaris), as well as the 
14 xxxxBSD family and Linux, now utilize the Pluggable Authentication 
15 Modules (PAM) facility to provide all authentication, 
16 authorization and resource control services. Prior to the 
17 introduction of PAM, a decision to use an alternative to 
18 the system password database (<filename>/etc/passwd</filename>) 
19 would require the provision of alternatives for all programs that provide 
20 security services. Such a choice would involve provision of 
21 alternatives to such programs as: <command>login</command>, 
22 <command>passwd</command>, <command>chown</command>, etc.
23 </para>
24
25 <para>
26 PAM provides a mechanism that disconnects these security programs 
27 from the underlying authentication/authorization infrastructure.
28 PAM is configured either through one file <filename>/etc/pam.conf</filename> (Solaris), 
29 or by editing individual files that are located in <filename>/etc/pam.d</filename>.
30 </para>
31
32 <note>
33         <para>
34         If the PAM authentication module (loadable link library file) is located in the
35         default location then it is not necessary to specify the path. In the case of
36         Linux, the default location is <filename>/lib/security</filename>. If the module
37         is located outside the default then the path must be specified as:
38         
39         <programlisting>
40         auth       required      /other_path/pam_strange_module.so
41         </programlisting>
42         </para>
43 </note>
44
45 <para>
46 The following is an example <filename>/etc/pam.d/login</filename> configuration file. 
47 This example had all options been uncommented is probably not usable 
48 as it stacks many conditions before allowing successful completion 
49 of the login process. Essentially all conditions can be disabled 
50 by commenting them out except the calls to <filename>pam_pwdb.so</filename>.
51 </para>
52
53 <para><programlisting>
54         #%PAM-1.0
55         # The PAM configuration file for the `login' service
56         #
57         auth            required        pam_securetty.so
58         auth            required        pam_nologin.so
59         # auth          required        pam_dialup.so
60         # auth          optional        pam_mail.so
61         auth            required        pam_pwdb.so shadow md5
62         # account       requisite       pam_time.so
63         account         required        pam_pwdb.so
64         session         required        pam_pwdb.so
65         # session       optional        pam_lastlog.so
66         # password      required        pam_cracklib.so retry=3
67         password        required        pam_pwdb.so shadow md5
68 </programlisting></para>
69
70 <para>
71 PAM allows use of replacable modules. Those available on a 
72 sample system include:
73 </para>
74
75 <para><prompt>$</prompt><userinput>/bin/ls /lib/security</userinput>
76 <programlisting>
77         pam_access.so    pam_ftp.so          pam_limits.so     
78         pam_ncp_auth.so  pam_rhosts_auth.so  pam_stress.so     
79         pam_cracklib.so  pam_group.so        pam_listfile.so   
80         pam_nologin.so   pam_rootok.so       pam_tally.so      
81         pam_deny.so      pam_issue.so        pam_mail.so       
82         pam_permit.so    pam_securetty.so    pam_time.so       
83         pam_dialup.so    pam_lastlog.so      pam_mkhomedir.so  
84         pam_pwdb.so      pam_shells.so       pam_unix.so       
85         pam_env.so       pam_ldap.so         pam_motd.so       
86         pam_radius.so    pam_smbpass.so      pam_unix_acct.so  
87         pam_wheel.so     pam_unix_auth.so    pam_unix_passwd.so
88         pam_userdb.so    pam_warn.so         pam_unix_session.so
89 </programlisting></para>
90
91 <para>
92 The following example for the login program replaces the use of 
93 the <filename>pam_pwdb.so</filename> module which uses the system 
94 password database (<filename>/etc/passwd</filename>,
95 <filename>/etc/shadow</filename>, <filename>/etc/group</filename>) with 
96 the module <filename>pam_smbpass.so</filename> which uses the Samba 
97 database which contains the Microsoft MD4 encrypted password 
98 hashes. This database is stored in either 
99 <filename>/usr/local/samba/private/smbpasswd</filename>, 
100 <filename>/etc/samba/smbpasswd</filename>, or in 
101 <filename>/etc/samba.d/smbpasswd</filename>, depending on the 
102 Samba implementation for your Unix/Linux system. The 
103 <filename>pam_smbpass.so</filename> module is provided by 
104 Samba version 2.2.1 or later. It can be compiled by specifying the 
105 <command>--with-pam_smbpass</command> options when running Samba's
106 <filename>configure</filename> script.  For more information
107 on the <filename>pam_smbpass</filename> module, see the documentation
108 in the <filename>source/pam_smbpass</filename> directory of the Samba 
109 source distribution.
110 </para>
111
112 <para><programlisting>
113         #%PAM-1.0
114         # The PAM configuration file for the `login' service
115         #
116         auth            required        pam_smbpass.so nodelay
117         account         required        pam_smbpass.so nodelay
118         session         required        pam_smbpass.so nodelay
119         password        required        pam_smbpass.so nodelay
120 </programlisting></para>
121
122 <para>
123 The following is the PAM configuration file for a particular 
124 Linux system. The default condition uses <filename>pam_pwdb.so</filename>.
125 </para>
126
127 <para><programlisting>
128         #%PAM-1.0
129         # The PAM configuration file for the `samba' service
130         #
131         auth       required     pam_pwdb.so nullok nodelay shadow audit
132         account    required     pam_pwdb.so audit nodelay
133         session    required     pam_pwdb.so nodelay
134         password   required     pam_pwdb.so shadow md5
135 </programlisting></para>
136
137 <para>
138 In the following example the decision has been made to use the 
139 smbpasswd database even for basic samba authentication. Such a 
140 decision could also be made for the passwd program and would 
141 thus allow the smbpasswd passwords to be changed using the passwd 
142 program.
143 </para>
144
145 <para><programlisting>
146         #%PAM-1.0
147         # The PAM configuration file for the `samba' service
148         #
149         auth       required     pam_smbpass.so nodelay
150         account    required     pam_pwdb.so audit nodelay
151         session    required     pam_pwdb.so nodelay
152         password   required     pam_smbpass.so nodelay smbconf=/etc/samba.d/smb.conf
153 </programlisting></para>
154
155 <note><para>PAM allows stacking of authentication mechanisms. It is 
156 also possible to pass information obtained within one PAM module through 
157 to the next module in the PAM stack. Please refer to the documentation for 
158 your particular system implementation for details regarding the specific 
159 capabilities of PAM in this environment. Some Linux implmentations also 
160 provide the <filename>pam_stack.so</filename> module that allows all 
161 authentication to be configured in a single central file. The 
162 <filename>pam_stack.so</filename> method has some very devoted followers 
163 on the basis that it allows for easier administration. As with all issues in 
164 life though, every decision makes trade-offs, so you may want examine the 
165 PAM documentation for further helpful information.
166 </para></note>
167
168 <sect2>
169 <title>PAM Configuration in smb.conf</title>
170
171 <para>
172 There is an option in smb.conf called <ulink 
173 url="smb.conf.5.html#OBEYPAMRESTRICTIONS">obey pam restrictions</ulink>. 
174 The following is from the on-line help for this option in SWAT;
175 </para>
176
177 <para>
178 When Samba is configured to enable PAM support (i.e. 
179 <constant>--with-pam</constant>), this parameter will 
180 control whether or not Samba should obey PAM's account 
181 and session management directives. The default behavior 
182 is to use PAM for clear text authentication only and to 
183 ignore any account or session management. Note that Samba always 
184 ignores PAM for authentication in the case of 
185 <ulink url="smb.conf.5.html#ENCRYPTPASSWORDS">encrypt passwords = yes</ulink>. 
186 The reason is that PAM modules cannot support the challenge/response 
187 authentication mechanism needed in the presence of SMB 
188 password encryption. 
189 </para>
190
191 <para>Default: <command>obey pam restrictions = no</command></para>
192
193 </sect2>
194
195 <sect2>
196 <title>Password Synchronisation using pam_smbpass.so</title>
197
198 <para>
199 pam_smbpass is a PAM module which can be used on conforming systems to
200 keep the smbpasswd (Samba password) database in sync with the unix
201 password file. PAM (Pluggable Authentication Modules) is an API supported
202 under some Unices, such as Solaris, HPUX and Linux, that provides a
203 generic interface to authentication mechanisms.
204 </para>
205
206 <para>
207 For more information on PAM, see http://ftp.kernel.org/pub/linux/libs/pam/
208 </para>
209
210 <para>
211 This module authenticates a local smbpasswd user database.  If you require
212 support for authenticating against a remote SMB server, or if you're
213 concerned about the presence of suid root binaries on your system, it is
214 recommended that you use pam_winbind instead.
215 </para>
216
217 <para><programlisting>
218 Options recognized by this module are as follows:
219
220         debug           -       log more debugging info
221         audit           -       like debug, but also logs unknown usernames
222         use_first_pass  -       don't prompt the user for passwords;
223                                 take them from PAM_ items instead
224         try_first_pass  -       try to get the password from a previous
225                                 PAM module, fall back to prompting the user
226         use_authtok     -       like try_first_pass, but *fail* if the new
227                                 PAM_AUTHTOK has not been previously set.
228                                 (intended for stacking password modules only)
229         not_set_pass    -       don't make passwords used by this module
230                                 available to other modules.
231         nodelay         -       don't insert ~1 second delays on authentication
232                                 failure.
233         nullok          -       null passwords are allowed.
234         nonull          -       null passwords are not allowed. Used to
235                                 override the Samba configuration.
236         migrate         -       only meaningful in an "auth" context;
237                                 used to update smbpasswd file with a
238                                 password used for successful authentication.
239         smbconf=&lt; file &gt;  -     specify an alternate path to the smb.conf
240                                 file.
241 </programlisting></para>
242
243 <para><programlisting>
244 Thanks go to the following people:
245
246         * Andrew Morgan &lt; morgan@transmeta.com &gt;, for providing the Linux-PAM
247         framework, without which none of this would have happened
248
249         * Christian Gafton &lt; gafton@redhat.com &gt; and Andrew Morgan again, for the
250         pam_pwdb module upon which pam_smbpass was originally based
251
252         * Luke Leighton &lt; lkcl@switchboard.net &gt; for being receptive to the idea,
253         and for the occasional good-natured complaint about the project's status
254         that keep me working on it :)
255
256         * and of course, all the other members of the Samba team
257         &lt;http://www.samba.org/samba/team.html&gt;, for creating a great product
258         and for giving this project a purpose
259
260         ---------------------
261         Stephen Langasek &lt; vorlon@netexpress.net &gt;
262 </programlisting></para>
263
264 <para>
265 The following are examples of the use of pam_smbpass.so in the format of Linux
266 <filename>/etc/pam.d/</filename> files structure. Those wishing to implement this
267 tool on other platforms will need to adapt this appropriately.
268 </para>
269
270 <sect3>
271 <title>Password Synchonisation Configuration</title>
272
273 <para>
274 A sample PAM configuration that shows the use of pam_smbpass to make
275 sure private/smbpasswd is kept in sync when /etc/passwd (/etc/shadow)
276 is changed.  Useful when an expired password might be changed by an
277 application (such as ssh).
278 </para>
279
280 <para><programlisting>
281         #%PAM-1.0
282         # password-sync
283         #
284         auth       requisite        pam_nologin.so
285         auth       required         pam_unix.so
286         account    required         pam_unix.so
287         password   requisite        pam_cracklib.so retry=3
288         password   requisite        pam_unix.so shadow md5 use_authtok try_first_pass
289         password   required         pam_smbpass.so nullok use_authtok try_first_pass
290         session    required         pam_unix.so
291 </programlisting></para>
292 </sect3>
293
294 <sect3>
295 <title>Password Migration Configuration</title>
296
297 <para>
298 A sample PAM configuration that shows the use of pam_smbpass to migrate
299 from plaintext to encrypted passwords for Samba.  Unlike other methods,
300 this can be used for users who have never connected to Samba shares:
301 password migration takes place when users ftp in, login using ssh, pop
302 their mail, etc.
303 </para>
304
305 <para><programlisting>
306         #%PAM-1.0
307         # password-migration
308         #
309         auth       requisite        pam_nologin.so
310         # pam_smbpass is called IFF pam_unix succeeds.
311         auth       requisite        pam_unix.so
312         auth       optional         pam_smbpass.so migrate
313         account    required         pam_unix.so
314         password   requisite        pam_cracklib.so retry=3
315         password   requisite        pam_unix.so shadow md5 use_authtok try_first_pass
316         password   optional         pam_smbpass.so nullok use_authtok try_first_pass
317         session    required         pam_unix.so
318 </programlisting></para>
319 </sect3>
320
321 <sect3>
322 <title>Mature Password Configuration</title>
323
324 <para>
325 A sample PAM configuration for a 'mature' smbpasswd installation.
326 private/smbpasswd is fully populated, and we consider it an error if
327 the smbpasswd doesn't exist or doesn't match the Unix password.
328 </para>
329
330 <para><programlisting>
331         #%PAM-1.0
332         # password-mature
333         #
334         auth       requisite        pam_nologin.so
335         auth       required         pam_unix.so
336         account    required         pam_unix.so
337         password   requisite        pam_cracklib.so retry=3
338         password   requisite        pam_unix.so shadow md5 use_authtok try_first_pass
339         password   required         pam_smbpass.so use_authtok use_first_pass
340         session    required         pam_unix.so
341 </programlisting></para>
342 </sect3>
343
344 <sect3>
345 <title>Kerberos Password Integration Configuration</title>
346
347 <para>
348 A sample PAM configuration that shows pam_smbpass used together with
349 pam_krb5.  This could be useful on a Samba PDC that is also a member of
350 a Kerberos realm.
351 </para>
352
353 <para><programlisting>
354         #%PAM-1.0
355         # kdc-pdc
356         #
357         auth       requisite        pam_nologin.so
358         auth       requisite        pam_krb5.so
359         auth       optional         pam_smbpass.so migrate
360         account    required         pam_krb5.so
361         password   requisite        pam_cracklib.so retry=3
362         password   optional         pam_smbpass.so nullok use_authtok try_first_pass
363         password   required         pam_krb5.so use_authtok try_first_pass
364         session    required         pam_krb5.so
365 </programlisting></para>
366 </sect3>
367
368 </sect2>
369 </sect1>
370
371 <sect1>
372 <title>Distributed Authentication</title>
373
374 <para>
375 The astute administrator will realize from this that the 
376 combination of <filename>pam_smbpass.so</filename>, 
377 <command>winbindd</command>, and a distributed 
378 passdb backend, such as ldap, will allow the establishment of a
379 centrally managed, distributed 
380 user/password database that can also be used by all 
381 PAM (eg: Linux) aware programs and applications. This arrangement 
382 can have particularly potent advantages compared with the 
383 use of Microsoft Active Directory Service (ADS) in so far as 
384 reduction of wide area network authentication traffic.
385 </para>
386
387 </sect1>
388
389 </chapter>