Introduction top


This is a rewrite of the mod_auth_cookie_mysql module for apache 1.3. Some features were added, some were forgotten.
The module is available for apache 1.3 (mod_auth_cookie_mysql1) and apache 2.x (mod_auth_cookie_mysql2). The module is tested with mysql 3.x/4.x and and 5.0.x.

The current version of of this module is version 0.9 (for apache 1.3) / version 1.0 (for apache 2).

If you want to receive a message when a new version is released, please leave your e-mail address in the announcements field at the top left of this site. This will register you to a moderated mailing list. Your e-mail address, will be kept private, it isn't visible to other users and it will not be distributed.

There is also a PostgreSQL version of this module for apache 2. It is maintained by Takashi Matsuo and availabe on his website:
http://mars.shehas.net/software/mod_auth_cookie_pgsql2.html

 
Description top


Basic auth is a standard authentication method in the internet. But there are two big disadvantages. With every request the username and password are transmitted to the webserver. Additionally there is no possibility to log out without closing the webbrowser.

With this module you can authorize your users with cookies. An external script sets the cookie and this module checks it against a MySQL database. The username/password combination is transferred only once to the webserver when the external authenticator script (which sets the cookie) checks the user data.

The generated cookie may be full of random session data. That random data is compared with the data in the SQL database and is internally associated with the username that was authenticated before.

So you can, for example, authenticate the user and set the cookie in a ssl connection and then use the cookie in a non-ssl environment. Since only random cookie data without confidential information is stored in that cookie, nobody can spy the username/password.

Additionally nobody can "hack" the system by manipulating the cookie values because they are only valid for one session. Additional checks for session expiry and the correct remote ip can be activated in this module.

This module is perfectly suited for Single-Sign-On (SSO).

Diagram top


The following diagrams show two typical use-cases.

Login:
The login information are sent to a script (the mod_auth_cookie_mysql 1/2 module is not involved) which verifies all data and generates a random cookie. The client data like username, cookie and optionally expiry information or the remote IP is stored in a database and the random cookie ist sent to the browser of the client.

Request website:
If the client wants to access a protected site, the mod_auth_cookie_mysql 1/2 module tests the cookie sent by the browser against the database and, if permitted, allows the webserver to send the requested site back.

 
Features top

  • Fake Basic Auth with cookies
  • Cookie only consists of random session data, no username or password
  • Can check expiry information stored in database against cookie
  • Can check if the remote IP is equal to the IP stored in database
  • Can be used for Single-Sign-On (SSO).

 
Installation top

  • Installation of mod_auth_cookie_mysql2:
    • Please read the INSTALL file which is included in the source archive file.
  • Installation of mod_auth_cookie_mysql1:
    • Please read the INSTALL file which is included in the source archive file.

 
Configuration top

 

The following configuration directives are available in this module. Please refer to the config samples page for some configuration samples.

Name Values Description Required Ver. 1 Ver. 2
AuthCookieSql on|off Activates this module YES
AuthCookieSql_DBhost <hostname> or <IP> Hostname or IP of the host where MySQL is running on YES
AuthCookieSql_DBName <dbname> Name of the database in MySQL YES
AuthCookieSql_DBTable <tbname> Tablename in database YES
AuthCookieSql_DBUser <username> Username for MySQL connection YES
AuthCookieSql_DBPassword <password> Password for MySQL connection YES
SqlCookieAuth_DBPersistent on|off Default: off. Make database connection persistent, if you have a heavy loaded webserver this option increases the performance of the module. OPTIONAL
AuthCookieSql_UsernameField <fieldname> Field in MySQL table where username of session is stored. This username is displayed as the "Remote Username" variable "REMOTE_USER" in Apache YES
AuthCookieSql_SessnameField <fieldname> Field in MySQL table where session name is stored in. This is the name of the cookie ! YES
AuthCookieSql_SessvalField <fieldname> Field in MySQL table where session value (this is the value which is compared with the cookies value) is stored in YES
AuthCookieSql_CookieName <name> If this option is set, only the cookie with this name is searched. If it is not set, this module searches all cookies the browser sencs and checks the name against the values in die Sessname field and its value against Sessval field. OPTIONAL
AuthCookieSql_ExpiryField <fieldname> When this option is set, the current time of the webserver is compared against this field in the database. This value is: time in seconds since 01.01.1970 (unix timestamp). OPTIONAL
AuthCookieSql_RemoteIPField <fieldname> When this option is set, the remote address of the connected client is checked against this field. Only when the remote IP and the stored IP are eqal the client can authorize OPTIONAL
AuthCookieSql_FailureURL <url> Normally, when the authorization failed, the client gets a "AUTHORIZATION REQUIRED" message from the webserver. When this option is set, you can redirect the client to another URL.
Attention: This is a normal "redirect" for the browser, if you want a internal redirect (the browser doesn't see the url where he is redirected to) you can use the ErrorDocument directive: "ErrorDocument 401 /someerrorfile.html"		 OPTIONAL
SqlCookieAuth_AdditionalSql <sql term> With this parameter you can add an SQL term to the SQL query string. The term is appended after the WERE clause. OPTIONAL

Please refer to the config samples page for some configuration samples.

 
Download top


You can download the current version by clicking on one of the following links:

 
Changelog top

  • Version 0.2 - 28.07.2004
    • initial public release
  • Version 0.3 - 03.08.2004
    • code fixup
  • Version 0.4 - 05.04.2005
    • bug fix: internal redirect with failure_url doesn't work correctly, changed redirect routine to do a "302 MOVED PERMANENTLY"
    • bug fix in mod_auth_cookie_mysql2: added a null pointer in auth_commands array and removed a "module go" debug message
  • Version 0.5 - 01.06.2005
    • bug fix: mysql_connections were left open after authentication failures - thanks to Jason Haar
  • Version 0.6 - 20.12.2005
    • enhancement: module now reads [client] section in my.cnf and additionally [ModAuthCookieMysql] section (if exists)
    • bug fix: module didn't accept sessname/sessval pairs if sessnames were equal - thanks to Valerii Valeev
  • Version 0.7 - 04.01.2006
    • bug fix: return-code of function check_valid_cookies not initialized - thanks to Valerii Valeev
  • Version 0.8 - 26.03.2007
    • bug fix: fixed small memory leak
    • enhancement: code cleanup
  • Version 0.9 - 23.03.2007
    • enhancement: persistent connections are possible now (only in version 2)
    • enhancement: code cleanup
    • change: name of the configuration options were slightly modified
  • Version 0.9a (version 2) - 02.05.2007
    • bugfix: Fixed tiny typo in Makefile. "make install" should work without problems now on every machine.
  • Version 1.0 (version 2) - 18.06.2009
    • bugfix: Fixed another tiny typo in Makefile.
    • enhancement: AuthCookieSql_AdditionalSQL parameter added.

 
Contact top


If you have a question or if you have found a bug please contact me!

You can post into the forum (anonymous posts are allowed!) or you can send me an e-mail.

If you want to receive a message when a new version is released, please leave your e-mail address in the announcements field at the top left of this site. This will register you to a moderated mailing list. Your e-mail address, will be kept private, it isn't visible to other users and it will not be distributed.