Introduction:

These two modules provide basically the same functionality, and differ mainly in the way they interface to other authentication code in Apache. For Apache 2.1 and later, mod_authnz_external should be prefered. For older versions of Apache, mod_auth_external must be used.

The module can be used in either of two somewhat divergent ways:

• External Authentication:

  When a user supplies a login and password, mod_auth*_external runs a separate program that you provide, passing it the login and password. Your program does whatever checking and logging it needs to, and then returns a Accept/Reject flag to Apache.

  This is slower than doing the authentication internally because it has the overhead of launching an external program for each authentication. However, there are at least two situations where it is very useful:

  • Rapid prototyping. Mod_auth*_external makes a very nice swiss army knife authenticator. You can quickly put together custom authentication systems for many weird authentication applications. The external authentication program can be a shell script or perl program. It can be written without knowing much about building Apache modules. Bugs in it will not endanger the overall integrity of the Apache server.

  • Access restrictions. There are situations where you do not want to make your user database readable to the user-id that Apache runs under. In these cases the external authentication program can be an suid program that has access to databases Apache cannot access. For example, if you want to authentication out of a Unix shadow password database, and you aren't foolish enough to run Apache as root, a carefully written suid-root external authentication program can do the job for you. Such an authenticator for shadow password files and PAM (pwauth) is available separately.

• Hardcoded Authentication:

  Some hooks have been inserted into mod_auth*_external to make it easy to replace the call to the external authentication program with a call to a hardcoded internal authentication subroutine that you write.

  This is sort of a half-way measure to just writing your own Apache module from scratch, allowing you to easily borrow some of the logic from mod_auth*_external. It's a bit more dangerous than using an external authenticator, as bugs in your module can crash Apache, but performance is usually better.

Example Authenticators in Distribution:

• External Authentication Programs:

  pwauth

  A setuid-root external authentication program for securely authenticating out of most flavors of Unix shadow password files, or via PAM. Combined with pam_smb, this supports NT-style SMB authentication. Supports some Unix lastlog and faillog options.

  No longer in mod_auth*_external distribution.
  Available at http://www.unixpapa.com/pwauth/.
  Author and Maintainer: Jan Wolter (jan@unixpapa.com)

  auth-mysql

  A external authenticator for authenticating out of a MySQL database. Written in Perl using the DBI/DBD library, so it is easily adapted to any other SQL server.

  Included in mod_auth*_external distribution.
  Author and Maintainer: Anders Nordby (http://anders.fix.no/software/#unix)

  test

  Several small dummy external authentication programs written in Perl. These are meant only for testing of mod_auth*_external. They accept any user whose password and login name are identical. They write lots of debugging info to the error_log file.

  Included in mod_auth*_external distribution.
  Author and Maintainer: Jan Wolter (jan@unixpapa.com)

• Hardcoded Authentication Functions:

  radius

  A Radius client using code from the publicly available Merit Radius source code.

  Included in mod_auth*_external distribution.
  Author: Tyler Allison (allison@nas.nasa.gov)
  Unmaintained.

  sybase

  A function that queries a sybase database and compares the passwords for said user.

  Included in mod_auth*_external distribution.
  Author: (br@ota.fr.socgen.com)
  Unmaintained.

Bugs:

It has also been reported that it doesn't work with mod_frontpage.

Version Notes:

In 3.2.x, the code for launching the external authenticator has been rewritten to work by using Apache's internal process management library instead of directly calling the Unix process management functions like fork and execv. In theory this means that it should work on any operating system that Apache works on, including Windows. However, I only do Unix development, and don't even have a Windows C compiler, so I've only tested it under Unix. There is also a new alternate configuration command syntax, that will make it easier to support various other future improvements.

There used to be another version of mod_auth_external maintained by Satoh Fumiyasu. I believe the last version was called version 3.0.0beta3. The versions seem to have diverged after version 2.0.0, Tyler Allison's next-to-last release. It differed significantly from my version, and was not precisely compatible. Fumiyasu's version supported authenticating through a socket against an authentication daemon, a feature I hope to support in the future. It's documentation was mostly in Japanese. This seems to have largely disappeared from sight.

Compatibility:

Apache 1.3:

The 2.1.x versions of mod_auth_external are designed for use with Apache 1.3. This branch will continue to be supported for a while, though with steadily decreasing enthusiasm.

Apache 2.0:

The 2.2.x versions of mod_auth_external are designed for Apache 2.0.

Apache 2.2:

Apache 2.2 introduces authentication architecture with top-level authentication modules called mod_auth_basic and mod_auth_digest, which call lower-level authentication modules like mod_authn_file and mod_authn_dbm. Mod_Authnz_External is designed to fit into this scheme, and should be prefered by Apache 2.2 users.

Mod_Authnz_External does not work with digest authentication. I hope to implement this someday, but for a variety of reasons, I'm not confident that anyone would ever want to use it. In digest authentication, the password is one-way encrypted before it is sent by the browser to the http server. It is only possible to check the validity of that password, if the password database contains either plain text passwords or passwords encrypted by exactly the method defined in the digest authentication standard. If the database used some other one-way encryption method, then there would be no way to tell whether or not the password sent from the browser and the one in the database matched. So digest authentication could not be used with most authentication databases. Digest authentication out of a Unix password database is impossible, for example.

It is possible to use the old 2.2.x versions of mod_auth_external with Apache 2.2. You can just run mod_auth_external as a stand-alone authentication module, not using mod_auth_basic. Ideally we'd turn mod_auth_basic off for the directory, but this doesn't currently appear to be possible, so you have to set it to be non-authoritative, so that mod_auth_external will be run after it fails. This is described in the installation notes.

Windows:

It is possible that version 3.2.0 and later will work under Windows, and every other operating system supported by Apache, but this has not been tested.

Security Considerations:

With the insecure "environment" method, mod_auth*_external passes the user's login and password to the external authentication program by putting them in environment variables called USER and PASS. On many versions of Unix (including SunOS and IRIX) any user logged onto the server can see these values by doing a "ps -e" command. This would obviously be a problem if there are ever untrusted users on your server. Other versions of Unix (including Linux) restrict "ps -e" so you can only see your own processes, but this may still be a problem if untrusted people can put CGI programs on your server, since those may run as the same user as your authentication program does. Some versions of Unix don't have a "ps -e" command at all, but even then it is best to be careful. Although the default "ps" command on Solaris won't display environment variables, the backwards compatible "/usr/ucb/ps" command does. Are you sure there isn't an old-style ps command on your system?

I recommend using the "pipe" method instead. Then, mod_auth*_external passes the user's login and password to the external authentication program via a pipe. This is far more secure. If this is done (and it should be), then there should be no problems on any version of Unix.

Authn / Authz

The mod_authn_external part is an authentication provider for the mod_auth_basic module. Mod_auth_basic handles all the negotiations with the browser, while all mod_authn_external does is check if a password submitted by the user is correct (which it does by running an external program to perform the check).

The mod_authz_external part does access control. It has no relation to mod_auth_basic. It comes into play after authentication is complete, when a "Require group" or "Require file-group" directive is given. It checks if the authenticated user is in the list of required groups (which it does by running an external program to perform the check).

Links:

• Apache HTTP Server. Can't run mod_auth_anything without it.

• pwauth external authenticator. Used with mod_auth*_external for authenicating out of a unix password database or via PAM.

• Jonathan Weiss's blog entry describing how to install mod_authnz_external and pwauth. Might be a useful reference.

• mod_auth_shadow, by Bruce Duggan, appears to be a recent re-implementation of the same basic concept for authenticating out of shadow password file. I haven't checked it out enough to decide if it has any advantages over using pwauth with mod_auth_external. On first inspection it appears to be slightly less portable and paranoid.

• mod_auth_pipe is Alvaro Gamez Machado's development from mod_auth_shadow, allowing it to run arbitrary authenticators. The result ends up doing pretty much the same thing as mod_auth_external.

• mod_auth_script looks like it can be used to perform similar functions to mod_auth_external. It runs the authenticator by generating a sub-request to a CGI program. I haven't analyzed this approach, but it has obvious advantages in that the authenticator programs are just normal CGIs and in greater portability to windows servers.

• PAM. Portable Authentication Modules are libraries that have a common interface and can be linked to a program to do authentication out of different databases. Linux, FreeBSD and Solaris support PAM. OpenBSD does not.

  If you want to authenticate from a PAM module, but the user your httpd runs as does not have the necessary access, then the pwauth external authenticator can be run from mod_auth*_external to do the PAM authentication.

  The list of PAM modules includes authenticators for Kerberos, radius, unix password or shadow files, SMB, various SQL databases, and just about anything else imaginable.

• mod_auth_pam. If you want to use a PAM module to authenticate, and whatever user apache runs as has the necessary access to do the check, then you don't need an external authenticator, and you should probably use this module instead of mod_auth*_external and pwauth. There is such a thing as mod_auth_pam2, which is supposed to work with Apache2.

• Checkpassword. Checkpassword programs are external programs that are passed a login and password and check some database to decide if they are valid. Thus they are similar to the external authenticators traditionally used with mod_auth*_external. Mod_auth_external now supports the checkpassword protocol, so that authenicators written for checkpassword can be used with mod_auth*_external.

  The list of checkpassword authenticators includes, well, just about everything. Worth noting are checkpassword-pam, which could be used instead of pwauth as an external program to do authentication through an arbitrary PAM modules, and radcheckpassword which does radius authentication.

• mod_auth_any. This seems to be similar in function to mod_auth*_external. It seems very sparsely documented at this stage, but it from looking at the source code it seems to pass the login/password to the external authenticator on the command line, which doesn't seem very secure since they'd be trivially visible to anyone doing a 'ps'.

• vcheck. An external authenticator by Anders Brander for use against a vpopmail user database.

• Apache Module Registry. A good place to find apache modules.