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.
A number of useful variables are set by Apache itself, they include:
|DOCUMENT_ROOT||The directory the current file/script is executing|
|HTTP_ACCEPT||Contents of Accept: header|
|HTTP_HOST||Contents of Host: header|
|HTTP_USER_AGENT||Contents of User-Agent: header|
|QUERY_STRING||The query string, if any|
|REMOTE_ADDR||The IP address of the client|
|REMOTE_PORT||The port of the client machine|
|REQUEST_METHOD||The HTTP request method|
|REQUEST_SCHEME||The scheme of the reqeust (e.g. http)|
|REQUEST_URI||The requested URI|
|SERVER_ADDR||The IP address of the server|
|SERVER_NAME||The hostname of the server or virtual host|
|SERVER_PORT||The port on the server|
|SERVER_PROTOCOL||Name and version of the request protocol|
|SERVER_SIGNATURE||Server version and virtual host name added to server-generated pages|
|SERVER_SOFTWARE||Server identification string|
|UNIQUE_ID||ID set to be unique across requests. mod_unique_id|
Basic authentication is managed by Apache.
The configuration may look something like:
AuthType Basic AuthName "Restricted Files" AuthBasicProvider file AuthUserFile /etc/httpd/conf/passwords Require valid-user
The user database would be created with this:
htpasswd -c /etc/httpd/conf/passwords testuser
Kerberos authentication is managed by mod_auth_gssapi or mod_auth_kerb.
If delegation is enabled in the client and the server configuration includes KrbSaveCredentials on, then KRB5CCNAME will be set pointing to the user's keytab.
The configuration may look something like
AuthType GSSAPI AuthName "Kerberos Login" GssapiCredStore keytab:/etc/http.keytab
for mod_auth_gssapi or for mod_auth_kerb:
AuthType Kerberos AuthName "Kerberos Login" KrbMethodNegotiate on KrbMethodK5Passwd off KrbServiceName HTTP KrbAuthRealms EXAMPLE.COM Krb5KeyTab /etc/httpd/conf/ipa.keytab KrbSaveCredentials on
X.509 authentication is managed by either mod_nss or mod_ssl (or mod_gnutls about which I know very little).
No specific AUTH_TYPE is set, see https://issues.apache.org/bugzilla/show_bug.cgi?id=45058
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.
<Directory "/var/www/secure"> NSSOptions +StdEnvVars NSSVerifyClient Require </Directory>
The mod_ssl configuration is similar. Replace NSS with SSL.
The variables are named the same between mod_ssl and mod_nss though the contents may differ slightly. The set of variables available in httpd 2.4 are.
|HTTPS||HTTPS is being used.|
|SSL_PROTOCOL||The SSL protocol version (SSLv2, SSLv3, TLSv1, TLSv1.1, TLSv1.2)|
|SSL_SESSION_ID||The hex-encoded SSL session id|
|SSL_CIPHER||The cipher specification name|
|SSL_CIPHER_EXPORT||true if cipher is an export cipher|
|SSL_CIPHER_USEKEYSIZE||Number of cipher bits (actually used)|
|SSL_CIPHER_ALGKEYSIZE||Number of cipher bits (possible)|
|SSL_COMPRESS_METHOD||SSL compression method negotiated|
|SSL_VERSION_INTERFACE||The mod_ssl program version|
|SSL_VERSION_LIBRARY||The OpenSSL program version|
|SSL_CLIENT_M_VERSION||The version of the client certificate|
|SSL_CLIENT_M_SERIAL||The serial of the client certificate|
|SSL_CLIENT_S_DN||Subject DN in client's certificate|
|SSL_CLIENT_S_DN_x509||Component of client's Subject DN|
|SSL_CLIENT_I_DN||Issuer DN of client's certificate|
|SSL_CLIENT_I_DN_x509||Component of client's Issuer DN|
|SSL_CLIENT_V_START||Validity of client's certificate (start time)|
|SSL_CLIENT_V_END||Validity of client's certificate (end time)|
|SSL_CLIENT_V_REMAIN||Number of days until client's certificate expires|
|SSL_CLIENT_A_SIG||Algorithm used for the signature of client's certificate|
|SSL_CLIENT_A_KEY||Algorithm used for the public key of client's certificate|
|SSL_CLIENT_CERT||PEM-encoded client certificate|
|SSL_CLIENT_CERT_CHAIN_n||PEM-encoded certificates in client certificate chain|
|SSL_CLIENT_VERIFY||NONE, SUCCESS, GENEROUS or FAILED:reason|
|SSL_SERVER_M_VERSION||The version of the server certificate|
|SSL_SERVER_M_SERIAL||The serial of the server certificate|
|SSL_SERVER_S_DN||Subject DN in server's certificate|
|SSL_SERVER_S_DN_x509||Component of server's Subject DN|
|SSL_SERVER_I_DN||Issuer DN of server's certificate|
|SSL_SERVER_I_DN_x509||Component of server's Issuer DN|
|SSL_SERVER_V_START||Validity of server's certificate (start time)|
|SSL_SERVER_V_END||Validity of server's certificate (end time)|
|SSL_SERVER_A_SIG||Algorithm used for the signature of server's certificate|
|SSL_SERVER_A_KEY||Algorithm used for the public key of server's certificate|
|SSL_SERVER_CERT||PEM-encoded server certificate|
|SSL_TLS_SNI||Contents of the SNI TLS extension (if supplied with ClientHello)|
Apache provides the module mod_authnz_ldap to perform authentication and authorization over LDAP.
A simple configuration looks like:
AuthType Basic AuthName "LDAP Protected" AuthBasicProvider ldap AuthLDAPURL ldap://127.0.0.1/dc=example,dc=com?uid?one Require valid-user
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:
|Variable name||Semantics||Possible source||Example mod_lookup_identity configuration|
|REMOTE_USER_GROUPS||colon-separated list of group names the user is in||POSIX call getgrouplist; sssd dbus call org.freedesktop.sssd.infopipe.GetUserGroups||LookupOutputGroups REMOTE_USER_GROUPS :|
|REMOTE_USER_GROUP_N, REMOTE_USER_GROUP_1, REMOTE_USER_GROUP_2, ...||number of user groups and individual group names||alternate way to get the list of groups, avoiding the split needed with REMOTE_USER_GROUPS||LookupUserGroupsIter REMOTE_USER_GROUP|
|REMOTE_USER_GECOS||Equivalent of the GECOS value from the password file, could be full name.||pw_gecos field of result of POSIX call getpwname; IPA attribute gecos, sssd dbus call org.freedesktop.sssd.infopipe.GetUserAttr gecos||LookupUserGECOS REMOTE_USER_GECOS or LookupUserAttr gecos REMOTE_USER_GECOS|
|REMOTE_USER_DOMAIN||domain the user was authenticated in (could be the domain in sssd, nss, LDAP, etc.)|
|REMOTE_USER_EMAIL||user's email address||IPA attribute mail, sssd-dbus attribute mail||LookupUserAttr mail REMOTE_USER_EMAIL|
|REMOTE_USER_GROUPS_JSON||list of groups the user is in, formatted as JSON string|
|REMOTE_USER_FIRSTNAME||user's first name||IPA attribute givenname, sssd-dbus attribute givenname||LookupUserAttr givenname REMOTE_USER_FIRSTNAME|
|REMOTE_USER_MIDDLENAME||user's middle name|
|REMOTE_USER_LASTNAME||user's last name||IPA attribute sn, sssd-dbus attribute sn||LookupUserAttr sn REMOTE_USER_LASTNAME|
|REMOTE_USER_FULLNAME||user's full name formatted as one string (similar to and possibly the same as REMOTE_USER_GECOS)||IPA attribute cn or displayname, sssd-dbus attribute cn or displayname||LookupUserAttr cn REMOTE_USER_FULLNAME or LookupUserAttr displayname REMOTE_USER_FULLNAME|
|REMOTE_USER_ORGUNIT||organizational unit to which the user belongs||IPA attribute ou, sssd-dbus attribute ou||LookupUserAttr ou REMOTE_USER_ORGUNIT|
|REMOTE_USER_EXTERNAL_ID||SID, GUID, or other unique identifier from the external identity provider; used to reconcile account after login change||IPA attribute ipaUniqueId, 389 DS attribute nsUniqueID, AD attribute objectSid||LookupUserAttr ipaUniqueId REMOTE_USER_EXTERNAL_ID|
|EXTERNAL_AUTH_ERROR||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).