docs/docbook/projdoc/PAM-Authentication-And-Samba.sgml

   1 <chapter id="pam">
   2
   3
   4 <chapterinfo>
   5         <author>
   6                 <firstname>John</firstname><surname>Terpstra</surname>
   7                 <affiliation>
   8                         <orgname>Samba Team</orgname>
   9                         <address>
  10                         <email>jht@samba.org</email>
  11                         </address>
  12                 </affiliation>
  13         </author>
  14
  15
  16         <pubdate> (Jun 21 2001) </pubdate>
  17 </chapterinfo>
  18
  19 <title>Configuring PAM for distributed but centrally
  20 managed authentication</title>
  21
  22 <sect1>
  23 <title>Samba and PAM</title>
  24
  25 <para>
  26 A number of Unix systems (eg: Sun Solaris), as well as the
  27 xxxxBSD family and Linux, now utilize the Pluggable Authentication
  28 Modules (PAM) facility to provide all authentication,
  29 authorization and resource control services. Prior to the
  30 introduction of PAM, a decision to use an alternative to
  31 the system password database (<filename>/etc/passwd</filename>)
  32 would require the provision of alternatives for all programs that provide
  33 security services. Such a choice would involve provision of
  34 alternatives to such programs as: <command>login</command>,
  35 <command>passwd</command>, <command>chown</command>, etc.
  36 </para>
  37
  38 <para>
  39 PAM provides a mechanism that disconnects these security programs
  40 from the underlying authentication/authorization infrastructure.
  41 PAM is configured either through one file <filename>/etc/pam.conf</filename> (Solaris),
  42 or by editing individual files that are located in <filename>/etc/pam.d</filename>.
  43 </para>
  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><programlisting>
  76 $ /bin/ls /lib/security
  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     /lib/security/pam_pwdb.so nullok nodelay shadow audit
 132 account    required     /lib/security/pam_pwdb.so audit nodelay
 133 session    required     /lib/security/pam_pwdb.so nodelay
 134 password   required     /lib/security/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     /lib/security/pam_smbpass.so nodelay
 150 account    required     /lib/security/pam_pwdb.so audit nodelay
 151 session    required     /lib/security/pam_pwdb.so nodelay
 152 password   required     /lib/security/pam_smbpass.so nodelay smbconf=/etc/samba.d/smb.conf
 153 </programlisting></para>
 154
 155 <para>
 156 Note: PAM allows stacking of authentication mechanisms. It is
 157 also possible to pass information obtained within one PAM module through
 158 to the next module in the PAM stack. Please refer to the documentation for
 159 your particular system implementation for details regarding the specific
 160 capabilities of PAM in this environment. Some Linux implmentations also
 161 provide the <filename>pam_stack.so</filename> module that allows all
 162 authentication to be configured in a single central file. The
 163 <filename>pam_stack.so</filename> method has some very devoted followers
 164 on the basis that it allows for easier administration. As with all issues in
 165 life though, every decision makes trade-offs, so you may want examine the
 166 PAM documentation for further helpful information.
 167 </para>
 168
 169 </sect1>
 170
 171 <sect1>
 172 <title>Distributed Authentication</title>
 173
 174 <para>
 175 The astute administrator will realize from this that the
 176 combination of <filename>pam_smbpass.so</filename>,
 177 <command>winbindd</command>, and <command>rsync</command> (see
 178 <ulink url="http://rsync.samba.org/">http://rsync.samba.org/</ulink>)
 179 will allow the establishment of a centrally managed, distributed
 180 user/password database that can also be used by all
 181 PAM (eg: Linux) aware programs and applications. This arrangement
 182 can have particularly potent advantages compared with the
 183 use of Microsoft Active Directory Service (ADS) in so far as
 184 reduction of wide area network authentication traffic.
 185 </para>
 186
 187 </sect1>
 188
 189 <sect1>
 190 <title>PAM Configuration in smb.conf</title>
 191
 192 <para>
 193 There is an option in smb.conf called <ulink
 194 url="smb.conf.5.html#OBEYPAMRESTRICTIONS">obey pam restrictions</ulink>.
 195 The following is from the on-line help for this option in SWAT;
 196 </para>
 197
 198 <para>
 199 When Samba 2.2 is configure to enable PAM support (i.e.
 200 <constant>--with-pam</constant>), this parameter will
 201 control whether or not Samba should obey PAM's account
 202 and session management directives. The default behavior
 203 is to use PAM for clear text authentication only and to
 204 ignore any account or session management. Note that Samba always
 205 ignores PAM for authentication in the case of
 206 <ulink url="smb.conf.5.html#ENCRYPTPASSWORDS">encrypt passwords = yes</ulink>.
 207 The reason is that PAM modules cannot support the challenge/response
 208 authentication mechanism needed in the presence of SMB
 209 password encryption.
 210 </para>
 211
 212 <para>Default: <command>obey pam restrictions = no</command></para>
 213
 214 </sect1>
 215 </chapter>