Apache HTTP Server Version 2.5

Apache > HTTP Server > Documentation > Version 2.5 > Modules

# Apache Module mod_authz_dbd

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.4 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. Similar functionality is provided by `mod_authz_groupfile` and `mod_authz_dbm`, with the exception that this module queries a SQL database to determine whether a user is a member of a group.

This module can also provide database-backed user login/logout capabilities. These are likely to be of most value when used in conjunction with `mod_authn_dbd`.

This module relies on `mod_dbd` to specify the backend database driver and connection parameters, and manage the database connections.

### Topics

- The Require Directives
- Database Login
- Client Login integration
- Configuration example
- Preventing SQL injections

### Directives

### Bugfix checklist

- httpd changelog
- Known issues
- Report a bug

### See also

- `Require`
- `AuthDBDUserPWQuery`
- `DBDriver`
- `DBDParams`

## The Require Directives ¶

Apache's `Require` directives are used during the authorization phase to ensure that a user is allowed to access a resource. mod_authz_dbd extends the authorization types with `dbd-group`, `dbd-login` and `dbd-logout`.

Since v2.4.8, expressions are supported within the DBD require directives.

### Require dbd-group

This directive specifies group membership that is required for the user to gain access.

    Require dbd-group team
    AuthzDBDQuery "SELECT user_group FROM authz WHERE user = %s"

### Require dbd-login

This directive specifies a query to be run indicating the user has logged in.

    Require dbd-login
    AuthzDBDQuery "UPDATE authn SET login = 'true' WHERE user = %s"

### Require dbd-logout

This directive specifies a query to be run indicating the user has logged out.

    Require dbd-logout
    AuthzDBDQuery "UPDATE authn SET login = 'false' WHERE user = %s"

## Database Login ¶

In addition to the standard authorization function of checking group membership, this module can also provide server-side user session management via database-backed login/logout capabilities. Specifically, it can update a user's session status in the database whenever the user visits 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 integration ¶

Some administrators may wish to implement client-side session management that works in concert with the server-side login/logout capabilities offered by this module, for example, by setting or unsetting an HTTP cookie or other such token when a user logs in or out.

To support such integration, `mod_authz_dbd` exports an optional hook that will be run whenever a user's status is updated in the database. Other session management modules can then use the hook to implement functions that start and end client-side sessions.

## Configuration example ¶

    # mod_dbd configuration
    DBDriver pgsql
    DBDParams "dbname=apacheauth user=apache pass=xxxxxx"

    DBDMin  4
    DBDKeep 8
    DBDMax  20
    DBDExptime 300

    <Directory "/usr/www/my.site/team-private/">
      # mod_authn_core and mod_auth_basic configuration
      # for mod_authn_dbd
      AuthType Basic
      AuthName Team
      AuthBasicProvider dbd

      # mod_authn_dbd SQL query to authenticate a logged-in user
      AuthDBDUserPWQuery \
        "SELECT password FROM authn WHERE user = %s AND login = 'true'"

      # mod_authz_core configuration for mod_authz_dbd
      Require dbd-group team

      # mod_authz_dbd configuration
      AuthzDBDQuery "SELECT group FROM authz WHERE user = %s"

      # when a user fails to be authenticated or authorized,
      # invite them to login; this page should provide a link
      # to /team-private/login.html
      ErrorDocument 401 /login-info.html

      <Files "login.html">
        # don't require user to already be logged in!
        AuthDBDUserPWQuery "SELECT password FROM authn WHERE user = %s"

        # dbd-login action executes a statement to log user in
        Require dbd-login
        AuthzDBDQuery "UPDATE authn SET login = 'true' WHERE user = %s"

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

      <Files "logout.html">
        # dbd-logout action executes a statement to log user out
        Require dbd-logout
        AuthzDBDQuery "UPDATE authn SET login = 'false' WHERE user = %s"
      </Files>
    </Directory>

## Preventing SQL injections ¶

Whether you need to care about SQL security depends on what DBD driver and backend you use. With most drivers you don't have to do anything : the statement is prepared by the database at startup, and user input is used only as data. But you may need to untaint your input. At the time of writing, the only driver that requires you to take care is FreeTDS.

Please read `mod_dbd` documentation for more information about security on this scope.

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

- When used with a `Require dbd-group` directive, it specifies a query to look up groups for the current user. This is the standard functionality of other authorization modules such as `mod_authz_groupfile` and `mod_authz_dbm`. The first column value of each row returned by the query statement should be a string containing a group name. Zero, one, or more rows may be returned.

      Require dbd-group
      AuthzDBDQuery "SELECT group FROM groups WHERE user = %s"

- When used with a `Require dbd-login` or `Require dbd-logout` directive, it will never deny access, but will instead execute a SQL statement designed to log the user in or out. The user must already be authenticated with `mod_authn_dbd`.

      Require dbd-login
      AuthzDBDQuery "UPDATE authn SET login = 'true' WHERE user = %s"

In all cases, the user's ID will be passed as a single string parameter when the SQL query is executed. It may be referenced within the query statement using a `%s` format specifier.

## AuthzDBDRedirectQuery Directive ¶

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

Specifies an optional SQL query to use after successful login (or logout) to redirect the user to a URL, which may be specific to the user. The user's ID will be passed as a single string parameter when the SQL query is executed. It may be referenced within the query statement using a `%s` format specifier.

    AuthzDBDRedirectQuery "SELECT userpage FROM userpages WHERE user = %s"

The first column value of the first row returned by the query statement should be a string containing a URL to which to redirect the client. Subsequent rows will be ignored. If no rows are returned, the client will not be redirected.

Note that `AuthzDBDLoginToReferer` takes precedence if both are set.