Build Status License: GPL v3

What is “Auth MemCookie”?

Auth MemCookie is an Apache v2 Authentication and authorization modules are based on cookie Authentication mechanism.

The module doesn’t make Authentication by it self, but verify if Authentication the cookie is valid for each url protected by the module. The module validate also if the authenticated user have authorization to access url.

Authentication is made externally by an Authentication html form page and all Authentication information necessary to the module a stored in memcached identified by the cookie value Authentication session id by this login page.

How it Works

Phase 1 : The login Form

Authentication is made by a login form page.

This login page must authenticate the user with any authenticate source (ldap, /etc/password, file, database….) accessible to language of the page (php, perl, java… an ldap login page sample in php are in samples directory).

Then this page must set cookie that contains only a key the Authentication unique id of the Authentication session.

The login page must store authorization and user information of the authenticated user in memcached identified by the cookie key Authentication unique id.

The login page can be developed in any language you want, but must be capable to use memcached (they must have memcache client api for us)

Phase 2 : The Apache v2 Module

After the user is logged, the Auth MemCookie module check on each protected page by apache ACL is the user is authenticated.

When authenticating a request Auth MemCookie module walks through the following steps:

  1. Get the session id. The session id is stored in a cookie (by default named AuthMemCookie).

  2. Get the session data. Auth MemCookie module fetches session data by looking up the session id on the memcached server.

  3. Verify the remote ip. Auth MemCookie module checks the ip address stored in the session data against the ip address of the current request. This step is optional, and can be disabled by setting the Auth_memCookie_MatchIP option to no.

  4. Get username and groups from session data. The username is stored in the UserName field in the session data and the groups the user is a member of is stored in the Groups field.

  5. Check username and groups against Require configuration directives.

If any of the steps 1-4 fails, then Auth MemCookie will return a HTTP_UNAUTHORIZED (401) Authorization Required error. A HTTP_FORBIDDEN (403) Forbidden error will be returned if the last step fails.

When a user is successfully authenticated, Auth MemCookie will store all the fields from the session data in environment variables accessible to the web page. Every field of the session data will be send http header MCAC_<field-name> to the value of the field.

“Session data” format stored in memcached

The session data stored in memcached are composed with multiple line in form of name equal value ended by \r\n. some are mandatory, other are optional and the rest are information only (all this field are transmitted to the script language protect the module).

Session data format:

UserName=<user name>\r\n
Groups=<group name1>:<group name2>:...\r\n
RemoteIP=<remote ip>\r\n
Password=<password>\r\n
Expiration=<expiration time>\r\n
Email=<email>\r\n
Name=<name>\r\n
GivenName=<given name>\r\n

The session field size is for the moment limited to 10 fields by default.

Build dependency

You must have compiled and installed:

Compilation

# autoconf -f
# ./configure --with-apxs=/path/to/apache/httpd/bin/apxs --with-libmemcached=/path/to/libmemcached_install_dir/
# make
# make install

After that the mod_auth_memcookie.so is generated in apache modules installation directory.

How to configure Apache Module

Module configuration option:

This option can be used in location or directory apache context.

On the backend application

The application recieve this information:

And all session field (prefixed by Auth_memCookie_SetSessionHTTPHeaderPrefix/AUTHMEMCOOKIE_PREFIX) if Auth_memCookie_SetSessionHTTPHeader is on.

And if Auth_memCookie_SilmulateAuthBasic is set, they recieve also this $_SERVER variable :

  AUTH_TYPE = "basic"
  PHP_AUTH_USER = "user"
  PHP_AUTH_PW = "password"

Apache 2.3/2.4 authn/authz model

The module add some Require/authz provider:

Sample to configure Apache v2.4 Module:

Configuration sample for using Auth_memcookie apache V2.4 module:

LoadModule mod_auth_memcookie_module modules/mod_auth_memcookie.so

<IfModule mod_auth_memcookie.c>
<Location />
    Auth_memCookie_CookieName myauthcookie
    Auth_memCookie_Memcached_Configuration --SERVER=127.0.0.1:11000

    # to redirect unauthorized user to the login page
    ErrorDocument 401 "/gestionuser/login.php"

    # to specify if the module are autoritative in this directory
    Auth_memCookie_Authoritative on
    # must be set without that the refuse authentification
    AuthType Cookie
    # must be set (apache mandatory) but not used by the module
    AuthName "My Login"
    require mcac-public
</Location>

</IfModule>

# to protect juste user authentification
<Location "/myprotectedurl">
    require valid-user
</Location>

# to protect acces to user in group1
<Location "/myprotectedurlgroup1">
    require mcac-group group1
</Location>

Apache 2.0/2.2 authn/authz model

Sample to configure Apache v2.0 Module:

Configuration sample for using Auth_memcookie apache V2.0 module:

LoadModule mod_auth_memcookie_module modules/mod_auth_memcookie.so

<IfModule mod_auth_memcookie.c>
<Location />
    Auth_memCookie_CookieName myauthcookie
    Auth_memCookie_Memcached_Configuration --SERVER=127.0.0.1:11000

    # to redirect unauthorized user to the login page
    ErrorDocument 401 "/gestionuser/login.php"

    # to specify if the module are autoritative in this directory
    Auth_memCookie_Authoritative on
    # must be set without that the refuse authentification
    AuthType Cookie
    # must be set (apache mandatory) but not used by the module
    AuthName "My Login"
</Location>

</IfModule>

# to protect juste user authentification
<Location "/myprotectedurl">
    require valid-user
</Location>

# to protect acces to user in group1
<Location "/myprotectedurlgroup1">
    require group group1
</Location>

Releases notes

News in v2.0

News in v1.2

News in v1.1.1