1 How To Implementation External Authentication Programs
2 for mod_authnz_external or mod_auth_external
7 External authenticators can be written in almost any language. The sample
8 authenticators in the 'test' directory are in Perl and PHP. The 'pwauth'
9 authenticator is in ANSI C. The example code fragments in this document
12 If the authenticator is a script rather than a compiled program, it normally
13 has to start with a "#!/bin/sh" or "#!/usr/bin/perl" type directive. Scripts
14 without such directives may get interpreted by the shell, or may just not
15 work, depending on your installation.
19 The authenticator program should be written with great care because it runs
20 as a privileged user and handles privileged data. A poorly written
21 authenticator could substantially compromise the security of your system.
22 You get points for paranoia. Some notes:
24 - Don't make any assumptions about the length of the login names and
25 passwords given by the user. I *think* Apache will never pass you ones
26 that are longer than 8192 characters, but don't depend this. Check very
27 carefully for buffer overflows.
29 - Think about locking. It is possible to get lots of hits at your website
30 very fast, so there may be many programs simultaneously reading your
31 authentication database, plus updates may be going on at the same time.
32 Probably some form of locking is needed to make all this work right.
34 - Think about core dumps. On some systems core dump files can be publically
35 readable. A core dump from your authenticator is likely to contain the
36 user's plain text password, and may include large chunks of your password
37 database that may have been in buffers. For C programs on most versions of
38 Unix, it is possible to disable core dumps by doing something like:
40 rlim.rlim_cur = rlim.rlim_max = 0;
41 (void)setrlimit(RLIMIT_CORE, &rlim);
43 Actually, core dumps seem to be mostly a thing of the past. Most modern
44 Unixes don't seem to generate them.
46 It may not hurt to spend a little time looking at the features of the pwauth
47 authenticator, which is the most secure external authenticator that I have
50 PASSWORD AUTHENTICATORS
52 Authenticators communicate their result by the exit status code they return.
53 A value of 0 indicates that the password is correct. Other values indicate
54 that the password is incorrect, or something else is wrong. It can be
55 useful to return different error codes for different kinds of errors. These
56 will be logged in the Apache error log file, and can be helpful in diagnosing
57 problems. This version of mod_authnz_external does not have any provision for
58 returning textual error messages from the external authenticator. You might
59 be able to use syslog() for this. This might be improved in future releases.
61 Returned error codes should not be negative. Negative values are used
62 internally to mod_authnz_external to indicate problems launching your program.
64 How the external authentication program gets its arguments depends on
65 the method used. The method used is determined by the 'SetExternalAuthMethod'
66 command in your Apache configuration file. You need implement only the
67 method that you plan to use in your configuration.
71 In the "pipe" method, the arguments are read from standard input. The
72 user name will be on the first line, and the password will be on the
73 second. Here's a typical chunk of C code to read that:
77 char user[100], password[100], *p;
79 if (fgets(user, sizeof(user), stdin) == NULL) exit(2);
80 if ((p= strchr(user, '\n')) == NULL) exit(4)
83 if (fgets(password, sizeof(password), stdin) == NULL) exit(3);
84 if ((p= strchr(password, '\n')) == NULL) exit(5)
87 if (check_password(user, password) == OK)
88 exit(0); /* Good Password */
90 exit(1); /* Incorrect Password */
93 Here we simply read two lines from stdin, being careful not to allow
94 buffer overflows and stripping off trailing newlines.
96 We assume "check_password()" is some function that checks the validity of a
97 password and returns 'OK' if it is good.
99 Note that we exit with different non-zero error codes in different error
100 cases. This will be helpful for debugging, as those values will be logged
101 when authentication fails, giving you some clue as to what went wrong.
102 It'd really be better for check_password() to return more detailed error
103 codes, but I wanted to keep the example simple.
107 The "checkpassword" method is identical to the "pipe" method, except
108 that the user name and password are terminated by NUL ('\0') characters
109 instead of newline characters, and they must be read from file descriptor
110 3 instead of standard input. Documentation for the checkpassword
111 interface is at http://cr.yp.to/checkpwd.html.
115 In the "environment" method, the arguments are passed in environment
116 variables. The user id and the clear-text password are passed in the
117 USER and PASS environment variables respectively.
119 Note that the environment method has fundamental security weaknesses,
120 and should probably not be used unless you have cause to believe it is
121 safe on your system. I wouldn't be surprised if it is marginally faster
122 than the pipe method. Most applications should use the pipe method instead.
124 A typical chunk of C code to authenticate with the environment method
129 char *user, *password;
131 if ((user= getenv("USER")) == NULL) exit(2);
132 if ((password= getenv("PASS")) == NULL) exit(3);
134 if (check_password(user, password) == OK)
135 exit(0); /* Good Password */
137 exit(1); /* Incorrect Password */
142 Security is generally less of a issue with group authenicators, since they
143 are not handling any data as sensitive as clear-text passwords. They are
144 only passed a user name (presumably already authenticated), and a list of
145 group names. They exit with status code 0 if that user is in one of those
146 groups, and a non-zero code otherwise.
148 In versions of mod_auth_external before 2.1.8, external authenticators were
149 always passed just one group name. If the Apache "require group" directive
150 listed more than one group, then the external authenticator would be called
151 once with each group name, which could be inefficient if you have a large
152 number of groups. Mod_auth_external will still behave this way if you
153 issue the "GroupExternalManyAtOnce off" directive.
155 Newer versions of mod_auth_external and mod_authnz_external will pass all
156 group names, separated by spaces. There will only be multiple calls if more
157 than one "require group" directive applies to the same program (e.g., if
158 different parent directories contain such directives in their .htaccess
159 files - for efficiency, this should be avoided). The list of group names
160 is passed in exactly as they appear on the "require group" directive - if
161 your program can't handle multiple spaces between group names, don't put
164 Arguments are passed in a manner similar to password authenticators. The
165 method used is determined by the 'SetExternalGroupMethod' command in your
166 Apache configuration file.
170 In the "environment" method, the arguments are passed in environment
171 variables. The user id and the group names are passed in the USER and
172 GROUP environment variables respectively. A typical chunk of C code to
173 fetch the arguments and check each group might be like:
177 char *user, *groups, *group;
179 if ((user= getenv("USER")) == NULL) exit(2);
180 if ((groups= getenv("GROUP")) == NULL) exit(3);
182 group= strtok(groups, " ");
183 while (group != NULL)
185 if (check_group(user, group) == OK)
186 exit(0); /* User is in group */
187 group= strtok(NULL, " ");
189 exit(1); /* User is not in any group */
192 Here "check_group()" is some function that looks in your database to see if
193 user is in group and returns 'OK' if he is.
197 In the "pipe" method, the arguments are read from standard input. The
198 user name will be on the first line, and the group name will be on the
199 second. Here's a typical chunk of C code to read that:
203 char user[100], groups[100], *group, *p;
205 if (fgets(user, sizeof(user), stdin) == NULL) exit(2);
206 if ((p= strchr(user, '\n')) == NULL) exit(4)
209 if (fgets(groups, sizeof(groups), stdin) == NULL) exit(3);
210 if ((p= strchr(groups, '\n')) == NULL) exit(5)
213 group= strtok(groups, " ");
214 while (group != NULL)
216 if (check_group(user, group) == OK)
217 exit(0); /* User is in group */
218 group= strtok(NULL, " ");
220 exit(1); /* User is not in any group */
223 Here we simply read two lines from stdin, being careful not to allow
224 buffer overflows and stripping off trailing newlines. We loop through
225 all groups, checking each.
229 Mod_auth_external will happily try to do group authentication via the
230 checkpassword method, piping NUL terminated user and group names to
231 the child process's file descriptor 3, but this isn't actually allowed
232 for in the checkpassword protocol specification, so I don't recommend it.
234 OTHER ENVIRONMENT VARIABLES
236 In all cases (pipe or environment method, password or group authentication),
237 the following additional environment variables will be supplied to the
240 AUTHTYPE either "PASS" or "GROUP" depending on whether we are doing
241 password or group authentication. This is handy if you are
242 using one program to do both.
244 CONTEXT a string whose value is set by an "AuthExternalContext"
245 directive in the .htaccess file or "<Directory>" block for
246 the directory. This can be used to select different
247 authentication behaviors in different directories. It is
248 undefined if there is no "AuthExternalContext" directive.
250 IP the client's ip-address.
252 HOST the host name corresponding to IP, if Apache has
253 "HostnameLookups On".
255 FORWARDS If a load-balancer or proxy is being used, then the "IP" variable
256 is just going to be the ip-address of the server that forwarded
257 the client's request to the current server. In that case, the
258 "FORWARDS" environment variable gives a comma-separated list of
259 ip-addresses, the first of which will be the original client's ip,
260 while the rest are all the other proxies the request was forwarded
261 through before reaching the server named by the the "IP" variable.
263 PATH the httpd's path environment variable.
265 COOKIE all cookie values passed in by the client.
267 HTTP_HOST the server's host name, as given in the HTTP request. May
268 be useful if you have multiple virtual hosts sharing an
271 URI the document requested. This is the URL including any extra
272 path information, but not including the hostname or any CGI
275 These may be useful for logging, or you may want to accept logins from
276 certain users only if they are connecting from certain locations or requesting
279 Note that if you have configured Apache with "HostnameLookups Off" then HOST
280 will usually not be set. If you really want hostnames, either turn on
281 HostnameLookups or do your own gethostbyaddr() calls from the authenticator
282 when HOST is not defined. Note that if the user is coming from an
283 unresolvable IP, then hostname lookups can be very slow.
285 Note that using IP addresses to track a user through your site is not
286 reliable. Users of services like AOL and WebTV use proxy servers, so that
287 their IP addresses appear to change constantly since each request may come
288 through a different proxy. A single user's requests for successive pages,
289 or for different images on the same page may all come from different IP
292 The PATH environment variable passed to the authenticator is just whatever
293 PATH was in effect when Apache was launched, and may differ if the server
294 was launched automatically during a reboot or manually by an admin.
295 Probably your program should set its own PATH if it needs one.
297 The COOKIE environment variable contains all cookies set in the current
298 request. This has the same format as the HTTP_COOKIES ("key=val;key=val")
299 passed to a CGI program. This should be used with caution. Cookies come
300 from the user's computer and might have been created, editted or deleted
301 by the user rather than your website. This severely limits their use for
302 authentication. It is not possible to set cookies from an authentication
305 The URI variable is there because various people want it. Mostly it
306 is useful not for authentication ("who is this person?") but for access
307 control ("is this person permitted to do this?"), and good design usually
308 dictates separating those functions. Strictly speaking, an authenticator
309 is not the right place to be doing access control. However,
310 mod_authnz_external is 50% a kludge-builder's tool, so we won't fuss if you
311 want to break the rules.