granicus.if.org Git - apache-authnz-external/blob - mod_authnz_external/README

   1                    Mod_Authnz_External version 3.3.x
   2
   3      Original Coder: Nathan Neulinger <nneul@umr.edu>
   4 Previous Maintainer: Tyler Allison    <allison@nas.nasa.gov>
   5  Current Maintainer: Jan Wolter       http://www.unixpapa.com
   6     Apache 2.0 Port: Dave Woolaway    <dave@watersheep.org>
   7                      Sven Koch        <haegar@sdinet.de>
   8     Apache 2.2 Port: Jan Wolter       http://www.unixpapa.com
   9
  10 Caution:
  11 --------
  12
  13 Mod_Auth_External can be used to quickly construct secure, reliable
  14 authentication systems.  It can also be mis-used to quickly open gaping
  15 holes in your security.  Read the documentation, and use with extreme
  16 caution.
  17
  18 Versions:
  19 ---------
  20
  21 Mod_authnz_external version 3.3.x is designed for use with Apache version
  22 2.4.x.  It will not work with Apache 2.2 or 2.0.  For older versions of
  23 Apache you will need older branches of mod_authnz_external:
  24
  25      Apache 1.3   mod_auth_external-2.1.x
  26      Apache 2.0   mod_auth_external-2.2.x
  27      Apache 2.2   mod_authnz_external-3.1.x or mod_authnz_external-3.2.x
  28      Apache 2.4   mod_authnz_external-3.3.x
  29
  30 This module was developed from "mod_auth_external".  It has been restructured
  31 to fit into the authn/authz structure introduce in Apache 2.1.  It can be used
  32 in any application where mod_auth_external was previously used.  No changes
  33 will be needed to the external authentication programs, but the exact Apache
  34 configuration commands needed will be different.  It is possible to use the
  35 old "mod_auth_external-2.2" with Apache-2.2, but mod_authnz_external is
  36 preferable.  If you are upgrading from "mod_auth_external" to
  37 "mod_authnz_external" then read the file "UPGRADE" for advice.
  38
  39 Introduction:
  40 -------------
  41
  42 Mod_Authnz_External is an Apache module used for authentication.  The Apache
  43 HTTP Daemon can be configured to require users to supply logins and passwords
  44 before accessing pages in some directories.  Authentication is the process
  45 of checking if the password given is correct for a user.  Apache has
  46 standard modules for authenticating out of several different kinds of
  47 databases.  Mod_Authnz_External is a flexible tool for creating authentication
  48 systems based on other databases.
  49
  50 Mod_Authnz_External can be used in either of two somewhat divergent ways:
  51
  52  External Authentication:
  53
  54     When a user supplies a login and password, mod_authnz_external runs a
  55     program you write, passing it the login and password.  Your program
  56     does whatever checking and logging it needs to, and then returns a
  57     Accept/Reject flag to Apache.
  58
  59     This is slower than doing the authentication internally because it
  60     has the overhead of launching an external program for each authentication.
  61     However, there are at least two situations where it is very useful:
  62
  63       - Rapid prototyping.  The external authentication program can be
  64         a shell script or perl program.  It can be written without knowing
  65         much about building Apache modules.  Bugs in it will not endanger
  66         the overall integrity of the Apache server.  Later, as performance
  67         becomes more of an issue, you can write a custom Apache module to
  68         do the job more efficiently (perhaps using the HARDCODE option below).
  69
  70       - Access restrictions.  There are situations where you do not want to
  71         make your user database readable to the user-id that Apache runs
  72         under.  In these cases the external authentication program can be
  73         an suid program that has access to databases Apache cannot access.
  74         For example, if you want to authentication out of a Unix shadow
  75         password database, and you aren't foolish enough to run Apache
  76         as root, a carefully written suid-root external authentication
  77         program can do the job for you.
  78
  79     Pwauth, an external authentication program for securely authenticating
  80     out of a Unix shadow password database available from
  81     http://www.unixpapa.com/pwauth/ .
  82
  83  Hardcoded Authentication:
  84
  85     Some hooks have been inserted into mod_authnz_external to make it easy
  86     to replace the call to the external authentication program with a
  87     call to a hardcoded internal authentication routine that you write.
  88
  89     This is sort of a half-way measure to just writing your own Apache
  90     module from scratch, allowing you to use some of the logic from
  91     mod_authnz_external.
  92
  93     Example functions for authenticating out of a RADIUS server or Sybase
  94     database are included in this distribution.
  95
  96 Compatibility:
  97 --------------
  98
  99 The current version of mod_authnz_external is designed for use with Apache 2.2.
 100 It will not work with older versions of Apache.
 101
 102 Mod_authnz_external has been tested on a wide variety of Unix platforms.  In
 103 theory versions after 3.2.0 should work on any non-Unix platforms supported
 104 by Apache, but it has been tested only under Unix.
 105
 106 Mod_authnz_external is also compatible with authenticators using the
 107 checkpassword interface.  See http://cr.yp.to/checkpwd.html for more
 108 information.
 109
 110 Authn / Authz
 111 -------------
 112
 113 Users of mod_authnz_external may find it helpful understand a bit more of
 114 it's internal structure.  It is actually best thought of as two functionally
 115 separate modules, mod_authn_external and mod_authz_external, which have
 116 combined into a single module simply because they share a lot of code.
 117 In any particular application, you may only be using one of these two
 118 modules, or you may be using both.
 119
 120 The mod_authn_external part is an authentication provider for the
 121 mod_auth_basic module.  Mod_auth_basic handles all the negotiations with
 122 the browser, while all mod_authn_external does is check if a password
 123 submitted by the user is correct (which it does by running an external
 124 program to perform the check).
 125
 126 The mod_authz_external part does access control.  It has no relation
 127 to mod_auth_basic.  It comes into play after authentication is complete,
 128 when a "Require group" or "Require file-group" directive is given.  It
 129 checks if the authenticated user is in the list of required groups (which
 130 it does by running an external program to perform the check).
 131
 132 Digest Authentication
 133 ---------------------
 134
 135 The new authentication structure introduced in Apache 2.1 makes it much
 136 easier for modules like this one to support digest authentication as an
 137 alternative to basic authentication.  Mod_Authnz_External, however, does
 138 not yet support digest authentication.
 139
 140 I hope to support this in the future, but it really isn't a very attractive
 141 alternative and I don't expect many people will want to use it.  It will
 142 not be possible to use the same external authentication programs that are
 143 used for basic authentication - they would have to be rewritten.  It will
 144 only work if the database being accessed by the external program either has
 145 passwords in plaintext, or has them encrypted in a very specific way.  This
 146 means it could not be used for unix password database authentication or with
 147 most other password databases not specifically designed for this application.
 148 And password databases specifically designed for this application might as
 149 well be designed in a format where they could be accessed by mod_authn_file
 150 or mod_authn_dbm.
 151
 152 Security Considerations:
 153 ------------------------
 154
 155 By default, mod_authnz_external passes the user's login and password to the
 156 external authentication program by sending them through a pipe.  This is
 157 very secure.
 158
 159 In older versions of mod_auth_external, the login and password were by
 160 default passed in environment variables called USER and PASS.  This is
 161 still an option, but we do NOT recommend using option.
 162
 163 On some versions of Unix (including SunOS and IRIX) any user logged onto
 164 the server can see these values by doing a "ps -e" command.  This would
 165 obviously be a problem if there are ever untrusted users on your server.
 166 Other versions of Unix (including Linux) restrict "ps -e" so you can only
 167 see your own processes, but this may still be a problem if untrusted people
 168 can put CGI programs on your server, since those may run as the same user
 169 as your authentication program does.  Some versions of Unix don't seem to
 170 have a "ps -e" command at all, but even then it is best to be careful.
 171 Although the default "ps" command on Solaris won't display environment
 172 variables, the backwards compatible "/usr/ucb/ps" command does.  Are you
 173 sure there isn't and won't be an old-style ps command installed on your
 174 system?
 175
 176 Use of this module requires development of an external authentication program
 177 or a hardcoded internal function.  These are typically very simple programs,
 178 but there are more ways to screw up your security by doing them badly than
 179 we could possibly list.  See the file AUTHENTICATORS for more information
 180 on implementing authenticators.
 181
 182 Example External Authentication Routines in this Distribution:
 183 --------------------------------------------------------------
 184
 185  test/
 186     Several small dummy external authentication programs written in Perl.
 187     This are meant only for testing of mod_authnz_external.  They accept
 188     any user whose password and login name are identical.  They write
 189     lots of debugging info to the error_log file.
 190
 191     Author and Maintainer:  Jan Wolter <janc@cyberspace.org>
 192
 193  mysql/
 194     A Perl program for authenticating out of a MySQL database.  This is
 195     written in Perl using the DBI interface, so it could be trivially adapted
 196     to work with any other SQL database server that has a DBI interface
 197     (that is to say all of them).
 198
 199     Author and Maintainer:  Anders Nordby <anders@fix.no>
 200                             http://anders.fix.no/software/#unix
 201
 202 The "pwauth" authenticator for unix shadow password files or PAM which
 203 was previously included in this distribution is now in a separate package,
 204 available from http://www.unixpapa.com/pwauth/.
 205
 206 Example Hardcoded Internal Authentication Routines in this Distribution:
 207 ------------------------------------------------------------------------
 208
 209  sybase/
 210     A function that queries a sybase database and compares the passwords
 211     for said user.
 212
 213     Author:  <br@ota.fr.socgen.com>
 214     Unmaintained.
 215
 216 The radius client previously distributed with mod_auth_external has been
 217 removed from the distribution because of possible license problems.  Get it
 218 from http://unixpapa.com/software/mae_radius.tar.gz if you want it, but
 219 mod_auth_radius is a better choice.
 220
 221 If you have programs or functions you have coded and would like to add them
 222 to the examples collection on the next release please email them to
 223 jan@unixpapa.com and include a short description.
 224
 225 Checkpassword Authenticators
 226 ----------------------------
 227
 228 There are various "checkpassword" compatible authenticators available on the
 229 net which can be used with mod_authnz_external.  These authenticators are most
 230 commonly used with qmail pop servers but it is sometimes useful to be able
 231 to use the same authentication system for some web pages.  I've listed some
 232 of the ones that look useful for mod_authnz_external, but I've tested only
 233 'checkpassword'.
 234
 235    checkpassword
 236         http://cr.yp.to/checkpwd.html
 237         Dan J. Bernstein <djb@cr.yp.to>
 238
 239         Authentication from a Unix shadow password file, similar to the
 240         the pwauth program.
 241
 242    radcheckpassword
 243         http://www.tic.ch/e-image/andrew/software/radcheckpassword/
 244         Andrew Richards <andrew@tic.ch>
 245
 246         Radius authentication.