Commit 83beaeac authored by David G Andersen's avatar David G Andersen

The documentation for the auth_mysql apache module, in convenient

readable format. :)
parent 0e4befb7
Apache authentication module for MySQL v2.20
============================================
Maintainer: Zeev Suraski <bourbon@netvision.net.il>
What's New?
-----------
There were quite a few fixes and changes that warranted jumping from 2.11
to 2.20. First, there were a couple of bugs that were fixed - namely,
with users who belonged to more than one group, and with with the
scrambled/encrypted passwords directives.
Apart from those fixes, two new directives that correspond to two new
functionalities were added. First, it is now possible to instruct the module
to disconnect from the SQL server after every authentication request. It is
still not possible to authenticate using more than one SQL server host, but
it is possible to prevent all of the SQL links from staying alive all the time.
Note that as far as I see it, there's no reason to use this option, and there
are reasons against it - but still, it seemed to bother some people, so I
added it.
Second - the code now has a fairly general encryption scheme support. Right
now, only the three original encryption types are supported (no encryption,
DES crypt and MySQL's encryption), but it's now extremely easy and general
to add support for new encryption types. Also, it's now possible to instruct
the module to try more than one encryption method in each authentication job.
E.g., you may want to allow both plaintext and crypt passwords in the database.
As far as downwards incompatible changes are concerned - there's one major
downwards incompatible change, which is a total renaming of the directives.
The 2.0x and 2.1x directive names were based on the original mod_auth_msql
directive names, and were extremely inconsistent and messed up in my opinion.
A very simple script is bundled with this distribution, that converts any of
your old .htaccess files to use the new directive names. This script requires
the 'replace' utility, that is bundled with MySQL. The script name is
'update_htaccess_files.sh', and will convert any .htaccess files under the
current directory and its subdirectories. If your Apache per-directory
configuration file name isn't '.htaccess', edit this script and change
the name accordingly.
Last but not least, the package now comes with a configure script that allows
you to set your MySQL installation directory, as well as your Apache
installation directory. It also supports the easy to use Apache 1.3.x module
configuration, even though it's still 100% Apache 1.2.x compatible. Thanks
goes to Rasmus Lerdorf for helping me on this one.
General
-------
This module is originally based on the MySQL-patched mod_auth_msql.c, but the
truth is, very little (if any) remains from the previous
mod_auth_msql.c/mod_auth_mysql.c. Since MySQL can handle lots of simultaneous
connections easily (unlike mSQL), I've more or less rebuilt the module from
the bottom up to keep the SQL link alive in between hits. I've also cleaned
up the code (mostly be deleting it and writing it in another way), dumped the
large static query buffers in favour of pool-allocated memory, and possibly
some other stuff.
Who shouldn't use it
--------------------
Somebody who uses more than one MySQL *server* to authenticate users, from
within the same apache process. This isn't possible right now, and as far as
I'm concerned, wouldn't be possible in the near future (one SQL link per httpd
is how it works now).
Who should use it
-----------------
Everybody else, and especially on a busy site.
Installation notes
------------------
Run the configure script, and then make, and follow the instructions.
The configure script defaults to look for MySQL in /usr/local,
and for Apache in /usr/local/etc/httpd. If you have a different
setup, you can override these defaults using --with-mysql-dir
and --with-apache=dir, respectively. For example:
./configure --with-mysql=/usr/local/mysql --with-apache=/usr/local/apache
Note that you must have MySQL installed prior to installing mod_auth_mysql.
You can obtain MySQL from http://www.tcx.se.
How do I use it?
----------------
Read the 'USAGE' file supplied with this package,
or take a look at http://bourbon.netvision.net.il/mod_auth_mysql/
Revision history
---------------
v2.20 - A user that was a member of more than one group couldn't be
authenticated using group authentication. Fixed.
(thanks to Jonathan Roy for reporting that bug).
- Turning scrambled passwords on and then encrypted passwords off, or
turning encrypted passwords on and then scrambled passwords off,
would result in both scrambled and encrypted passwords being off.
Fixed.
- Changed all directive names to be nicer and more consistent. See the
USAGE file for specific information.
- Added Auth_MySQL_Encryption_Types directive to allow for nicer setting
of which encryption types to use, and multiple encryption types.
- Added Auth_MySQL_Non_Persistent directive to allow non-persistent
links to the MySQL server.
- ONLY_ONCE is no longer supported. This was a compile-time macro that
wasn't even documented, and made no much sense anyway. The
user:password SQL table should really have one row per user, and the
username should most probably be a primary or otherwise unique key.
- The module should now be possible to compile on platform that does
not have the crypt() function. The Crypt_DES encryption type
will not be available.
v2.11 - Fixed a bug in the scrambled password implementation. It probably had
no symptoms whatsoever with just about any C compiler in existence,
but still, from a pure C-language-definition point of view, it was
incorrect. Thanks for Marschall Peter for pointing that out.
- Fixed a small typo in the string escaping routine, which caused it
never to work right. I guess nobody uses strings that need to be
escaped anywhere :) Thanks to Brent Metz for noticing that.
v2.10 - Added the necessary include file to make Apache 1.3b6 happy
- Added some information to the USAGE file, loosely describing how to
go about implementing multiple groups for a single user.
v2.09 - Made the full error message of the MySQL server appear in case of a
failed connect
- Added Auth_MYSQL on/off directive, so that it'll be easily possible
to turn the MySQL authentication on/off serverwide or for a specific
directory.
- Fixed the groups authentication code so that it'll work with one
query and multiple groups. For good this time :)
- Some code cleanups
v2.08 - Fixed a checking for NULL password fields (won't work, but won't
crash either)
- Fixed logic and possible crashes with the new scrambled password
initialization routines
- Optimized a couple of routines
- Changed the query that is used to check user groups - users that belong
to multiple groups should have multiple rows in the groups table
v2.07 - Fixed a bug in the escaping routine - strings that required escaping
were not properly detected (thanks to Marschall Peter for noticing
the bug!)
- Added Auth_MYSQL_ScrambledPassword - boolean flag to instruct the
module to assume that passwords are scrambled using MySQL's password()
function (by Marschall Peter <Peter.Marschall@gedos.de>).
v2.06 - Rearranged some code to allow for a successful apache 1.3beta
compilation.
Please note that this is *untested*, I only got it to compile, I haven't
actually tried to run apache 1.3.
v2.05 - Change the check for 'mysql server has gone away' to be case insenitive
v2.04 - Added USAGE file that explains how to use this module thoroughly
v2.03 - Added compilation information :)
v2.02 - Changed version number from 1.x to 2.x, so that people know that this is
really newer than mod_auth_mysql v1.4 :)
Added a tiny note at the top of the source file.
v1.02 - Fixed a bug in the groups code
v1.01 - Fixed a segmentation fault bug in case of aborted hits
v1.00 - Initial, unversioned release.
Disclaimer
----------
This comes with no warranty of any kind whatsoever, including but not limited to everything you can think of,
and everything your lawyers can think of.
Bugs
----
If you found a bug in this mod_auth_mysql ("it works for me"), please let me know. This module has
been in active use in my former company for quite a while (and still is), and plenty of people
are using it, including on fairly busy sites, so bugs are not all that likely anymore, but they're
always possible.
Author
------
Email: Zeev Suraski <bourbon@bourbon.netvision.net.il>
Please register this module at http://bourbon.netvision.net.il/mod_auth_mysql/
This file assumes you've successfully compiled mod_auth_mysql, and you're now
trying to figure out how to use it :)
mod_auth_mysql, like other apache authentication modules, is used in order
to protect pages with username/password. The unique thing is that the
passwords and usernames is stored in a MySQL database for much quicker access.
Also, unlike the previous implementation of the module, SQL links are kept
alive in between hits to acheive even better performance.
Protecting a directory with a username/password is simple, and involves
two steps:
1. Creating the necessary SQL information.
2. Telling apache to protect the page using that information.
Creating the necessary SQL information
--------------------------------------
You would generally need one table, that contains 3 fields - username,
password, and group. In some cases the group wouldn't be required and
in others you may want to have extra fields in that table for other usages.
If you already have the database and table with the necessary fields, you
can skip to the next phase. Otherwise:
1. Create a database to store the authentication table, e.g.:
prompt> mysqladmin create http_auth
NOTE: You *don't* have to have this table in a seperate database, you
can skip creating a new database and use an existing database if it fits
your needs.
2. Create the auth table, e.g.:
prompt> mysql http_auth
mysql> create table mysql_auth (
-> username char(25),
-> passwd char(25),
-> groups char(25),
-> primary key (username)
-> );
NOTE 1: You *don't* have to use a new table for this purpose; You can
use existing fields in existing tables for this purpose.
NOTE 2: All of the above names (the table name and field names) are the
defaults the module looks for.
They CAN be overriden using directives.
NOTE 3: The username/passwd information and username/group information
can be stored in seperate tables (using different table names
for the password table and group table). This is useful if you
want some users to have multiple (or no) groups. In order to do
that, you should have one row in the username/passwd table, and
multiple rows in the username/group table, one for each group
the user is in.
3. Insert the information into the table. Both the username and group fields
are plaintext, whereas the password field should contain standard UNIX DES
encrypted passwords (this can be overriden using a directive as well, but
the default is using encrypted passwords).
Telling apache to protect the page using that information
---------------------------------------------------------
1. If you're using a MySQL server other than localhost, and/or you want to
specify a different user than the httpd user when accessing the MySQL
server, and/or you need to specify a password for that user, you'd need
to add the following line somewhere in your httpd.conf (doesn't really
matter where):
Auth_MySQL_Info <host> <user> <password>
This information can *only* be specified in the server's httpd.conf, since
it's used server-wide.
2. If you're going to use mainly one MySQL database for all of your pages,
you should probably add the following line to your httpd.conf as well:
Auth_MySQL_General_DB <database_name>
The database can be set on a per-directory basis using a different
directive in .htaccess, as mentioned later in this file.
3. Create (or update) a file named .htaccess inside the directory you would
like to protect. Here are a few simple .htaccess files (full
documentation about the various possible non-MySQL-auth specific directives
can be obtained from the apache docs):
(I) Protect your company's financial information (not recommended to put on
the web:) to any user that's in the SQL auth table:
AuthName My Company's Financial Information <-- the realm name, use some informative name
AuthType Basic <-- keep it that way
require valid-user <-- allow any valid user to access
(II) Allow access only to specific users:
AuthName My Company's Financial Information <-- the realm name, use some informative name
AuthType Basic <-- keep it that way
require user johndoe devnull <-- let only johndoe and devnull access
(III) Allow only members of group 'executives' access the information:
AuthName My Company's Financial Information <-- the realm name, use some informative name
AuthType Basic <-- keep it that way
require group executives <-- allow only members of this group to access
Note that with Apache 1.3, you would have to encapsulate the AuthName
with double quotes if it contains spaces, e.g.
AuthName "My Company's Financial Information"
4. Take a look at the following directives, and see if you need to
use any of them:
Auth_MySQL_DB <database_name>
The MySQL database to use. If you havne't specified Auth_MySQL_General_DB
earlier, in the httpd.conf file, you *must* specify this directive.
Example:
Auth_MySQL_DB http_auth
Auth_MySQL_Password_Table <password_table_name>
The name of the MySQL table that contains user:password pairs. By default
it is 'mysql_auth'.
Auth_MySQL_Group_Table <group_table_name>
The name of the MySQL table that contains user:group pairs. Typically
you'd probably just want to triplets of user:password:group inside
the same table, but you can use a different table for user:group pairs
if you'd like. By default it is 'mysql_auth'.
Auth_MySQL_Username_Field <username_field_name>
The field name of the username field. By default it is 'username'.
Auth_MySQL_Password_Field <password_field_name>
The field name of the password field. By default it is 'passwd'.
Auth_MySQL_Group_Field <group_field_name>
The field name of the group field. By default it is 'groups'.
Auth_MySQL_Empty_Passwords on/off
Whether or not to allow empty passwords. If the password field is empty
(equals to '') and this is set to 'On', users would be able to access
the page by just specifying their username without any password checking.
If this is 'Off', they would be denied access. Default: On.
Auth_MySQL_Encryption_Types [Plaintext, Crypt_DES, MySQL]
This directive tells the authentication module which encryption type(s)
to use. It overrides the Auth_MySQL_Scrambled_Passwords and
Auth_MySQL_Encrypted_Passwords directives if it appears after them.
More than one encryption type may be specified, to instruct the module to
check each password through more than one encryption scheme. For example,
Auth_MySQL_Encryption_Types Plaintext Crypt_DES
will instruct the module to check each password both as-is, and through
DES crypt.
Auth_MySQL_Encrypted_Passwords on/off
Whether or not to use standard UNIX DES encrypted passwords. If turned
on, the module expects the password field to contain standard UNIX DES
encrypted passwords (2 bytes salt plus 11 bytes encrypted data). If
turned off, the passwords are expected to be plaintext, unless
Auth_MySQL_Scrambled_Passwords is turned on. Use of this directive
is not encouraged - use Auth_MySQL_Encryption_Types instead.
Default: On.
Auth_MySQL_Scrambled_Passwords on/off
Whether or not to use passwords scrambled with MySQL's password() routine.
If turned on, the module expects the password field to contain standard
passwords encrypted with the SQL password() function in MySQL. If turned
off, the passwords are expected to be plaintext, unless
Auth_MySQL_Encrypted_Passwords is turned on. Use of this directive is
not encouraged - use Auth_MySQL_Encryption_Types instead. Default: Off.
Auth_MySQL_Authoritative on/off
Whether or not to authenticate using other authentication modules after
the user is successfully authenticated by the MySQL auth module.
Default: On (i.e., don't pass on the request).
Auth_MySQL_Non_Persistent on/off
By turning on this option, you can tell the module to close the MySQL
link after each authentication request. Note that I can't think of any
good reason to do it, unless your platform makes MySQL go crazy when
it has plenty of simultaneous threads (bad handling of file descriptor
may cause that). In my opinion, one should increase the maximum number
of simultaneous threads in MySQL and keep this option Off. Default: Off.
Auth_MYSQL on/off
Whether or not to enable MySQL authentication. If it's off, the MySQL
authentication will pass on the authentication job to the other
authentication modules (e.g. the flatfile auth module). If it's on,
and a database name was specified - the MySQL module will be used for
authentication.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment