Home

mod_authnz_external and mod_auth_external

Previous Maintainer: Jan Wolter (deceased)
Previous Maintainer: Tyler Allison (allison@nas.nasa.gov)
Original Author: Nathan Neulinger (nneul@umr.edu)
Other Contributors: See CONTRIBUTORS

Mod_authnz_external and mod_auth_external are flexible tools for building custom basic authentication systems for the Apache HTTP Daemon. "Basic Authentication" is a type of authentication built into the HTTP protocol, in which the browser automatically pops up a login box when the user requests a protected resource, and the login ids and passwords entered are checked by Apache. Mod_auth*_external allows the password checking normally done inside Apache to be done by an separate external program running outside of Apache. This is useful in either of two situations:

• Rapid, Safe Deployment of Custom Authentication Systems. Standard authentication modules with names like mod_auth_file and mod_auth_ldap exist for most common forms of password database, but occasionally you will need to authenticate out of some database for which no appropriate module exists. Writing custom authentication modules is difficult, requiring a lot of knowledge of the internals of Apache, and bugs in such modules can crash Apache. But with mod_auth*_external the custom code can be in a separate program, possibly even a Perl or PHP script. The interface is very simple, and bugs in the authenticator program can not possibly crash Apache.

• Authentication out of Secure Databases. It is often undesirable for a password database to be readable by Apache. If it is readable by Apache, then it is possible that bugs in Apache or in any CGI program run by Apache could allow hackers to access the password database. With mod_auth*_external the external authenticator can be configured as a setuid program, so that it runs as a different user than Apache, and so can access databases that are not accessible to Apache. Since only the small, simple authenticator program has the privileges to access the database, instead of all of Apache, this is vastly easier to make secure.

One of the most common secure databases that people want to authenticate out of is the Unix system password database. The open source pwauth program is a mod_auth*_external compatible authenticator that can do this. It can also authenticate from any PAM authentication source.

The obvious disadvantage of using mod_auth*_external is that each authentication requires that the authentication program be loaded and launched. This causes some extra computational overhead. Some hooks have been inserted into mod_auth*_external to make it easy to replace the call to an external authenticators 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, but you clearly lose the advantages of external authentication listed above.

Mod_auth*_external can also be used to run external programs to make access control checks. Access control means checking if a user is in a group allowed to access a particular resource. It occurs after a user has been authenticated, by mod_auth*_external or by another module.

Compatibility

Apache Versions

Apache Version	mod_authnz_external Version
Apache 2.4	mod_authnz_external 3.3.x
Apache 2.2	mod_authnz_external 3.1.x or 3.2.x
Apache 2.0	mod_auth_external 2.2.x
Apache 1.3	mod_auth_external 2.1.x

The addition of "nz" to the module name in recent releases reflects the fact that the module has been redesigned to fit into the new authentication architecture introduced by Apache, in which top level authentication modules named mod_auth_basic and mod_auth_digest call lower level modules with names like mod_authn_file and mod_authn_dbm.

Windows Support

Version 3.3.3 builds upon work done in 3.2.0 and 3.3.2 to get mod_authnz_external working on Windows. The latest master also includes a Windows-specific nmake makefile, Makefile.win. This is recent code, so if you experiment with this, please let us know of any problems you encounter.

OS2, Netware, etc

Version 3.2.0 of mod_authnz_external was redesigned to avoid all unix system calls and work entirely through the Apache API. In theory it should now work on any operating system supported by Apache. However, I do not know that anyone has tried this. If you experiment with this, please let us know the results.

Digest Authentication

Mod_authnz_external does not work with digest authentication. It is unlikely that anyone would actually want to do this. 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 reasonable authentication databases (storing plain text passwords is not reasonable). Digest authentication out of a Unix password database is impossible, for example.

Security Considerations

Older versions of mod_auth_external would by default pass logins and passwords into the authentication module using environment variables. This is insecure on some versions of Unix where the contents of environment variables are visible on a 'ps -e' command. In more recent versions, the default is to use a pipe to pass sensitive data. This is secure on all versions of Unix, and is recommended in all installations.

People using mod_auth*_external with pwauth to authenticate from system password databases should be aware of the innate security risks involved in doing this.