Apache Module mod_auth_dacs

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:

• Build and install the mod_auth_dacs module for the versions of DACS and Apache that you are using;
• Configure mod_auth_dacs using the new Apache directives it provides (described below);
• Configure Apache authentication/authorization directives so that mod_auth_dacs is associated with web resources you want DACS to protect;
• When Apache receives a request for a resource that you have associated with mod_auth_dacs, the module is invoked, it collects various information associated with the request, and it creates a new external process (the DACS authorization checking program, dacs_acs, invoked with arguments that you have configured) that is passed the collected information using a pipe;
• dacs_acs reads the information provided by mod_auth_dacs, consults your DACS configuration, determines how the request should be handled, and tells mod_auth_dacs what it should do;
• mod_auth_dacs reads the response provided by dacs_acs and tells Apache what it should do.

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>

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.

Copyright (c) 2003-2014 Distributed Systems Software.
Refer to the LICENSE file that accompanies the DACS distribution for licensing information.

$Id: mod_auth_dacs.html 2728 2014-09-12 20:14:29Z brachman $