Apache Module mod_authn_dbi

Compilation

mod_authn_dbi uses the "configure/make/make install" mechanism common to many Open Source programs. Most of the dirty work is handled by either configure or Apache's apx utility. If you have built apache modules before, there shouldn't be any surprises for you.

Before you can begin compiling mod_authn_dbi, you will need a working installation of Apache 2.1-dev (any earlier version, including Apache 2.0.x will NOT work) and libdbi with at least one driver installed. If this is not already the case, go to their homesites as given above, install them and then come back here.

The interesting options you can pass to configure are:

• --with-apxs=/path/to/apache/dir/bin/apxs

  This option is used to specify the location of the apxs utility that was installed as part of apache. Specify the location of the binary, not the directory it is located in.

• --with-dbi=/path/to/libdbi/installation/dir
  or
  --with-includes=/path/to/libdbi/includes
--with-libs=/path/to/libdbi/lib
  

  The installation directory of libdbi. Beneath this directory there should be directories "lib" and "include" that contain the library and its headers. Alternatively, you can specify the other two, if libraries and includes are installed into different directories. Usually, specifying the first should suffice.

Call configure with your site-specific values and then "make" and "make install" as usual. The module will be installed in the module directory of your Apache installation.

Integration into Apache

Again mod_authn_dbi behave like your average next-door Apache module. Just add

LoadModule authn_dbi_module modules/mod_authn_dbi.so

to your httpd.conf as usual and restart Apache.

Upon startup, mod_authn_dbi will read in all drivers that are in the driver directory of libdbi. This directory is a default vaule compiled into libdbi (usually <installation prefix of libdbi>/lib/dbd/). If you want mod_authn_dbi to look into a different directory, have a look at the AuthnDbiDriverDir directive.

Preparing the Database

Of course, before you can use mod_authn_dbi, you will need to decide which database to use and create it if it does not already exists. mod_authn_dbi is pretty flexible and tries to impose as few requirements on the structure of the table as possible. If you already have user records in some table, chances are good that you will be able to use these records without having to change the structure of the table. Also, migration from file-based authentication (htpasswd,htdigest) is very easy.

We will describe the "default requirements" and the first level of customization here. Most of these requirements will change, once you start to fiddle with the AuthnDbiPasswordQuery directive, most of these requirements will change or go away.

Starting from scratch...

The default structure that mod_authn_dbi expects is a database called "AuthDB", which contains a table called "Users". In this table, it expects two string (VARCHAR or similar) columns "Username" and "Password" containing the usernames and for each of them the password in plaintext.

mod_authn_dbi will, by default to access this database on through the MySQL driver on host "localhost" and login there as user "root" without a password.

Something like you would get with:

CREATE table Users (Username VARCHAR(32), Password VARCHAR(32));

In the first step of customization, you can change the values for driver, host, user, password, database, table, column names and the password format to match a table in an existing database.

So, let's continue with...

Basic configuration of mod_authn_dbi

The configuration of mod_authn_dbi consists of two main parts. First, you configure one or more configuration sets. Then, you use these configuration sets in any number of basic or digest authentication realms.

At the moment, there is only one global option (AuthnDbiDriverDir), which you will probably not need at first, so we will start with the section about mod_authn_dbi server configs. All options that are used for the creation of server configs take the name of the server config as first parameter and then some value(s) behind that. Server configs are created implicitly, each time the module encounters a configuration directive with a config name that it has not seen yet.

For example:

AuthnDbiTable Server1 MyDatabaseTable

This says that the config with the name "Server1" should use the table "MyDatabaseTable" instead of the default "AuthDB", you get the idea...

Creating Configuration sets

	AuthnDbiDriver         Server1  mysql
	AuthnDbiHost           Server1  mycoolcatserver.com
	AuthnDbiUsername       Server1  MyUser
	AuthnDbiPassword       Server1  MyPass
	AuthnDbiName           Server1  MyDatabaseName
	AuthnDbiTable          Server1  MyDatabaseTable
	AuthnDbiUsernameField  Server1  theUserNameField
	AuthnDbiPasswordField  Server1  PasswordField
	AuthnDbiIsActiveField  Server1  IsActiveField
	AuthnDbiConnMin        Server1    3
	AuthnDbiConnSoftMax    Server1   12
	AuthnDbiConnHardMax    Server1   20
	AuthnDbiConnTTL        Server1  600
      

Defining Authentication realms

mod_authn_dbi registers itself as an Authentication Provider with the name "dbi" in Apache's Authentication Framework. It provides authenticating users with both Basic and Digest Authentication. Basic Authentication is by far the more common one, but you might want to consider Digest Authentication as well, since it is more secure than Basic Authentication and supported by all major browsers. To the user, both will look the same, i.e. appear as a dialog box requesting username and password. The two mechanisms just differ in the way data is exchanged in the background between browser and webserver.

To use a configuration set (in one of Apaches central configuration files), you will need the AuthnDbiServerConfig directive from mod_authn_dbi plus at least AuthType, AuthDigestProvider or AuthBasicProvider (depending on the value you pass to AuthType) and Require and a directory-level container like <Location> or <Directory> to use them in.

First, decide wheter to use Basic or Digest Authentication and set AuthType to Digest or Basic accordingly. Then, set the matching provider directive (AuthDigestProvider or AuthBasicProvider) to "dbi", this links mod_authn_dbi to this authentication section. Next, you need to tell mod_authn_dbi which configuration set to use by setting AuthnDbiServerConfig to the name of the set. Configuration sets can be used for both Basic and Digest Authentication (even at the same time) and for any number of authentication sections. Now, this authentication section is linked to a specific configuration set within mod_authn_dbi. If you specify AuthnDbiServerConfig more than once, the last value will be used.
Finally, you specify who may access the section with Require to actually use this authentication section when a client request comes in. (Well, most of this is not really that different from what is is in 2.0 and earlier). Authentication realms that use mod_authn_dbi can also be used from a .htaccess file as usual. Just leave off the container directives.

Below you find two example configurations, one for Basic and one for Digest Authentication.

	<Directory  "/path/to/htdocs/to/be/area_1_protected">
	  AuthType Digest
	  AuthName "digest authn_dbi testing area"
	  AuthDigestProvider dbi
	  AuthnDbiServerConfig Server1
	  Require valid-user
	</Directory>
      

      <Directory  "/path/to/htdocs/to/be/area_2_protected">
        AuthType Basic
        AuthName "basic authn_mysql testing area"
        AuthBasicProvider dbi
        AuthnDbiServerConfig Server1
        Require valid-user
      </Directory>
      

Advanced configuration of mod_authn_dbi

As mentioned earlier, mode_authn_dbi is very flexible. You can do all kinds of nifty things, with (or even without) your user database, especially with the AuthnDbiPasswordQuery.

More kung-foo will be added here soon...

If you have done something nifty with mode_authn_dbi we would appreciate it if you contributed it as an example for this section....

Pooling of database connections

To handle incoming requests in an efficient but also performant way, mod_authn_dbi organizes connections to the database server(s) into pools, with one connection pool per configuration set. It opens and closes connections depending on the load the webserver is experiencing at a given time. The pooling mechanism is built on the Resource List Routines of libapr-util (and you probably had to download separately) and is similar to the way Apache manages the number of server processes or threads.

When first started, mod_authn_dbi creates a mimimum number of connections to the database server before accepting client requests. When a client request comes in that needs to be Authenticated, a database connection is requested from the connection pool of the matching configuration set. The connection is used for authentication and then released back into the pool of idle connections. If no idle connection is available and the number of connections in the pool has not reached its hard maximum, a new connection to the database is created and used. After use, it is not destroyed but added as idle connection to the pool of connections.
Each configuration contains soft maximum value and a time-to-live (TTL) value (e.g. 600 seconds). If more than the soft maximum number of idle database connections is in a given pool, connections that have been idle for longer than the time-to-live value will be closed until a value not larger than the soft maximum is reached.

These four directives can be used to control the various limits:

• AuthnDbiConnMin - The minimum (and initial) number of connections.
• AuthnDbiConnSoftMax - The soft maximum value of connections.
• AuthnDbiConnHardMax - The hard maximum of connections.
• AuthnDbiConnTTL - The time-to-live in seconds.