Apache HTTP Server Version 2.2

Apache > HTTP Server > Documentation > Version 2.2 > Modules

# Apache Module mod_auth_dacs

Description: | User authentication and access control based on DACS (the Distributed Access Control System)
Status: | External
Module<A0>Identifier: | auth_dacs_module
Source<A0>File: | mod_auth_dacs.c
Compatibility: | Requires Apache versions 2.0.X, X ≥ 51, or Apache 2.2.Y, Y ≥ 2

### Summary

This module allows DACS (and perhaps other authentication and access control systems, eventually) to perform user authentication and access control on web service requests. In the current implementation, DACS functionality is obtained through a suite of programs that are external to the web server.

Similar but much more limited functionality is provided by Base and Extension Apache modules, such as `mod_access` and `mod_auth` (both in Apache 2.0), `mod_auth*` in Apache 2.2, as well as many external modules. DACS can co-exist with these modules and even leverage their authentication functionality.

When Apache receives a request for a resource that has been configured to be under the control of the module (via "`AuthType` `DACS`"), `mod_auth_dacs` is called. The module invokes an external program to determine whether access should be granted, passing it information about the request over a pipe. The external program returns information, also over a pipe, to `mod_auth_dacs`, instructing it how to proceed. If the request was denied, the user might receive a `403 Forbidden` response or might be redirected. If the request was granted, Apache processing will continue almost as if DACS were not there. For computational resources (e.g., CGI programs and servlets), certain DACS-related environment variables will be passed.

The Apache `<Location>` (or `<LocationMatch>`) directive is used to indicate those URLs that require DACS-controlled access. Depending on the organization of the URL namespace, one or perhaps two such specifications may be all that is required. With two specifications, there would likely be one directive for the common root URL of all DACS-wrapped CGI programs (or servlets) and another for the common root URL of all static content.

If certificate-based authentication is required, Apache should be configured so that `StdEnvVars` and `ExportCertData` are enabled in an appropriate `SSLOptions` directive:

        SSLOptions +StdEnvVars +ExportCertData

If servlets are under the control of DACS, proper operation requires that `mod_jk` be configured to pass variables defined by DACS to Tomcat so that they are available to the servlet. At present, the following `mod_jk` directives (which appear in, or are included in, the Apache configuration file) are necessary to do this:

        <IfModule mod_jk.c>
            JkEnvVar DACS_FEDERATION         NONE
            JkEnvVar DACS_JURISDICTION       NONE
            JkEnvVar DACS_ACS_JURISDICTION   NONE
            JkEnvVar DACS_ROLES              NONE
            JkEnvVar DACS_USERNAME           NONE
            JkEnvVar DACS_CONSTRAINT         NONE
            JkEnvVar DACS_DEFAULT_CONSTRAINT NONE
            JkEnvVar DACS_COOKIE             NONE
            JkEnvVar DACS_MOD_AUTH_DACS      NONE
        </IfModule mod_jk.c>

(JkEnvVar is described here.)

From a servlet, the values of these variables can be obtained through the `getAttribute()` method, invoked on an `HttpServletRequest` object. For example:

    Object username = req.getAttribute("DACS_USERNAME");
    out.println("roles = " + req.getAttribute("DACS_ROLES"));

For a complete description of DACS, please refer to the individual technical documents.

### Directives

### See also

- Authentication, Authorization and Access Control
- `AuthName`
- `AuthType`
- `Location`
- `Require`

Here is an example of a (partial) configuration:

`

    AddDACSAuth dacs-acs
        /usr/local/dacs/bin/dacs_acs "-u myhost.foo.baz"
    AddDACSAuthConf dacs-acs
        /usr/local/dacs/federations/myhost/dacs.conf
    SetDACSAuthMethod dacs-acs external
    SetDACSAuthEnvBuffer 32768
    SetDACSAuthPostBuffer 32768
    SetDACSAuthDebug On

    <Location /cgi-bin/dacs>
        AllowOverride AuthConfig
        AuthType DACS
        Require valid-user
        AuthDACS dacs-acs
    </Location>

    <Location /secure>
        AllowOverride AuthConfig
        AuthType DACS
        Require valid-user
        AuthDACS dacs-acs
    </Location>

`

This example creates two DACS-wrapped areas of the server's (or virtual server's) URL space. The DACS `cgi-bin` directory must always be under the control of DACS. The example also puts the URL space under `/secure` under the control of DACS.

### Security

Improper installation, configuration, or use of DACS may leave your system open to various kinds of attacks and exploits. In particular, ensure that file ownership and modes are appropriate for run-time accessible DACS files. Always test your Apache/DACS configuration before making it operational. Keep up-to-date with the latest releases of DACS and the third-party packages that it uses.

### Note

By default, DACS makes `POST` parameters available to its access control rules. It does this by making a copy of the data stream and parsing it according to the MIME headers sent with the request. But because a `POST` data stream can potentially be very large and of indefinite length, a maximum length must be imposed. If the actual length of the stream exceeds the current limit, the copied data will be truncated. As a result, some parameters may not be passed from the web server to DACS, and the "last" argument may be erroneous. Starting with release 1.4.22, if a problem occurs while DACS is parsing `multipart/form-data`, it will discard all parameters passed in this way (any query parameters will still be available). Refer to the SetDACSAuthPostBuffer directive and dacs_acs(8) for additional information.

This module uses some non-standard tricks to sample the `POST` data stream; Apache 2.0 and 2.2 do not provide mechanisms to do this properly. A consequence of this is that `mod_auth_dacs` cannot sample the `POST` data stream if the data coming from `mod_ssl` has been compressed, for example. In this event, SetDACSAuthPostBuffer should be set to zero and DACS access control rules will not be able to examine `POST` method arguments.

## SetDACSAuthMethod Directive

Description: | Controls how the module performs access control processing. At present, the only method implemented uses an external program
Syntax: | `SetDACSAuthMethod keyword external|internal`
Default: | `external`
Context: | server config, virtual host
Override: | Not applicable
Status: | Extension
Module: | mod_auth_dacs

The `SetDACSAuthMethod` directive selects between a DACS implementation internal to the web server and an external implementation of DACS. The selection is associated with a configuration label, keyword. The external method is the default (the internal method is not currently available).

## SetDACSAuthConf Directive

Description: | Supplies DACS with the name of the `dacs.conf` configuration file to use.
Syntax: | `SetDACSAuthConf keyword pathname`
Default: | `Specified when DACS is built.`
Context: | server config, virtual host
Override: | Not applicable
Status: | Extension
Module: | mod_auth_dacs

The `SetDACSAuthConf` directive provides the full pathname of the DACS configuration file to use. The pathname is passed to DACS services as the environment variable `DACS_CONF`. If the directive is not present, then DACS components will attempt to fall back to use a compile-time specified file. If no DACS configuration file can be located, DACS components will not function. The selection is associated with a configuration label, keyword.

## SetDACSAuthSiteConf Directive

Description: | Supplies DACS with the name of the `site.conf` configuration file to use.
Syntax: | `SetDACSAuthSiteConf keyword pathname`
Default: | `Specified when DACS is built.`
Context: | server config, virtual host
Override: | Not applicable
Status: | Extension
Module: | mod_auth_dacs

The `SetDACSAuthSiteConf` directive provides the full pathname of the DACS site-wide configuration file to use. This file is optional and DACS will proceed normally if it does not exist; if it does exist, however, it must be readable by DACS. The pathname is passed to DACS services as the environment variable `DACS_SITE_CONF`. If the directive is not present, then DACS components will attempt to fall back to use a compile-time specified file. The selection is associated with a configuration label, keyword.

## AddDACSAuth Directive

Description: | Configures how the external program (normally, dacs_acs) will be invoked.
Syntax: | `AddDACSAuth keyword pathname [command-line-arg-string]`
Default: | `None`
Context: | server config, virtual host
Override: | Not applicable
Status: | Extension
Module: | mod_auth_dacs

When configuration label keyword is associated with an external method, the `AddDACSAuth` directive associates a full pathname, with an optional command line argument string, with a keyword that is used later in the configuration file. The pathname is that of the DACS program (or a compatible program) which will be invoked with the given arguments.

## AuthDACS Directive

Description: | Enables DACS access control processing.
Syntax: | `AuthDACS keyword`
Default: | `None`
Context: | directory, .htaccess
Override: | Not applicable
Status: | Extension
Module: | mod_auth_dacs

The `AuthDACS` directive enables the DACS authentication and access control configuration associated with the previously-defined configuration label keyword. Authoritative authentication and access control will be delegated to DACS.

This directive is required to enable DACS.

The following directives should be included within the same context as `AuthDACS`:

`

        AuthType DACS
        Require valid-user

`

The following directive should be included within the same context as `AuthDACS` to enable `.htaccess` files:

`

        AllowOverride AuthConfig

`

## SetDACSAuthEnvBuffer Directive

Description: | Sets the (global) size of the environment variable buffer.
Syntax: | `SetDACSAuthEnvBuffer integer`
Default: | `16384`
Context: | server config, virtual host
Override: | Not applicable
Status: | Extension
Module: | mod_auth_dacs

If DACS grants access to a CGI program, it passes information to that program through environment variables. `SetDACSAuthEnvBuffer` sets the maximum number of bytes, representing environment variable names and values, to read from DACS and pass to a CGI program. This limit also applies to information that is passed by DACS to an error handler (see ACS_ERROR_HANDLER). The integer value must not be less than 1024 or greater than 1048576.

## SetDACSAuthPostBuffer Directive

Description: | Sets the (global) size of the `POST` data stream buffer.
Syntax: | `SetDACSAuthPostBuffer integer`
Default: | `16384`
Context: | server config, virtual host
Override: | Not applicable
Status: | Extension
Module: | mod_auth_dacs

As part of performing access control on a CGI program invoked using the `POST` method (or other methods that include parameters in an entity body), DACS will examine some or all of the `POST` data stream. While there is no restriction on the length of this data stream, DACS places an upper limit on the amount of data it will examine. The `SetDACSAuthPostBuffer` sets the maximum number of bytes that will be examined. If the integer value is zero, then this sampling is turned off, otherwise the value must not be less than 1024 or greater than 1048576. If you never need DACS to make these parameters available (e.g., your access control rules do not examine them), you may turn this sampling off. If DACS has trouble decoding this data stream, its contents will be ignored, the parameters will be unavailable to subsequent DACS processing, and a warning message will logged.

## SetDACSAuthDebug Directive

Description: | Enables debugging output to the Apache logs
Syntax: | `SetDACSAuthDebug On | Off`
Default: | `On`, if compiled with DACS_DEBUG defined to be 1; otherwise, `Off`
Context: | server config, virtual host
Override: | Not applicable
Status: | Extension
Module: | mod_auth_dacs

If you are having problems with DACS or `mod_auth_dacs` in particular, set `SetDACSAuthDebug` to `On` and set Apache's `LogLevel` to the `info` or `debug` level.

### Security

It is not impossible for sensitive information, such as passwords, to be logged.