Apache Module mod_authz_dbd

Available Languages: en

Description:	Group Authorization and Login using SQL
Status:	Extension
Module Identifier:	authz_dbd_module
Source File:	mod_authz_dbd.c
Compatibility:	Available in Apache 2.2 and later

Summary

This module provides authorization capabilities so that authenticated users can be allowed or denied access to portions of the web site by group membership. It also provides database/backend login/logout in conjunction with mod_authn_dbd.

Topics

Database Login
Client Login
Configuration Example

Database Login

In addition to the standard authz function of checking group membership, this module provides database Login/Logout capability. Specifically, we can maintain a logged in/logged out status in the database, and control the status via designated URLs (subject of course to users supplying the necessary credentials).

This works by defining two special Require types: Require dbd-login and Require dbd-logout. For usage details, see the configuration example below.

Client Login

In conjunction with server login/logout, we may wish to implement clientside login/out, for example by setting and unsetting a cookie or other such token. Although this is not the business of an authz module, client session management software should be able to tie its operation in to database login/logout. To support this, mod_authz_dbd exports an optional hook that will be run whenever a user successfully logs into or out of the database. Session management modules can use the hook to implement functions to start and end a client session.

Configuration Example


# DBD Configuration
DBDriver oracle
DBDParams "dbname=apacheauth user=apache pass=xxxxxx"

DBDMin  4
DBDKeep 8
DBDMax  20
DBDExptime 300

<Directory /usr/www/my.site/team-private/>
   # authn with mod_authn_dbd
   AuthType Basic
   AuthName Team
   AuthBasicProvider dbd
   AuthDBDUserPWQuery "SELECT pass FROM authn WHERE user = %s AND login = true"

   # Require dbd-group and authz_dbd implementation
   Require dbd-group team
   AuthzDBDQuery "SELECT group FROM authz WHERE user = %s"

   # When a user fails to authn/authz, invite them to login
   ErrorDocument 401 /team-private/login-form.html

   <Files login.html>
      # Don't require that we're already logged in!
      AuthDBDUserPWQuery "SELECT pass FROM authn WHERE user = %s"

      # dbd-login action executes a query to set our own state
      Require dbd-login
      AuthzDBDQuery "UPDATE authn SET login = true WHERE user = %s"

      # Return user to referring page (if any) on successful login
      AuthzDBDLoginToReferer On
   </Files>

   <Files logout.html>
      # dbd-logout action executes a query to set our own state
      Require dbd-logout
      AuthzDBDQuery "UPDATE authn SET login = false WHERE user = %s"
   </Files>
</Directory>

AuthzDBDAuthoritative Directive

Description:	Sets whether authorization will be passed on to lower level modules
Syntax:	`AuthzDBDAuthoritative On\|Off`
Default:	`AuthzDBDAuthoritative On`
Context:	directory
Status:	Extension
Module:	mod_authz_dbd

Setting the AuthzDBDAuthoritative directive explicitly to Off allows group authorization to be handled by another authz module if the userID is not in any authorized dbd-group. If there are any groups specified, the usual checks will be applied and a failure will give an Authentication Required reply.

So if a userID appears in the database of more than one module; or if a valid Require directive applies to more than one module; then the first module will verify the credentials; and no access is passed on; regardless of the AuthAuthoritative setting.

A common use for this is in conjunction with one of the auth providers; such or mod_authn_file. Whereas this DBD module supplies the bulk of the user credential checking; a few (administrator) related accesses fall through to a lower level with a well protected .htpasswd file.

By default, control is not passed on and an unknown group will result in an Authentication Required reply. Not setting it thus keeps the system secure and forces an NCSA compliant behaviour.

AuthzDBDLoginToReferer Directive

Description:	Determines whether to redirect the Client to the Referring page on successful login or logout if a `Referer` request header is present
Syntax:	`AuthzDBDLoginToReferer On\|Off`
Default:	`AuthzDBDLoginToReferer Off`
Context:	directory
Status:	Extension
Module:	mod_authz_dbd

In conjunction with Require dbd-login or Require dbd-logout, this provides the option to redirect the client back to the Referring page (the URL in the Referer HTTP request header, if present. When there is no Referer header, AuthzDBDLoginToReferer On will be ignored.

AuthzDBDQuery Directive

Description:	Specify the SQL Query for the required operation
Syntax:	`AuthzDBDQuery SQL-Query`
Context:	directory
Status:	Extension
Module:	mod_authz_dbd

The AuthzDBDQuery specifies an SQL query to run. The purpose of the query depends on the Require directive in effect.

With Require dbd-group, it specifies a query to look up groups for the current user. This is the standard functionality of other authz modules such as mod_authz_file and mod_authz_dbm. In this case it will typically take the form
AuthzDBDQuery "SELECT group FROM groups WHERE user= %s"
With Require dbd-login or Require dbd-logout, it will never deny access, but will instead execute an SQL Query designed to log the user (who must already be authenticated with mod_authn_dbd) in or out. Such a query will typically take the form
AuthzDBDQuery "UPDATE authn SET login = true WHERE user = %s"

AuthzDBDRedirectQuery Directive

Description:	Specify a query to look up a login page for the user
Syntax:	`AuthzDBDRedirectQuery SQL-Query`
Context:	directory
Status:	Extension
Module:	mod_authz_dbd

Specifies an optional query to use after successful login (or logout) to redirect the user to a page, which may be specific to the user. Such a query will take the form
AuthzDBDRedirectQuery "SELECT userpage FROM userpages WHERE user = %s"

Note that AuthzDBDLoginToReferer takes precedence if both are set.