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

   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>