Apache Module: mod_auth_cookie_mysql1/2

Current version: 0.5
Attention: This is a beta version !! Use and test it at your own risk :))

• Introduction
  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 (mod_auth_cookie_mysql2).
  
  
• Description:
  Basic auth is a standard authentication method in the internet. Two big disadvantages are, that on every request the username and password are transmitted to the webserver and there is no possibility to log out without closing the webbrowser.
  With this module you can authorize your users with cookies. An external script (perl, C, php, ..) sets the cookie and this module checks it against a MySQL database. The username/password combination is only one time transferred to the webserver when the external authenticator script (which sets the cookie) checks the user data. The generated cookie consists only of random session data. 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 and nobody can spy the username/password. Since the cookie is only random session data nobody can "hack" the system by manipulating the cookie values. Additionally you can add checks for session expiry and the correct remote ip on the server side.
  
  
• Features:
  • 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
    
• PostgreSQL version
  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

• Installation of mod_auth_cookie_mysql2:
  • Compiled directly in apache2: configure your apache as always, add the following lines:
    LDFLAGS="-L/usr/local/mysql/lib/" LIBS="-lz -lmysqlclient" INCLUDES="-I/usr/local/mysql/include" \
    ./configure --with-module=aaa:<pathtofile>/mod_auth_cookie_mysql2.c
    (or whereever your MySQL library and include files are)
    
  • There is also a possibility to compile mod_auth_cookie_mysql1 as a run-time loadable module with apxs:
    apxs -q -lmysqlclient -lz -L /usr/local/mysql/lib/ -I/usr/local/mysql/include <path to module>/mod_auth_cookie_mysql2.c
    (or whereever your MySQL library and include files are)
    
    Then copy the .so file to your apache modules directory and modify your httpd.conf:
    LoadModule auth_cookie_mysql1_module modules/mod_auth_cookie_mysql2.so
    ...
    AddModule mod_auth_cookie_mysql2.c
    
• Installation of mod_auth_cookie_mysql1:
  • Compiled directly in apache1.3: configure your apache as always, add the following lines:
    LDFLAGS="-L/usr/local/mysql/lib/" LIBS="-lz -lmysqlclient" INCLUDES="-I/usr/local/mysql/include" \
    ./configure --add-module=<path to module>/mod_auth_cookie_mysql1.c
    (or whereever your MySQL library and include files are)
    
  • There is also a possibility to compile mod_auth_cookie_mysql1 as a run-time loadable module with apxs:
    apxs -q -lmysqlclient -lz -L /usr/local/mysql/lib/ -I/usr/local/mysql/include <path to module>/mod_auth_cookie_mysql1.c
    (or whereever your MySQL library and include files are)
    
    Then copy the .so file to your apache modules directory and modify your httpd.conf:
    LoadModule auth_cookie_mysql1_module modules/mod_auth_cookie_mysql1.so
    ...
    AddModule mod_auth_cookie_mysql1.c

• Run-Time Configuration:

The are a hand of configuration directives you can set:


• Name	Values	Description	Required
  CookieAuth	{on|off}	Activates this module	YES
  CookieAuth_DBhost	<hostname> or <IP>	Hostname or IP of the host where MySQL is running on	YES
  CookieAuth_DBName	<dbname>	Name of the database in MySQL	YES
  CookieAuth_DBTable	<tbname>	Tablename in database	YES
  CookieAuth_DBUser	<username>	Username for MySQL connection	YES
  CookieAuth_DBPassword	<password>	Password for MySQL connection	YES
  CookieAuth_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
  CookieAuth_SessnameField	<fieldname>	Field in MySQL table where session name is stored in. This is the name of the cookie !	YES
  CookieAuth_SessvalField	<fieldname>	Field in MySQL table where session value (this is the value which is compared with the cookies value) is stored in	YES
  CookieAuth_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
  CookieAuth_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
  CookieAuth_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
  CookieAuth_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

  
  
  
• Examples:
  • MySQL table:
    

• CREATE TABLE `inter_sessions` ( `sessname` varchar(32) NOT NULL default '', `sesskey` varchar(32) NOT NULL default '', `expiry` int(11) NOT NULL default '0', `remoteip` varchar(15) NOT NULL default '', `username` varchar(32) NOT NULL default '', UNIQUE KEY `sessname` (`sessname`) ) TYPE=MyISAM;

  
  
• Apache config file:
  

• <Directory /www/secure> AuthName "SomeName" AuthType Cookie CookieAuth on CookieAuth_DBhost localhost CookieAuth_DBName authdb CookieAuth_DBUser mike CookieAuth_DBPassword pass1234 CookieAuth_DBtable apacheauth CookieAuth_UsernameField username CookieAuth_SessnameField sessname CookieAuth_SessvalField sesskey CookieAuth_RemoteIPField remoteip CookieAuth_FailureURL /error.html require user bill thimo </Directory>

  
  
  
• PHP Code to set the cookie:
  

• <?php $ip=getenv("REMOTE_ADDR"); $sessname="abc"; $sesskey="abc"; $expires=time()+60*60*24*30; // expires in one month $cookie=setcookie($sessname,$sesskey,$expires,"/","www.mydomain.com"); // set cookie for www.mydomain.com $query="INSERT INTO $tbname '$sessname','$sesskey','$expires','$ip','mark'"; // this adds the data into a MySQL database ?>

• Bugs:
  If you have found a bug, please report them to me!
  
  
• License:
  This module is licensed under the Apache License
  
  
• Download module for apache 2:
  mod_auth_cookie_mysql2_0.5.tar.gz
  
  
• Download module for apache 1.3:
  mod_auth_cookie_mysql1_0.5.tar.gz
  
  
• Changelog:
  • 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




• Contact:
  If you have further questions or bug reports, please feel free to contact me:
  E-Mail: apache-mod at digithi.de
  Website: http://home.digithi.de/digithi/dev/mod_auth_cookie_mysql.html