<-
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
ModuleIdentifier:auth_dacs_module
SourceFile:mod_auth_dacs.c
Compatibility:Requires Apache versions Apache 2.2.Y, Y ≥ 2, or Apache 2.4.Z, Z ≥ 3

Summary

This module supports user authentication and access control on web service requests through DACS. Most DACS functionality is implemented by 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_auth* in Apache 2.2, mod_auth_*, mod_authn_*, mod_authnz_*, and mod_authz_* in Apache 2.4, as well as many contributed modules. DACS can co-exist with these modules and even leverage their authentication functionality.

In brief, this is how the pieces fit together:

Most of the work is performed by dacs_acs. The mod_auth_dacs module primarily acts as "glue" between Apache and dacs_acs. If the request was denied by dacs_acs, 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 are passed.

The Apache <Location> (or <LocationMatch>) and <Directory> (or <DirectoryMatch>) directives are used to indicate those requests 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 Apache (e.g., through 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.

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
# Note: For Apache 2.4, instead use:
# Require dacs-authz
    AuthDACS dacs-acs
</Location>

<Location /secure>
    AllowOverride AuthConfig
    AuthType DACS
    Require valid-user
# Note: For Apache 2.4, instead use:
# Require dacs-authz
    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.

Note

Starting with Apache 2.4.2, the directive Require dacs-authz (case-sensitive) must be used instead of Require valid-user. Contrary to the Apache documentation, the AuthName directive is in general not necessary with mod_auth_dacs, except where the DACS documentation explicitly states that it is needed. An AuthType DACS directive should be used, even when DACS has been configured to use its built-in HTTP Basic or Digest Authentication feature.

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.2 and 2.4 do not provide mechanisms to do this cleanly. 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.

top

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

top

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.

top

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.

top

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.

top

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
# Note: For Apache 2.4, instead use:
# Require dacs-authz

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

    AllowOverride AuthConfig

top

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.

top

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.

top

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 possible for sensitive information, such as passwords, to be logged.