ArchitectureConsiderations

Introduction

Mod_authnz_external is a flexible tool for building custom basic authentication systems for the Apache HTTP Server. "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 design leads to a number of important side-effects, listed in the Considerations section below.

Architecture Overview

Apache Authentication Architecture Details

A browser request (e.g. GET /home.html HTTP/1.1 or POST /myPHPContent.php HTTP/1.1) comes in to Apache, then Apache does 2 separate things (among many others):

1. Check Authorization -> mod_authnz_external -> Your Authenticator (e.g.) DefineExternalAuth checkerscript pipe myPHPAuthChecker.php

   1. This is where mod_authnz_external and your authenticator (PHP, Bash script, etc.) does its work
   2. In the above example, the myPHPAuthChecker.php PHP script runs as a separate PHP process and returns only an ok/fail code, nothing else is passed back to Apache from any authenticator. See the Considerations section below for important side-effects to be aware of.

2. Actually Build the Page -> requested file (e.g.) myPHPContent.php -> Apache's registered handler for PHP files (e.g. mod_php)

   1. This is where the work to build the page the user will see is done, either returning a static file or using a CGI script or a registered Apache handler module
   2. This is where cookies (including session cookies such as PHPSESSID) are created

Put another way:

1. This mod_authnz_external module deals solely with Authentication/Authorization, and is not involved at all in actually constructing the requested page: in other words, this module returns a pass/fail code to apache, and does not output headers or body content. See the Considerations section below.

2. The authenticator (such as a PHP script) you are running via this module is external, meaning it is running in a separate process and is not in the current apache process at all. See the Considerations section below.

Considerations for Your External Authenticator

As mentioned and shown in the diagram above, the password checker program (Authenticator) you specify in your config file is then run completely external to Apache as a separate process. It is important to remember that mod_authnz_external handles authentication and authorization checks when accessing a page and has no effect on the resulting page itself. This has a few potentially unexpected side-effects:

1. You cannot create or set cookies inside of an authenticator script (as you might be accustomed to with PHP, Java, etc. when running your web content).

   1. Any existing cookies sent by the browser can be read. Creating cookies here is meaningless, since these are external and have nothing to do with Apache at all.

2. You cannot create or set environment variables inside of an authenticator script (as you might when running your web content).

3. You can only read certain environment variables inside of an authenticator script, not the full list.

   1. Only the following list of environment variables are passed to the external authenticator process.
   2. Please note: If you want to pass something in an environment variable from Apache to the external process, you should set the CONTEXT environment variable.

4. You cannot create sessions in your authenticators based on PHP or similar scripts.

   1. Trying to do so may not throw an error, depending on your PHP/script configuration, but the user will never see the new session because the new session cookie is not sent to the user (see point 1 above).
   2. Please note: while you can read the value of an existing PHPSESSID cookie from an external script, the actual $_SESSION data will not be available from the external script unless PHP's global session.save_path variable and Apache's mod_php (or the php_fcgi setup for the current vhost) session.save_path variable point to the same location. This would depend on your server setup/environment. Other script hosts would have similar considerations.

5. Your authenticator is not affected by Apache configuration. The authenticator (such as a PHP script) you are running via this module is external, meaning it is running in a separate process and is not in the current Apache process at all. Apache config file settings are not passed to the authenticator.

   1. For example, a PHP-based authenticator would get its settings solely from sources such as the global php.ini file, and would not at all be affected by mod_php directives in apache's config files, or a vhost/port-specific config for php-fcgi.

6. Your authenticator will run in the Apache user context.

   1. For example, if you have an Apache service named apache2 set up to run as the system user myapacheuser, then the authenticator will also run as myapacheuser.
   2. This means that anything your authenticator accesses needs to be available to the Apache user context for your authenticator to work properly.
   3. For example, if your authenticator reads a config file, that file needs to be readable by the myapacheuser user.

Security Considerations

mod_authnz_external can be used to quickly construct secure, reliable authentication systems. It can also be mis-used to quickly open gaping holes in your security. Read the documentation, and use with extreme caution.

Use of this module requires development of an external authentication program or a hardcoded internal function. These are typically very simple programs, but there are more ways to screw up your security by doing them badly than we could possibly list. See the file AUTHENTICATORS or the How to Write an External Authenticator or Group Checker wiki document for more information on implementing authenticators.

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.