mod_cookie_auth
is a Lua hook script implemented for the Apache2 HTTP server. Its primary functionality involves storing authentication results within a cookie, effectively reducing the number of authentication prompts whenever a browser restarts. This feature proves extremely beneficial for mobile web applications that depend on HTTP authentication techniques, given that the 'Authorization' header might get lost when inactive tabs are put into sleep mode by mobile browsers.
To clone the repository and install mod_cookie_auth, run:
git clone https://github.com/vivimice/mod_cookie_auth.git
cd mod_cookie_auth
sudo ./install.sh
You may need to generate a digest salt. The following command can be used to create one:
cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 32 | head -n 1
After generating a salt, proceed to modifying your Apache2 configuration file. Append the following lines in the configuration file:
LuaHookAccessChecker /usr/local/lib/mod_cookie_auth/mod_cookie_auth.lua check late
LuaHookAuthChecker /usr/local/lib/mod_cookie_auth/mod_cookie_auth.lua store early
SetEnvIf Host .* MOD_COOKIE_AUTH_SALT=<put_your_random_generated_salt_here>
Replacing <put_your_random_generated_salt_here>
with the output of the digest salt command.
Finally, to enable necessary modules, check the updated configuration, and reload your Apache2 instance for the changes to take effect, use the following commands:
sudo a2enmod lua setenvif
sudo apache2ctl configtest && sudo apache2ctl graceful
Upon successful initial authentication by standard authentication modules (mod_auth_basic or mod_auth_digeset), the mod_cookie_auth
hook generates a cookie. This cookie contains the authenticated user details, expiration time, and a checksum.
In instances where the browser is restored from sleep, the 'Authorization' header may be cleared. During such instances, mod_cookie_auth
is capable of restoring the user's authentication state using the persisted cookies.
The mod_cookie_auth
can be customized using the Set-EnvIf
directive (Please note that Set-Env
is not suited for this purpose, more information can be found here). The template for the configuration appears as follows:
SetEnvIf Host .* <CONFIG_NAME>=<CONFIG_VALUE>
The aforementioned configuration directive can be implemented in several contexts such as the server configuration, virtual host, directory, or .htaccess.
Config Name | Type | Required | Comment |
---|---|---|---|
MOD_COOKIE_AUTH_SALT | string | yes | The salt is employed in generating the checksum portion of the cookie value. NOTE: It's crucial to generate intricate values in this section to guarantee sufficient security against brute force attacks. |
MOD_COOKIE_AUTH_KEY | string | no | The name of the cookie. Default value: mcasec |
MOD_COOKIE_AUTH_TTL | int | no | The maximum expiry time (in seconds) of the authentication period since the last successful access. Default value: 86400 |
MOD_COOKIE_AUTH_PATH | string | no | The path section of the outgoing cookie. Default value: / |
MOD_COOKIE_AUTH_DISABLE_SECURE_COOKIE | string | no | Configure the parameter as this_is_unsafe to omit the secure attribute from the cookie.IMPORTANT: Exposing cookies in unencrypted traffic is a security risk. For more details, refer to the Security section of the documentation. |
The mod_cookie_auth
module, which is based on cookies, is susceptible to cookie hijacking. To counteract this vulnerability, mod_cookie_auth
implements a widely-used protection method against cookie hijacking.
By default, the mod_cookie_auth
module enables both http_only
and secure
attributes. These attributes instruct the browser to hide the cookie value from scripts and unencrypted traffic. The secure
attribute can be disabled by setting the MOD_COOKIE_AUTH_DISABLE_SECURE_COOKIE
configuration to this_is_unsafe
. This setting should ONLY be utilized in scenarios where SSL is not applicable.
The mod_cookie_auth
module utilizes salted MD5 to mitigate the risk of cookie value forgery. For enhanced resistance against dictionary attacks, it is advisable to set a private, highly random value for the MOD_COOKIE_AUTH_SALT
configuration.
Also, to avoid the unintended exposure of MOD_COOKIE_AUTH_SALT
, ensure that the configuration file containing the SetEnv-If
directive is not accessible by any unnecessary user on the server.