Apache HTTP Server Version 2.2
Apache HTTP Server Version 2.2
| Description: | User authentication and access control based on DACS (the Distributed Access Control System) |
|---|---|
| Status: | External |
| Module | auth_dacs_module |
| Source | mod_auth_dacs.c |
| Compatibility: | Requires Apache versions 2.0.X, X ≥ 51, or Apache 2.2.Y, Y ≥ 2 |
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.
AuthDACS AddDACSAuth SetDACSAuthMethod
SetDACSAuthConf SetDACSAuthSiteConf SetDACSAuthEnvBuffer SetDACSAuthPostBuffer SetDACSAuthDebugHere 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.
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.
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.
| 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).
| 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.
| 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.
| 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.
| 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:
The following directive should be included within the same context as
AuthDACS
to enable .htaccess files:
AllowOverride AuthConfig
| 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.
| 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.
| 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.
It is not impossible for sensitive information, such as passwords, to be logged.