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