Environment Variables

Authenticating via Apache will set a number of environment variables, depending on the configuration and the authentication method. I'm skipping digest authentication because that is not commonly used.

X.509 Authentication

The value of REMOTE_USER is dependent upon the configuration. If SSLUserName or NSSUserName is set then that component of the client certificate DN is set. The exception is when FakeBasicAuth is set, in which case the full DN is set.

By default only the standard CGI environment variables are included, plus HTTPS.

A number of SSL-specific variables are set if ExportCertData is enabled in SSLOptions or NSSOptions.

There may be some slight differences in the variables available in mod_ssl and mod_nss. For example, SSL_TLS_SNI is not available in mod_nss.

Authorization can be done by specifying the allowed users, groups, attribute with in an entry or even a filter.

Attributes can be specified in the AuthLDAPURL value such that those values are set as environment variables of the form "AUTHENTICATE_", so any arbitrary list of values may be provided.

Proposed Additional Variables

When Apache module is used for authentication, the authentication result is passed to the application typically in the form of environment variable REMOTE_USER. Current web applications however want and need to create the user record in their internal databases so that foreign keys validate, and applications also want to do access control checks (authorizations) -- applications typically don't rely on Apache modules for authorization.

We are in need of a way for Apache modules to pass information about the authenticated user beyond the login name (in REMOTE_USER) to the application. That way the applications do not need to implement all possible authentication mechanisms (Kerberos, SAML, LDAP, ...) and can depend on specialized mod_auth_* modules to do it, while being able to know what user to populate and maintain in their internal user database.

We propose Apache modules that wish to pass information about users to applications adopt the following environment variable names:

when external authentication fails (and REMOTE_USER is not set), this variable can contain error describing the reason

The character set for values should be UTF-8.

The list above is not exhaustive, authentication and identity modules can provide additional variables with other values and meanings and applications are welcome to use them.

Module mod_lookup_identity (documentation, git repo) has been created as a proof of concept for this way of information passing. The full functionality depends on the sssd-dbus package (not yet released, in testing).

Module mod_intercept_form_submit (documentation, git repo) has been created as a proof of concept for PAM authentication based on form submission and it supports the REMOTE_USER and EXTERNAL_AUTH_ERROR outputs, plus mod_lookup_identity can work based on the mod_intercept_form_submit authentication result (latest versions of both modules required).