docs/htmldocs/pam.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
   2 <html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter 20. PAM Configuration for Centrally Managed Authentication</title><link rel="stylesheet" href="samba.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.59.1"><link rel="home" href="index.html" title="SAMBA Project Documentation"><link rel="up" href="optional.html" title="Part III. Advanced Configuration"><link rel="previous" href="InterdomainTrusts.html" title="Chapter 19. Interdomain Trust Relationships"><link rel="next" href="VFS.html" title="Chapter 21. Stackable VFS modules"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter 20. PAM Configuration for Centrally Managed Authentication</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="InterdomainTrusts.html">Prev</a> </td><th width="60%" align="center">Part III. Advanced Configuration</th><td width="20%" align="right"> <a accesskey="n" href="VFS.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><h2 class="title"><a name="pam"></a>Chapter 20. PAM Configuration for Centrally Managed Authentication</h2></div><div><div class="author"><h3 class="author">John H. Terpstra</h3><div class="affiliation"><span class="orgname">Samba Team<br></span><div class="address"><p><tt>&lt;<a href="mailto:jht@samba.org">jht@samba.org</a>&gt;</tt></p></div></div></div></div><div><p class="pubdate"> (Jun 21 2001) </p></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><a href="pam.html#id2897853">Samba and PAM</a></dt><dd><dl><dt><a href="pam.html#id2898634">PAM Configuration in smb.conf</a></dt><dt><a href="pam.html#id2898691">Password Synchronisation using pam_smbpass.so</a></dt></dl></dd><dt><a href="pam.html#id2898943">Distributed Authentication</a></dt></dl></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="id2897853"></a>Samba and PAM</h2></div></div><p>
   3 A number of Unix systems (eg: Sun Solaris), as well as the
   4 xxxxBSD family and Linux, now utilize the Pluggable Authentication
   5 Modules (PAM) facility to provide all authentication,
   6 authorization and resource control services. Prior to the
   7 introduction of PAM, a decision to use an alternative to
   8 the system password database (<tt>/etc/passwd</tt>)
   9 would require the provision of alternatives for all programs that provide
  10 security services. Such a choice would involve provision of
  11 alternatives to such programs as: <b>login</b>,
  12 <b>passwd</b>, <b>chown</b>, etc.
  13 </p><p>
  14 PAM provides a mechanism that disconnects these security programs
  15 from the underlying authentication/authorization infrastructure.
  16 PAM is configured either through one file <tt>/etc/pam.conf</tt> (Solaris),
  17 or by editing individual files that are located in <tt>/etc/pam.d</tt>.
  18 </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
  19         If the PAM authentication module (loadable link library file) is located in the
  20         default location then it is not necessary to specify the path. In the case of
  21         Linux, the default location is <tt>/lib/security</tt>. If the module
  22         is located outside the default then the path must be specified as:
  23
  24         </p><pre class="programlisting">
  25         auth       required      /other_path/pam_strange_module.so
  26         </pre><p>
  27         </p></div><p>
  28 The following is an example <tt>/etc/pam.d/login</tt> configuration file.
  29 This example had all options been uncommented is probably not usable
  30 as it stacks many conditions before allowing successful completion
  31 of the login process. Essentially all conditions can be disabled
  32 by commenting them out except the calls to <tt>pam_pwdb.so</tt>.
  33 </p><pre class="programlisting">
  34         #%PAM-1.0
  35         # The PAM configuration file for the `login' service
  36         #
  37         auth            required        pam_securetty.so
  38         auth            required        pam_nologin.so
  39         # auth          required        pam_dialup.so
  40         # auth          optional        pam_mail.so
  41         auth            required        pam_pwdb.so shadow md5
  42         # account       requisite       pam_time.so
  43         account         required        pam_pwdb.so
  44         session         required        pam_pwdb.so
  45         # session       optional        pam_lastlog.so
  46         # password      required        pam_cracklib.so retry=3
  47         password        required        pam_pwdb.so shadow md5
  48 </pre><p>
  49 PAM allows use of replacable modules. Those available on a
  50 sample system include:
  51 </p><p><tt>$</tt><b><tt>/bin/ls /lib/security</tt></b>
  52 </p><pre class="programlisting">
  53         pam_access.so    pam_ftp.so          pam_limits.so
  54         pam_ncp_auth.so  pam_rhosts_auth.so  pam_stress.so
  55         pam_cracklib.so  pam_group.so        pam_listfile.so
  56         pam_nologin.so   pam_rootok.so       pam_tally.so
  57         pam_deny.so      pam_issue.so        pam_mail.so
  58         pam_permit.so    pam_securetty.so    pam_time.so
  59         pam_dialup.so    pam_lastlog.so      pam_mkhomedir.so
  60         pam_pwdb.so      pam_shells.so       pam_unix.so
  61         pam_env.so       pam_ldap.so         pam_motd.so
  62         pam_radius.so    pam_smbpass.so      pam_unix_acct.so
  63         pam_wheel.so     pam_unix_auth.so    pam_unix_passwd.so
  64         pam_userdb.so    pam_warn.so         pam_unix_session.so
  65 </pre><p>
  66 The following example for the login program replaces the use of
  67 the <tt>pam_pwdb.so</tt> module which uses the system
  68 password database (<tt>/etc/passwd</tt>,
  69 <tt>/etc/shadow</tt>, <tt>/etc/group</tt>) with
  70 the module <tt>pam_smbpass.so</tt> which uses the Samba
  71 database which contains the Microsoft MD4 encrypted password
  72 hashes. This database is stored in either
  73 <tt>/usr/local/samba/private/smbpasswd</tt>,
  74 <tt>/etc/samba/smbpasswd</tt>, or in
  75 <tt>/etc/samba.d/smbpasswd</tt>, depending on the
  76 Samba implementation for your Unix/Linux system. The
  77 <tt>pam_smbpass.so</tt> module is provided by
  78 Samba version 2.2.1 or later. It can be compiled by specifying the
  79 <b>--with-pam_smbpass</b> options when running Samba's
  80 <tt>configure</tt> script.  For more information
  81 on the <tt>pam_smbpass</tt> module, see the documentation
  82 in the <tt>source/pam_smbpass</tt> directory of the Samba
  83 source distribution.
  84 </p><pre class="programlisting">
  85         #%PAM-1.0
  86         # The PAM configuration file for the `login' service
  87         #
  88         auth            required        pam_smbpass.so nodelay
  89         account         required        pam_smbpass.so nodelay
  90         session         required        pam_smbpass.so nodelay
  91         password        required        pam_smbpass.so nodelay
  92 </pre><p>
  93 The following is the PAM configuration file for a particular
  94 Linux system. The default condition uses <tt>pam_pwdb.so</tt>.
  95 </p><pre class="programlisting">
  96         #%PAM-1.0
  97         # The PAM configuration file for the `samba' service
  98         #
  99         auth       required     pam_pwdb.so nullok nodelay shadow audit
 100         account    required     pam_pwdb.so audit nodelay
 101         session    required     pam_pwdb.so nodelay
 102         password   required     pam_pwdb.so shadow md5
 103 </pre><p>
 104 In the following example the decision has been made to use the
 105 smbpasswd database even for basic samba authentication. Such a
 106 decision could also be made for the passwd program and would
 107 thus allow the smbpasswd passwords to be changed using the passwd
 108 program.
 109 </p><pre class="programlisting">
 110         #%PAM-1.0
 111         # The PAM configuration file for the `samba' service
 112         #
 113         auth       required     pam_smbpass.so nodelay
 114         account    required     pam_pwdb.so audit nodelay
 115         session    required     pam_pwdb.so nodelay
 116         password   required     pam_smbpass.so nodelay smbconf=/etc/samba.d/smb.conf
 117 </pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>PAM allows stacking of authentication mechanisms. It is
 118 also possible to pass information obtained within one PAM module through
 119 to the next module in the PAM stack. Please refer to the documentation for
 120 your particular system implementation for details regarding the specific
 121 capabilities of PAM in this environment. Some Linux implmentations also
 122 provide the <tt>pam_stack.so</tt> module that allows all
 123 authentication to be configured in a single central file. The
 124 <tt>pam_stack.so</tt> method has some very devoted followers
 125 on the basis that it allows for easier administration. As with all issues in
 126 life though, every decision makes trade-offs, so you may want examine the
 127 PAM documentation for further helpful information.
 128 </p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="id2898634"></a>PAM Configuration in smb.conf</h3></div></div><p>
 129 There is an option in smb.conf called <a href="smb.conf.5.html#OBEYPAMRESTRICTIONS" target="_top">obey pam restrictions</a>.
 130 The following is from the on-line help for this option in SWAT;
 131 </p><p>
 132 When Samba is configured to enable PAM support (i.e.
 133 <tt>--with-pam</tt>), this parameter will
 134 control whether or not Samba should obey PAM's account
 135 and session management directives. The default behavior
 136 is to use PAM for clear text authentication only and to
 137 ignore any account or session management. Note that Samba always
 138 ignores PAM for authentication in the case of
 139 <a href="smb.conf.5.html#ENCRYPTPASSWORDS" target="_top">encrypt passwords = yes</a>.
 140 The reason is that PAM modules cannot support the challenge/response
 141 authentication mechanism needed in the presence of SMB
 142 password encryption.
 143 </p><p>Default: <b>obey pam restrictions = no</b></p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="id2898691"></a>Password Synchronisation using pam_smbpass.so</h3></div></div><p>
 144 pam_smbpass is a PAM module which can be used on conforming systems to
 145 keep the smbpasswd (Samba password) database in sync with the unix
 146 password file. PAM (Pluggable Authentication Modules) is an API supported
 147 under some Unices, such as Solaris, HPUX and Linux, that provides a
 148 generic interface to authentication mechanisms.
 149 </p><p>
 150 For more information on PAM, see http://ftp.kernel.org/pub/linux/libs/pam/
 151 </p><p>
 152 This module authenticates a local smbpasswd user database.  If you require
 153 support for authenticating against a remote SMB server, or if you're
 154 concerned about the presence of suid root binaries on your system, it is
 155 recommended that you use pam_winbind instead.
 156 </p><pre class="programlisting">
 157 Options recognized by this module are as follows:
 158
 159         debug           -       log more debugging info
 160         audit           -       like debug, but also logs unknown usernames
 161         use_first_pass  -       don't prompt the user for passwords;
 162                                 take them from PAM_ items instead
 163         try_first_pass  -       try to get the password from a previous
 164                                 PAM module, fall back to prompting the user
 165         use_authtok     -       like try_first_pass, but *fail* if the new
 166                                 PAM_AUTHTOK has not been previously set.
 167                                 (intended for stacking password modules only)
 168         not_set_pass    -       don't make passwords used by this module
 169                                 available to other modules.
 170         nodelay         -       don't insert ~1 second delays on authentication
 171                                 failure.
 172         nullok          -       null passwords are allowed.
 173         nonull          -       null passwords are not allowed. Used to
 174                                 override the Samba configuration.
 175         migrate         -       only meaningful in an &quot;auth&quot; context;
 176                                 used to update smbpasswd file with a
 177                                 password used for successful authentication.
 178         smbconf=&lt; file &gt;  -     specify an alternate path to the smb.conf
 179                                 file.
 180 </pre><pre class="programlisting">
 181 Thanks go to the following people:
 182
 183         * Andrew Morgan &lt; morgan@transmeta.com &gt;, for providing the Linux-PAM
 184         framework, without which none of this would have happened
 185
 186         * Christian Gafton &lt; gafton@redhat.com &gt; and Andrew Morgan again, for the
 187         pam_pwdb module upon which pam_smbpass was originally based
 188
 189         * Luke Leighton &lt; lkcl@switchboard.net &gt; for being receptive to the idea,
 190         and for the occasional good-natured complaint about the project's status
 191         that keep me working on it :)
 192
 193         * and of course, all the other members of the Samba team
 194         &lt;http://www.samba.org/samba/team.html&gt;, for creating a great product
 195         and for giving this project a purpose
 196
 197         ---------------------
 198         Stephen Langasek &lt; vorlon@netexpress.net &gt;
 199 </pre><p>
 200 The following are examples of the use of pam_smbpass.so in the format of Linux
 201 <tt>/etc/pam.d/</tt> files structure. Those wishing to implement this
 202 tool on other platforms will need to adapt this appropriately.
 203 </p><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="id2898803"></a>Password Synchonisation Configuration</h4></div></div><p>
 204 A sample PAM configuration that shows the use of pam_smbpass to make
 205 sure private/smbpasswd is kept in sync when /etc/passwd (/etc/shadow)
 206 is changed.  Useful when an expired password might be changed by an
 207 application (such as ssh).
 208 </p><pre class="programlisting">
 209         #%PAM-1.0
 210         # password-sync
 211         #
 212         auth       requisite        pam_nologin.so
 213         auth       required         pam_unix.so
 214         account    required         pam_unix.so
 215         password   requisite        pam_cracklib.so retry=3
 216         password   requisite        pam_unix.so shadow md5 use_authtok try_first_pass
 217         password   required         pam_smbpass.so nullok use_authtok try_first_pass
 218         session    required         pam_unix.so
 219 </pre></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="id2898838"></a>Password Migration Configuration</h4></div></div><p>
 220 A sample PAM configuration that shows the use of pam_smbpass to migrate
 221 from plaintext to encrypted passwords for Samba.  Unlike other methods,
 222 this can be used for users who have never connected to Samba shares:
 223 password migration takes place when users ftp in, login using ssh, pop
 224 their mail, etc.
 225 </p><pre class="programlisting">
 226         #%PAM-1.0
 227         # password-migration
 228         #
 229         auth       requisite        pam_nologin.so
 230         # pam_smbpass is called IFF pam_unix succeeds.
 231         auth       requisite        pam_unix.so
 232         auth       optional         pam_smbpass.so migrate
 233         account    required         pam_unix.so
 234         password   requisite        pam_cracklib.so retry=3
 235         password   requisite        pam_unix.so shadow md5 use_authtok try_first_pass
 236         password   optional         pam_smbpass.so nullok use_authtok try_first_pass
 237         session    required         pam_unix.so
 238 </pre></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="id2898875"></a>Mature Password Configuration</h4></div></div><p>
 239 A sample PAM configuration for a 'mature' smbpasswd installation.
 240 private/smbpasswd is fully populated, and we consider it an error if
 241 the smbpasswd doesn't exist or doesn't match the Unix password.
 242 </p><pre class="programlisting">
 243         #%PAM-1.0
 244         # password-mature
 245         #
 246         auth       requisite        pam_nologin.so
 247         auth       required         pam_unix.so
 248         account    required         pam_unix.so
 249         password   requisite        pam_cracklib.so retry=3
 250         password   requisite        pam_unix.so shadow md5 use_authtok try_first_pass
 251         password   required         pam_smbpass.so use_authtok use_first_pass
 252         session    required         pam_unix.so
 253 </pre></div><div class="sect3" lang="en"><div class="titlepage"><div><h4 class="title"><a name="id2898908"></a>Kerberos Password Integration Configuration</h4></div></div><p>
 254 A sample PAM configuration that shows pam_smbpass used together with
 255 pam_krb5.  This could be useful on a Samba PDC that is also a member of
 256 a Kerberos realm.
 257 </p><pre class="programlisting">
 258         #%PAM-1.0
 259         # kdc-pdc
 260         #
 261         auth       requisite        pam_nologin.so
 262         auth       requisite        pam_krb5.so
 263         auth       optional         pam_smbpass.so migrate
 264         account    required         pam_krb5.so
 265         password   requisite        pam_cracklib.so retry=3
 266         password   optional         pam_smbpass.so nullok use_authtok try_first_pass
 267         password   required         pam_krb5.so use_authtok try_first_pass
 268         session    required         pam_krb5.so
 269 </pre></div></div></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="id2898943"></a>Distributed Authentication</h2></div></div><p>
 270 The astute administrator will realize from this that the
 271 combination of <tt>pam_smbpass.so</tt>,
 272 <b>winbindd</b>, and a distributed
 273 passdb backend, such as ldap, will allow the establishment of a
 274 centrally managed, distributed
 275 user/password database that can also be used by all
 276 PAM (eg: Linux) aware programs and applications. This arrangement
 277 can have particularly potent advantages compared with the
 278 use of Microsoft Active Directory Service (ADS) in so far as
 279 reduction of wide area network authentication traffic.
 280 </p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="InterdomainTrusts.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="optional.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="VFS.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 19. Interdomain Trust Relationships </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 21. Stackable VFS modules</td></tr></table></div></body></html>