mod_auth_cookie_mysql: Cookie based authentication with MySQL for Apache Webserver

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
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

Download

top

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

Source Code:
- module for apache 1.3: mod_auth_cookie_mysql1_0.9.tar.gz
- module for apache 2: mod_auth_cookie_mysql2_1.0.tar.gz
Debian Packages (Maintained by Sébastien Gallet):
- Debian Sarge package for apache 2 (i386) : libapache2-mod-auth-cookie-mysql_0.5-1_i386.deb
  (Attention: old version, 0.5 !)

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 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.