| DACS.CONF(5) | DACS Formats Manual | DACS.CONF(5) |
NAME¶
dacs.conf - DACS configuration files and directivesDESCRIPTION¶
These files are part of the DACS suite. Nearly all DACS services and utilities consult a configuration file when they start up. Such things as the per-jurisdiction locations of access control files and log files, authentication processing, error handling, and run-time limits are specified in the configuration file. The recommended name for this file is dacs.conf and the DACS documentation will generally refer to it by that name. Site-wide configuration, which is optional, is typically put in a file named site.conf. Both files are XML documents, and consist of various sections, clauses, and directives, not unlike the httpd.conf configuration file used by Apache. Different federations and jurisdictions running on the same host may share these files or each might have its own separate configuration file; the former is more common since it reduces duplication and helps to prevent inconsistencies.•The DACS distribution includes a
prototype version of site.conf, found in conf/site.conf-std, which establishes
reasonable defaults based on DACS build-time arguments. It may need
some customization for the local environment. By default, DACS looks
for the site configuration file in federations/site.conf, relative to the
DACS installation directory; conf/site.conf-std can be copied there and
any necessary customizations made.
•A command to validate and display
configuration, dacsconf(1)[1] is available, as is a simple web service,
dacs_conf(8)[2]. Until you become comfortable with configuration files,
consider running one of them after making changes. A fatal configuration error
will prevent DACS from running and access to all DACS-wrapped
resources will be denied.
Locating dacs.conf and site.conf¶
The locations of dacs.conf and site.conf may be specified with the web server configuration, in an environment variable, through a command line flag, or at compile time. A single configuration file can provide directives for multiple DACS jurisdictions. For example, if a machine is hosting more than one DACS jurisdiction, they can each use the same DACS binaries.
Path interpolation is available using a syntax and method similar to
Apache's mod_vhost_alias[7] module. Interpolation is
always performed to determine the locations of several resources used by
DACS, such as dacs.conf and site.conf, and with DACS's
LOG_FILE[8] directive, regardless of the manner in which the location
is provided to DACS. It is applied whether the location of dacs.conf is
specified using the -u command line flag or the Apache (
mod_auth_dacs) SetDACSAuthConf directive, for instance.
The functionality can also be accessed using the pathname()[9] function.
The strings that may be interpolated into the pathname are obtained from the
execution environment, in particular the URI authority information (based on
Apache's SERVER_NAME and SERVER_PORT environment
variables), the URI service path (described below), build-time configuration,
and the applicable Jurisdiction section's distinguishing URI.
Interpolation is controlled by printf-like format specifiers, as follows:
%%
will expand the path to /usr/local/apache2/conf/dacs/example.com/dacs.conf. The
command line flag:
specifies the location of the configuration file to be
/usr/local/dacs/dss.8080/dacs.conf.
The %u specifier interpolates the URI service path, or portions thereof, which
is the string HTTP_HOST/REQUEST_URI (without a query component).
When a DACS service is invoked as a CGI, this will be the usual case;
the URI service path is undefined if either of those environment variables is
unavailable, however.
Insert a literal percent character
%a
Insert the application name, which is obtained
from the filename component of the program's argv[0] argument
%bA
Insert the absolute pathname of the root of
the Apache installation directory, specified at build-time (
APACHE_HOME)
%bD
Insert the absolute pathname of the root of
the DACS installation directory, specified at build-time (
DACS_HOME)
%p
Insert the port number of the virtual host
(SERVER_PORT)
% N.M
Insert one or more components of the name, or
a substring of those subcomponents. N and M are numbers used to
select part of the SERVER_NAME string (a domain name or IP address).
N selects from the dot-separated components of SERVER_NAME,
while M selects characters within whatever N has selected.
M is optional and defaults to zero if it isn't present. The dot must be
present if and only if M is also present. If N or M are
greater than the number of parts available, a single underscore is
interpolated. The numbers are interpreted as follows:
0 or 1+ or -1+
%s[ N.M]
the whole name
1
the first part
2
the second name
-1
the last part
-2
the next-to-last part
2+
the second and all following parts
-2+
the next-to-last and all preceding parts
This is a synonym for % N.M,
with %s being equivalent to %0.
Note
In cases where the character following %s should not be interpreted as part of
the format, it must be escaped (e.g., %s%2).
%u[ N.M]
This functions like the %s specifier except
that it is applied to the URI service path (described below) for the current
request, which has slash-separated components. %u is equivalent to %u0. For
example, if the URI service path is "example.com/metalogic", %u1
would be "example.com", %u2 would be "metalogic", and %u0
(and %u and %u1+) would be "example.com/metalogic".
Note
In cases where the character following %u should be interpolated verbatim and
not interpreted as part of the specifier, it must be escaped (e.g., %u%2).
%U[ N.M]
This functions like the %u specifier except
that it is applied to the applicable Jurisdiction section's[10]
distinguishing URI (described below). %U is equivalent to %U0.
Note
Other format specifiers
•Because the applicable Jurisdiction
section is not known until after configuration processing has started, this
specifier cannot be used to describe the location of configuration
files.
•In cases where the character following
%U should be interpolated verbatim and not interpreted as part of the
specifier, it must be escaped (e.g., %U%2).
If a % is followed by an unrecognized
specifier, that character is inserted verbatim.
Other characters
All other characters are inserted
verbatim
For example, if SERVER_NAME is dss.example.com and SERVER_PORT is
8080, then the Apache directive:
SetDACSAuthConf dacs-acs "/usr/local/apache2/conf/dacs/%2+/dacs.conf"
-c /usr/local/dacs/%1%.%p/dacs.conf
File Format¶
dacs.conf is an XML document that conforms to Configuration.dtd[11]. A dacs.conf file consists of an optional Default section followed by zero or more Jurisdiction sections. Either type of section consists of DACS directives or XML elements, called clauses, that contain DACS directives. There are three kinds of clauses: Auth clauses, Roles clauses, and Transfer clauses. Just to give its flavour, here's an incomplete dacs.conf file:<Configuration>
<Default>
LOG_FILE "${Conf::DACS_HOME}/logs/logfile"
FEDERATION_DOMAIN "example.com"
FEDERATION_NAME "ROOT"
LOG_LEVEL "notice"
SSL_PROG "/usr/local/dacs/bin/sslclient"
</Default>
<!-- Configuration of first jurisdiction -->
<Jurisdiction uri="dss.example.com">
JURISDICTION_NAME "DSS"
<Auth id="auth_name">
URL "https://dss.example.com/cgi-bin/dacs/local_unix_authenticate"
STYLE "pass"
CONTROL "sufficient"
</Auth>
</Jurisdiction>
<!-- Configuration of second jurisdiction -->
<Jurisdiction uri="dss.example.com/foo">
JURISDICTION_NAME "FOO"
</Jurisdiction>
<!-- Configuration of third jurisdiction -->
<Jurisdiction uri="metalogic.example.com">
JURISDICTION_NAME "METALOGIC"
</Jurisdiction>
</Configuration>
The Default Section¶
The purpose of the Default section in dacs.conf is to establish default values for directives that tend to be shared amongst all of the Jurisdiction sections that appear in dacs.conf. The Default section is optional; if present, it must appear before any Jurisdiction section in dacs.conf. The site.conf file, if it exists, consists of only a Default section. Directives that are common to all of a site's dacs.conf files might be put in site.conf. Any configuration directive or clause may appear in the Default section.The Jurisdiction Section¶
Each Jurisdiction section contains configuration directives that are associated with a particular jurisdiction. These directives override those found anywhere else, as described below.Section Merging and Directive Evaluation¶
The three types of configuration sections are merged as follows. First, directives and clauses that appear in the site.conf Default section are overridden by those that appear in the dacs.conf Default section. The resulting directives and clauses are in turn overridden by those that appear in the selected Jurisdiction section. Usually, site.conf will contain the standard default directives that come with the installed release of DACS, the dacs.conf Default section will contain directives common to all of the jurisdictions defined on the host that are in the same federation, and each Jurisdiction section will contain directives specific to that jurisdiction. The exception to this merging procedure is directives in the Stack category[12]. Instead of overriding, these directives accumulate. The order in which directives (but not clauses) appear within a section is not significant, even with respect to references to variables in the Conf namespace[13], with the exception of the EVAL directive[14]. Only after directives in the three sections are merged are their right-hand sides evaluated (again, with the exception of EVAL[14]) to determine the value of each directive. Therefore, if a directive appears in both the Default section and the Jurisdiction section, the instances in the Default section will not have their directive values evaluated; they will simply be discarded (with the exception of the Stack directive category).
As a special case, if a directive is given the special value returned by
undef()[15], the instance of the directive is deleted. This provides a
way to conditionally include or exclude a directive depending on the execution
environment. For example, this directive increases the debugging level for
DACS web services but not for commands:
Note
Because of the way configuration files are currently processed, the check for
directive category satisfaction happens before right-hand side
evaluation. This means that in any particular section only one instance of a
Required1 directive may appear, even if just one would be included after the
evaluation step.
LOG_LEVEL ${Env::REMOTE_ADDR:e} ? "TRACE" : undef()
It is a fatal error to reference an undefined variable unless the e or ?
modifier flag is used in the variable reference. Recursive variable references
are detected and result in a fatal error. If a directive ends up not being
evaluated, it does not matter whether its right-hand side is invalid (or would
be if evaluated).
Note
When a fatal error occurs during configuration processing, a DACS web
service tries to terminate gracefully. But because directives (including error
handling directives) may not have been processed correctly, or even at all,
there is no guarantee that an error handler (such as one defined by the
ACS_ERROR_HANDLER[16] directive) will be invoked or a requested output
format will be honoured during abnormal termination. A non-zero exit process
status is always returned.
Consider the following configuration excerpts:
After configuration processing, the directive LOG_LEVEL will be set to
"trace", and the variable ${Conf::LOG_LEVEL} will have that
value during configuration processing.
Here are some excerpts from dacs.conf:
When computing the VFS directive's value in the example above, the values of the
FEDERATIONS_ROOT variable (determined at build-time) and the
FEDERATION_DOMAIN and JURISDICTION_NAME configuration directives are
interpolated. Directives in site.conf may reference configuration variables
that are defined in dacs.conf.
Given the configuration:
All four VFS directives will be in effect, but they will be ordered such that
the first one in the Jurisdiction section is at the top of the stack, the
second one in that section is next on the stack, the directive in the
dacs.conf Default section follows, and the one from site.conf is last.
In site.conf: LOG_LEVEL "debug" In dacs.conf: Default section: LOG_LEVEL "notice" Jurisdiction section: LOG_LEVEL "trace"
Default section:
FEDERATION_DOMAIN "example.com"
FEDERATION_NAME "EXAMPLE"
Jurisdiction section:
JURISDICTION_NAME "DEMO"
VFS "[abc]dacs-fs:${Conf::FEDERATIONS_ROOT}/${Conf::FEDERATION_DOMAIN}\
/${Conf::JURISDICTION_NAME}/abc"
In site.conf: VFS "[dtds]dacs-fs:/usr/local/dacs/www/dtd-xsd" In dacs.conf: Default section: VFS "[dtds]dacs-fs:/usr/local/dacs/dtd-xsd" Jurisdiction section: VFS "[dtds]dacs-fs:/export/dacs/dtd-xsd" VFS "[xxx]dacs-fs:/export/dacs/xxx"
Jurisdiction Section Selection¶
DACS web services and commands do not have any federation or jurisdiction information compiled into them, so that a single set of DACS binaries can be shared by many jurisdictions (e.g., by multiple real or virtual web servers on the same host, or using NFS or some other file sharing mechanism). But it means that (most) web services and commands need a run-time mechanism to determine "who they are" - which federation and jurisdiction are they acting on behalf of? For web services, this usually depends on the server name, hostname, port, scheme, URI path, some other context associated with the request, or a combination of these things. But it is sometimes most convenient to specify a jurisdiction name and have DACS work out what the request URIs to that jurisdiction look like, if it needs to. Most DACS web services and commands need to obtain run-time configuration information for the jurisdiction they represent. Because dacs.conf may specify the configuration of more than one jurisdiction, how do they know which Jurisdiction section they should use? In cases where DACS does not know the jurisdiction name, it searches for the correct Jurisdiction section and then determines the name of the jurisdiction; in cases where it is given the jurisdiction name, it searches Jurisdiction sections to find one with a directive that identifies the jurisdiction that it was given. The applicable Jurisdiction section to use for a particular web service request or command can be determined in a variety of ways, using:•the -u command line flag to
specify a config-uri that is matched against effective
jurisdictional URIs[17];
•the -uj command line flag to
specify a jurisdiction-name that is matched against Jurisdiction
sections' JURISDICTION_NAME directive;
•the -us command line flag to
indicate that there is only one Jurisdiction section, so that section should
be selected; or
•by matching a request URI against
effective jurisdictional URIs[17].
Command line flags are described in dacs(1)[4], as is the
DEFAULT_JURISDICTION environment variable.
These methods will be described individually shortly.
<Configuration>
<Jurisdiction uri="foo.example.com">
JURISDICTION_NAME "FOO"
FEDERATION_DOMAIN "example.com"
# And so on...
</Jurisdiction>
</Configuration>
AddDACSAuth dacs-acs /usr/local/dacs/bin/dacs_acs "-u foo.example.com"
AddDACSAuth dacs-acs /usr/local/dacs/bin/dacs_acs "-us"
AddDACSAuth dacs-acs /usr/local/dacs/bin/dacs_acs "-uj FOO"
AddDACSAuth dacs-acs /usr/local/dacs/bin/dacs_acs
<Configuration>
<Jurisdiction uri="foo.example.com">
JURISDICTION_NAME "FOO"
FEDERATION_DOMAIN "example.com"
# And so on...
</Jurisdiction>
<Jurisdiction uri="baz.example.com">
JURISDICTION_NAME "BAZ"
FEDERATION_DOMAIN "example.com"
# And so on...
</Jurisdiction>
</Configuration>
AddDACSAuth dacs-acs /usr/local/dacs/bin/dacs_acs
<Configuration>
<Jurisdiction uri="example.com/foo">
JURISDICTION_NAME "FOO"
FEDERATION_DOMAIN "example.com"
# And so on...
</Jurisdiction>
<Jurisdiction uri="example.com/baz">
JURISDICTION_NAME "BAZ"
FEDERATION_DOMAIN "example.com"
# And so on...
</Jurisdiction>
</Configuration>
AddDACSAuth dacs-acs /usr/local/dacs/bin/dacs_acs
<Configuration>
<Jurisdiction uri="example.com:443">
JURISDICTION_NAME "FOO"
FEDERATION_DOMAIN "example.com"
# And so on...
</Jurisdiction>
<Jurisdiction uri="example.com:8443">
JURISDICTION_NAME "BAZ"
FEDERATION_DOMAIN "example.com"
# And so on...
</Jurisdiction>
</Configuration>
<Configuration>
<Jurisdiction uri="*.foo.example.com">
JURISDICTION_NAME "FOO"
FEDERATION_DOMAIN "example.com"
# And so on...
</Jurisdiction>
<Jurisdiction uri="*.baz.example.com">
JURISDICTION_NAME "BAZ"
FEDERATION_DOMAIN "example.com"
# And so on...
</Jurisdiction>
</Configuration>
A Jurisdiction element must have either a uri attribute or a uri_expr attribute,
but not both. If the latter is given, it specifies an expression[18]
that is evaluated at configuration processing time. The effective
jurisdictional URI (or the jurisdiction's effective URI) is either the value
of the uri attribute or the value obtained by evaluating the uri_expr
attribute. The effective jurisdictional URI can be matched against a request's
URI or the -u flag's config-uri to find the applicable
Jurisdiction section.
The standard set of configuration variables[19] in the Conf and
Env namespace[13] (but no others) are accessible during
evaluation of uri_expr. Consider this partial configuration:
Here, the effective jurisdictional URI is the value of the SERVER_NAME
environment variable.
Note
The effective jurisdictional URI has the following syntax:
<Jurisdiction uri_expr="${Env::SERVER_NAME}">
•The environment established for a
DACS web service and the environment of a DACS command are
typically different, so programs run from the command line may fail if
uri_expr references an undefined variable.
•Any error that occurs during evaluation
of uri_expr is fatal.
•One application of the uri_expr
attribute is constructing a generic or "template" Jurisdiction
section. For example, if multiple domain names need to map to the same
jurisdiction, a uri_expr like the following can be used:
<Jurisdiction uri_expr="regmatch(${Env::SERVER_NAME}, '(foo.example.com)|(baz.example.com)')">
uri -> [scheme-spec] [domain-spec] [":" port-spec] [path-spec] scheme-spec -> "http://" | "https://" domain-spec -> domain-name | "*." domain-name | IP-address port-spec -> positive-integer | positive-integer "," port-spec path-spec -> "/" path-segment | "/" path-segment path-spec
Whether the Jurisdiction section is selected based on the -u flag's
explicit config-uri or the request URI provided to DACS through
environment variables, the effective jurisdictional URIs are matched against
the provided URI.
An effective jurisdictional URI has the following semantics for matching against
the provided URI:
Tip
While configuration of the uri attribute may appear to be complex, its value
will typically be a simple hostname, or a simple hostname followed by a
jurisdiction-distinguishing initial path element, as in the example above. The
flexible syntax allows jurisdictions to be associated with requests based on
port numbers, use of SSL, etc. and lets dissimilar requests map to the same
jurisdiction.
For example, given the example configuration[20] above, if the request
URL is:
then the second Jurisdiction section will be used.
If the request URL is:
then the first Jurisdiction section will be used.
If a DACS utility is invoked with the command line flag -u
metalogic.example.com, the third Jurisdiction section will be used.
•If uri specifies the http scheme, the
provided UR must not have used SSL; if uri specifies the https scheme, the
provided URI must have used SSL; if neither scheme is specified, the scheme is
immaterial.
•The optional domain-spec
specifies a domain name to match (case-insensitively) against the provided
URI. If the initial component of domain-spec is "*.", then
only the components that follow it in domain-spec need to match the
domain name in the provided URI. For example, *.example.com matches
example.com and foo.baz.example.com. If the domain-spec is omitted, the
domain name in the provided URI is immaterial.
Note
The matching algorithm does not consider domain names that map to the same IP
address (i.e., aliases) to be equivalent.
The domain-spec can be an IP address, but in this case the provided URI
must also use an IP address for the two to match. That is, no mapping between
IP addresses and domain names is performed.
•The optional port-spec consists
of one or more port numbers, any one of which must match the one specified
explicitly (i.e., not by default) in the provided URI. If the provided
URI does not contain a port, it will not match any port-spec. Port
numbers are separated by a comma (with no embedded whitespace). If the
port-spec is omitted, the port number in the provided URI is
immaterial.
•The optional path-spec must
match the prefix of the provided URI's path component. Matching is
case-sensitive and is performed on corresponding path-segment
elements.
The matching algorithm first rejects any Jurisdiction section having an
effective jurisdictional URI that does not satisfy the scheme-spec or
the domain-spec. It looks for the section that contains a matching
port-spec and that has the longest matching path-spec; the first
such section will be selected. If no such section is found, however, it looks
for the section that does not contain a port-spec and that has the
longest matching path-spec; the first such section will be selected. It
is a fatal error if no section can be selected.
The applicable Jurisdiction section can be selected by providing the
jurisdiction's name. The -uj flag's jurisdiction-name argument
is compared against the unevaluated value of each section's
JURISDICTION_NAME directive until the first exact string match is found; the
section containing the directive will be selected.
Note
Because the unevaluated value of the directive is used, if the value of a
JURISDICTION_NAME is not a simple string, this option will not work unless
jurisdiction-name is that expression, not its value. Appropriate quotes
are implied around jurisdiction-name, so they should be omitted on the
command line.
For example, given the (partial) configuration file entry:
the command line argument " -uj DEMO" would select that
jurisdiction section. If instead JURISDICTION_NAME were an expression that
evaluated to the string DEMO, the argument would not select that
jurisdiction section.
<Jurisdiction uri="demo.example.com"> JURISDICTION_NAME "DEMO" ... </Jurisdiction>
If dacs.conf contains a single Jurisdiction section, the -us flag can be
used to select it without regard to the jurisdiction's name or effective
jurisdictional URI. This can be particularly useful during testing.
Should there be more than one Jurisdiction section when this flag is used, a
fatal error will occur.
Regardless of how the Jurisdiction section is selected, that section's effective
jurisdictional URI is matched against the -u flag's config-uri,
if given, or the request URI according to the method described for
Jurisdiction Selection by URI[21]. The resulting string is called the
distinguishing URI. This string is another way of identifying the selected
Jurisdiction section and can be used for string interpolation[22]. It
is also related to the shared attribute used in access control
rules[23].
For example, if the request URI is http://foo.example.com/a/b/c and the matching
effective jurisdictional URI is *.example.com/a/b, then the distinguishing URI
is foo.example.com/a/b.
Directives¶
Each directive consists of a directive name, followed by whitespace (spaces and/or tabs), followed by its value. Directive names are case-sensitive and comprised of printable characters, except the space character, and are upper case. A directive value is an expression or sequence of expressions ( dacs.exprs(5)[18]) that is evaluated at run time during configuration processing. Here are some directives that are equivalent (on a Saturday):AUTH_FAIL_DELAY_SECS 2
AUTH_FAIL_DELAY_SECS "2"
AUTH_FAIL_DELAY_SECS 1 + 1
AUTH_FAIL_DELAY_SECS strftime("%a") eq:i "Sat" ? 2 : 17
ACS_ERROR_HANDLER "902 'Access denied, \ user not authenticated'"
Some directive names end with a * character. By convention, this means that the
directive's value will be evaluated a second time, in the context of a
particular module or service request, but only if the directive value is
actually needed. This allows a configuration directive to reference a variable
that cannot be instantiated until normal configuration file processing has
been performed, for instance. The values of these directives usually appear
within single quotes so that they initially evaluate to the string between the
quotes.
Consider this INIT*[24] directive, which might appear within an Auth
clause[25]:
Because the directive's value appears within single quotes, the quoted
expression is not evaluated during the first scan of the directive (or more
accurately, it evaluates to an unquoted expression); this is as it should be
because the value of the referenced variable is not known at that time, nor
has it been determined whether the directive will even be needed. Later, if
the Auth clause containing this directive is used, the variable's value is
presumably known and the formerly quoted expression is evaluated, yielding a
final value for the directive.
INIT* '${Auth::CURRENT_USERNAME} = "goa\\" . ${Auth::CURRENT_USERNAME}'
After section merging[26] is performed, some directives must be specified
while others are optional. Some may appear at most once and others may be
repeated. The following labels are used to categorize directives:
Required1:
Note
A directive marked Deprecated will be removed in a future version and should not
be used.
Some directives have more complicated constraints on their usage; they might be
allowed only in certain contexts or are required only in certain situations
(e.g., directives associated with proxied operation are only required if that
mode of operation is being used).
Required directives must be present and assigned a valid value, although the
validity of a value is only checked if the directive is actually used. It is
okay to define directives that are not used; for example, directives related
to InfoCards may appear in a configuration file even if InfoCard support is
not enabled at the time DACS is built. Some configuration directives
may appear multiple times, others only once. The order in which configuration
directives appear within a section is not usually significant, although it may
be in cases where the directive is repeated (e.g., ACS_ERROR_HANDLER) and for
clauses (e.g., the Auth clause).
Note
Directives that expect to be assigned a value of yes, no, on, or off recognize
these keywords case-insensitively.
Directives of this type must be defined and
appear only once after merging.
Required1-C:
Under certain conditions, these directives
must be defined and appear only once after merging, otherwise they need not
appear. For example, some directives are required if and only if the module
that requires them is configured.
Required:
These directives must always be specified at
least once after merging, and may be repeated.
Optional1:
These directives may appear at most once after
merging.
Optional:
These directives may appear zero or more times
after merging.
Stack:
This is like the Optional type, in that the
directive may appear multiple times in any section, except the usual section
merging algorithm is not used. Instead, all occurrences of the directive in
the Jurisdiction section, then in the Default section of dacs.conf, and then
in site.conf will be "stacked", in the order in which they appear in
each section. Selection is dependent on the particular directive, which will
effectively search the directives in the Jurisdiction section first to find an
applicable directive, then search the directives in the Default section of
dacs.conf if necessary, and finally search site.conf if necessary.
The following general directives are provided. If present, they must appear
within any Default section or Jurisdiction section, but outside of any
clauses.
Directive Index:
1.ACCEPT_ALIEN_CREDENTIALS (Optional1)
2.ACS_ACCESS_TOKEN_ENABLE (Optional1)
3.ACS_ACCESS_TOKEN_LIFETIME_LIMIT
(Required1-C)
4.ACS_ACCESS_TOKEN_LIFETIME_SECS
(Required1-C)
5.ACS_AUTHENTICATED_ONLY (Optional1)
6.ACS_CREDENTIALS_LIMIT (Optional1)
7.ACS_EMIT_APPROVAL (Optional1)
8.ACS_ERROR_HANDLER (Stack)
9.ACS_FAIL (Optional1)
10.ACS_INACTIVITY_LIMIT_SECS (Optional1)
11.ACS_POST_BUFFER_LIMIT (Optional1)
12.ACS_POST_EXCEPTION_MODE (Optional1)
13.ACS_PRE_AUTH (Optional)
14.ACS_SUCCESS (Optional)
15.ACS_TRACK_ACTIVITY (Optional1)
16.ADMIN_IDENTITY (Optional)
17.ALLOW_HTTP_COOKIE (Optional1)
18.AUTH_AGENT_ALLOW_ADMIN_IDENTITY
(Optional1)
19.AUTH_CREDENTIALS_ADMIN_LIFETIME_SECS
(Optional1)
20.AUTH_CREDENTIALS_DEFAULT_LIFETIME_SECS
(Required1)
21.AUTH_ERROR_HANDLER (Stack)
22.AUTH_FAIL (Optional1)
23.AUTH_FAIL_DELAY_SECS (Optional1)
24.AUTH_SINGLE_COOKIE (Optional1)
25.AUTH_SUCCESS (Optional)
26.AUTH_SUCCESS_HANDLER (Optional1)
27.AUTH_TRANSFER_EXPORT (Optional)
28.AUTH_TRANSFER_TOKEN_LIFETIME_SECS
(Optional1)
29.COMPAT_MODE (Optional1)
30.COOKIE_HTTPONLY (Optional1)
31.COOKIE_NO_DOMAIN (Optional1)
32.COOKIE_PATH (Optional1)
33.CSS_PATH (Optional1)
34.DTD_BASE_URL (Optional1)
35.EVAL (Optional)
36.FEDERATION_DOMAIN (Required1)
37.FEDERATION_NAME (Required1)
38.HTTP_AUTH (Stack)
39.HTTP_AUTH_ENABLE (Optional1)
40.HTTP_PROG (Required1)
41.INFOCARD_AUDIENCE (Optional)
42.INFOCARD_AUDIENCE_RESTRICTION
(Optional)
43.INFOCARD_CARD_DEFS_URL (Optional1)
44.INFOCARD_CARD_FILL_URL (Optional1)
45.INFOCARD_CARD_IMAGE_BASE_URL
(Required1-C)
46.INFOCARD_CARD_LIFETIME_SECS
(Optional1)
47.INFOCARD_CARD_OUTPUTDIR (Optional1)
48.INFOCARD_CARD_VERSION (Optional1)
49.INFOCARD_CARDID_BASE_URL
(Required1-C)
50.INFOCARD_CARDID_SUFFIX (Optional1)
51.INFOCARD_CARD_DATETIME_EXPIRES
(Optional1)
52.INFOCARD_DIGEST (Optional1)
53.INFOCARD_IP_PRIVACY_URL (Required1-C)
54.INFOCARD_IP_PRIVACY_VERSION
(Optional1)
55.INFOCARD_ISSUER_INFO_ENTRY (Optional)
56.INFOCARD_MEX_URL (Required1-C)
57.INFOCARD_REQUIRE_APPLIES_TO
(Optional1)
58.INFOCARD_STRONG_RP_IDENTITY
(Optional1)
59.INFOCARD_STS_AUTH_TYPE (Required1-C)
60.INFOCARD_STS_CACERTFILE (Required1-C)
61.INFOCARD_STS_CERTFILE (Required1-C)
62.INFOCARD_STS_KEYFILE (Required1-C)
63.INFOCARD_STS_KEYFILE_PASSWORD
(Required1-C)
64.INFOCARD_STS_PASSWORD_METHOD
(Required1-C)
65.INFOCARD_STS_RP_ENDPOINT (Optional)
66.INFOCARD_TOKEN_DRIFT_SECS (Optional1)
67.INFOCARD_TOKEN_ISSUER (Required1-C)
68.INFOCARD_TOKEN_LIFETIME_SECS
(Optional1)
69.INFOCARD_TOKEN_MAX_LENGTH (Optional1)
70.INFOCARD_USERNAME_SELECTOR
(Optional1)
71.JURISDICTION_NAME (Required1)
72.LOGINGEN_FILE (Optional1)
73.LOGINGEN_PROG (Optional1)
74.LOG_FILE (Optional1)
75.LOG_FILTER (Stack)
76.LOG_FORMAT (Optional1)
77.LOG_LEVEL (Optional1)
78.LOG_SENSITIVE (Optional1)
79.NAME_COMPARE (Optional1)
80.NOTICES_ACCEPT_HANDLER (Optional1)
81.NOTICES_ACK_HANDLER (Optional1)
82.NOTICES_DECLINE_HANDLER (Optional1)
83.NOTICES_NAT_NAME_PREFIX (Optional1)
84.NOTICES_SECURE_HANDLER (Optional1)
85.NOTICES_WORKFLOW_LIFETIME_SECS
(Optional1)
86.PAMD_HOST (Optional1)
87.PAMD_PORT (Optional1)
88.PASSWORD_CONSTRAINTS (Optional1)
89.PASSWORD_DIGEST (Optional1)
90.PASSWORD_OPS_NEED_PASSWORD
(Optional1)
91.PASSWORD_SALT_PREFIX (Optional1)
92.PERMIT_CHAINING (Optional1)
93.PROXY_EXEC_DOCUMENT_ROOT (Optional1)
94.PROXY_EXEC_MAPPER_DEFAULT_ACTION
(Optional1)
95.PROXY_EXEC_MAPPER_LOGGING (Optional1)
96.PROXY_EXEC_MAPPER_LOG_FILE
(Optional1)
97.PROXY_EXEC_MAPPER_RULES_FILE
(Optional1)
98.PROXY_EXEC_PROG_URI (Optional1)
99.RLINK (Optional)
100.ROLE_STRING_MAX_LENGTH (Optional1)
101.SECURE_MODE (Optional1)
102.SIGNOUT_HANDLER (Optional1)
103.SSL_PROG (Optional1)
104.SSL_PROG_ARGS (Optional1)
105.SSL_PROG_CA_CRT (Optional1)
106.SSL_PROG_CLIENT_CRT (Optional1)
107.STATUS_LINE (Optional1)
108.TEMP_DIRECTORY (Optional1)
109.TOKEN_REQUIRES_PIN (Optional1)
110.TOKEN_HOTP_ACCEPT_WINDOW (Optional1)
111.TRACE_LEVEL (Optional1)
112.UNAUTH_ROLES (Optional1)
113.UPROXY_APPROVED (Stack)
114.VERBOSE_LEVEL (Optional1)
115.VERIFY_IP (Required1)
116.VERIFY_UA (Optional1)
117.VFS (Stack)
118.XSD_BASE_URL (Optional1)
ACCEPT_ALIEN_CREDENTIALS (Optional1)
If "yes", DACS will honour
credentials imported (by any means) from a different federation. As a security
precaution, such credentials are not used by default.
Security
In federations where dacs_auth_transfer(8)[27] is used, jurisdictions
will likely enable this capability.
ACS_ACCESS_TOKEN_ENABLE (Optional1)
If "yes", ACS's access token
mechanism will be enabled. By default, this feature is disabled. Please see
Authorization Caching[28] for details.
ACS_ACCESS_TOKEN_LIFETIME_LIMIT (Required1-C)
If ACS's access token mechanism has
been enabled, this is the number of times that an access token may be used. It
must be an integer greater than zero. There is no default value. This value,
ACS_ACCESS_TOKEN_LIFETIME_SECS, or both must be configured properly if the
mechanism is enabled. Because it requires updating a database entry, this
method of enforcing a limit on the lifetime of an access token is inherently
less efficient than using ACS_ACCESS_TOKEN_LIFETIME_SECS. Changes to this
limit do not affect access tokens that have already been issued. Please see
Authorization Caching[28] for details.
ACS_ACCESS_TOKEN_LIFETIME_SECS (Required1-C)
If ACS's access token mechanism has
been enabled, this is the lifetime in seconds of an access token, and must be
an integer greater than zero. There is no default value. This value,
ACS_ACCESS_TOKEN_LIFETIME_LIMIT, or both must be configured properly if the
mechanism is enabled. Please see Authorization Caching[28] for
details.
ACS_AUTHENTICATED_ONLY (Optional1)
If "yes", ACS will deny all
requests that are not accompanied by valid credentials, regardless of any
access control rules or other directives.
Note
Since this restriction also applies to DACS services, if this mode is
enabled an unauthenticated user will not be able to access DACS
services by which he might authenticate himself. Users must therefore have
authenticated before this directive is enabled, authenticate using an off-line
method (such as dacscookie(1)[29] or dacsauth(1)[30]), or
authenticate at some other jurisdiction.
ACS_CREDENTIALS_LIMIT (Optional1)
The value of this directive is either an
unsigned integer greater than zero, or the keyword "none" (case
insensitive). In the former case, if a request is submitted with more than
this number of valid credentials, the request will be denied with the REVOKED
error (equivalent to error code 903).
Probably the most common application of this directive is to limit each request
to being associated with at most one identity. The standard site configuration
sets ACS_CREDENTIALS_LIMIT to one. This eliminates confusion about which
identity invoked a web service (i.e., which identity REMOTE_USER should
be set to, for instance) and ambiguity regarding the semantics of rules, and
in some cases may simplify access control rules and log file audits.
A user denied access at a jurisdiction due to this directive will be denied
access to dacs_signout(8)[31] at the jurisdiction. To regain access to
the jurisdiction, the user will either need to signout from a different
jurisdiction or delete one or more sets of credentials (cookies) from his
browser, either using the browser's cookie manager or by terminating the
browser session.
Note
It is possible for a user that is not denied access at a jurisdiction due to
this directive to successfully authenticate, after which he will have
"too many" credentials and subsequently be denied access. Similarly,
a DACS administrator may reduce the limit at any time, potentially
causing access to be denied to users holding a number of credentials in excess
of the limit.
Security
This directive only limits the number of credentials associated with a single
request. It does not prevent the same individual from sending different
requests, from the same browser or different browsers, each associated with a
different identity. Also, it does not limit the number of concurrent logins of
the same identity (such as by different individuals sharing the same account).
DACS does not limit a user's number of concurrent logins or the number of
concurrent logins of the same identity because of the inherent drawbacks of a
general implementation of such a feature. In simple cases, however, an
administrator may be able to add a custom solution to DACS.
ACS_EMIT_APPROVAL (Optional1)
If "yes", DACS will generate
a DACS_APPROVAL environment variable that can be inspected by an
invoked program to verify that its use in the current context was authorized
by DACS. Before this feature is enabled, additional configuration is
necessary; see The DACS_APPROVAL environment variable[32] for
details.
ACS_ERROR_HANDLER (Stack)
If DACS denies a service request, the
web server's DACS module will be so informed and will return a
403 ("Forbidden") status code to the web server. By using
Apache's ErrorDocument directive, the resulting action taken by
Apache can be customized.
In some situations following denial of a request, however, it is desirable to
initiate an action that depends on the reason for denial. For example, if
access is denied because the user is not authenticated, the DACS
administrator might want users to be redirected to a login page; if access is
denied because an access control rule denies access although the user is
authenticated, the administrator might want users to be redirected to a page
that displays a custom error message. It is sometimes useful for the action to
depend on the resource being requested.
The ACS_ERROR_HANDLER directive defines (or overrides) Apache's behaviour
with respect to an ErrorDocument directive for 403 errors if
DACS denies a service request. The syntax and meaning of this directive
are similar to that of Apache's ErrorDocument directive. Please refer
to the Apache documentation for a description of the ErrorDocument
directive[33].
Also refer to the description of the redirect()[34] function.
The syntax of the directive is:
The optional url_pattern is a URI path component that is matched against
the request for which access was denied. It must begin with a '/'. It is like
the url_pattern used in access control rules[35] in that it can
require an exact match or end in "/*"; no query argument component
is allowed. If it is absent, the url_pattern defaults to
"/*", which matches any path.
The error-code is either a numeric error code, an equivalent
case-insensitive error-name, or the special symbol "*", which
means the directive applies to any DACS error code for which there is
no explicit directive.
The following error-name and error-code values are defined:
NO_RULE ( 900)
Access denied, no applicable rule
Access denied, forbidden by rule
Access denied, user not authenticated
Access denied, user access revoked
Access denied, redirect
Access denied, acknowledgement needed
Access denied, low authentication level
Access denied, simple redirect
Access denied, too many credentials were submitted
Access denied, inactivity timeout
Access denied, reason unknown
Control symbol
No blanks may precede the code, any number of blanks may follow it. The
descriptive-text consists only of printable characters (e.g., no tabs or
newlines) and may not contain a colon. The descriptive-text is subject to
change, but the meaning of the code number is fixed. When DACS returns
a numeric error code, a program only needs to examine the three digit code to
determine why access was denied. Optionally, the standard text may be followed
by a single space, a colon, at least one space, and a more detailed error
message.
If a handler-type keyword appears, it selects the action the handler
should take and disables the heuristics that would otherwise be used to decide
the type based on the syntax of the error-action. The reason and
default keywords are the only handler-type keyword that are not
followed by an error-action.
The following handler-type keywords and error-action arguments are
recognized:
This directive may appear multiple times. Because these directives are stacked,
during handler processing directives are examined "backwards",
starting from the last one that appears in the relevant jurisdiction section
through to the first one that appears in the default section of dacs.conf and
backwards through site.conf. The first directive having a url_pattern
and error-code that match the error condition exactly is used.
Otherwise, if no such exact match if found, the first directive encountered
having the closest url_pattern match and exact error-code match
is used; failing that, the first directive with the closest url_pattern
match and default ("*") error-code match is used.
Consider these example directives:
A request for /foo/foo.html that is denied because the user is not authenticated
will cause a redirect to /cgi-bin/foo-login.cgi. If the request is denied for
a different reason, the third directive will be used, causing a redirect to
/cgi-bin/dacs/foohandler. A request for something not located under /foo that
is denied because access is revoked will cause the message specified in the
second directive to be displayed to the user, while any other type of error
will cause an appropriate explanatory message to be displayed.
Here is an example of the expr handler form:
If triggered, this directive will emit a message similar to the following as
Apache's custom error response:
As with all such messages, Apache forces the Content-Type to be text/html.
These two directives are equivalent:
The error response returned by Apache will be:
Any invalid directive will result in Apache following its configured
behaviour. A directive with a syntactically valid but undefined
error-code is ignored, however.
In the case where the service request was issued by Internet Explorer, if
the length of the error response by the server isn't greater than some magic
value and IE's "Show friendly HTTP error messages" is
enabled, which it is by default, then IE will ignore the custom
message. When the "message" and "reason" handler types are
used, DACS adds some padding to thwart IE's
"cleverness". For other handler types, the administrator is
responsible for working around this problem.
Note
Care must be taken to avoid improper operation (such as a potentially infinite
regress) if a CGI program invoked to handle an error is itself protected by
DACS. One example is the situation where a user's access has been
revoked and is therefore unable to access any DACS-protected resource.
If an error occurs while DACS is processing a request for a handler,
DACS will fall back to Apache's default behaviour, ignoring any
normally applicable ACS_ERROR_HANDLER directives.
ACS_FAIL (Optional1)
[ url_pattern] error-code [handler-type] [error-action]
All rules were examined but no rule applies to
the service request.
BY_RULE ( 901)
The closest matching rule does not grant the
service request.
NO_AUTH ( 902)
No valid credentials were provided and either
a) no rule applies or b) the rule does not grant the service request.
REVOKED ( 903)
Credentials were explicitly revoked.
BY_REDIRECT ( 904)
A rule has explicitly redirected the
user.
ACK_NEEDED ( 905)
One or more notices associated with the
request must be acknowledged.
LOW_AUTH ( 906)
Although valid credentials were provided, they
were obtained by an authentication method not strong enough for the requested
resource.
BY_SIMPLE_REDIRECT ( 907)
A rule has explicitly redirected the user; do
not append DACS query arguments.
CREDENTIALS_LIMIT ( 908)
Too many selected credentials accompanied the
request.
INACTIVITY ( 909)
No authenticated requests were made within a
designated time interval.
UNKNOWN ( 998)
An error occurred during processing but no
additional information is available.
DEFAULT (*)
Not an error name, but a keyword used with
ACS_ERROR_HANDLER to configure a handler to invoke if no handler is explicitly
configured for the event.
1.reason
DACS will cause Apache to display the DACS error code that
identifies the reason for denying access followed by the corresponding textual
message. Apache might display messages like the following:
900 Access denied, no applicable access control rule 998 Access denied, internal error: Cookie parse error
2.default
This form instructs DACS not to alter Apache's behaviour (as if
there was no ACS_ERROR_HANDLER specified at all).
3.[url] URL
This form will cause Apache to redirect the client to URL using
the GET method. If the url keyword is absent, URL must begin with the
four characters "http". An invalid URL may be rejected by
Apache and treated as a message. The URL may contain a properly escaped
query string; DACS will append the following parameters, in the order
given, to URL (unless the error name is BY_SIMPLE_REDIRECT, in which
case none of these parameters is passed):
1.DACS_ERROR_CODE, the DACS
error code.
2.DACS_VERSION, the version number of
DACS (e.g., "1.4").
3.DACS_FEDERATION, the federation that
received the service request, if available.
4.DACS_JURISDICTION, the jurisdiction
that received the service request, if available.
5.DACS_HOSTNAME, the domain name of
the host that received the service request, if available.
6.DACS_USER_AGENT, if provided by the
user agent, this is an identifying string, such as:
Mozilla/3.01 (X11; U; Linux 2.4.2 i386)
7.DACS_REQUEST_METHOD, the method used
to invoke the service request, if available. For example, "GET" or
"POST".
8.DACS_ERROR_URL, the service request
URL, including any query string component. The values of these parameters are
URL encoded.
4.[localurl] / local-URL
This form is similar to the absolute URL form except that redirection is to a
local URL-path. The error-action must begin with a slash. The URL may
contain a properly escaped query string; DACS will append additional
parameters as in the absolute URL form.
5.[message] \"a message\"
This form causes Apache to emit the given string as the error document.
If the message keyword is absent, the string must be surrounded by double
quote characters (the quotes do not appear in the final output message).
Note
Apache always sets the Content-Type for this message to text/html. Although
reported quite some time ago, Bug 3641[36] is still open. There may be
a bug in Apache 2.X that prevents the initial double quote in the message from
being stripped; see Bug 42430[37].
6.expr expression
The expr keyword, which cannot be omitted, indicates that the
error-action is an expression. The expression is evaluated and
its value (a string) is used as the Apache error response. If an error occurs
during evaluation, the Apache ErrorDocument or default behaviour will be
used.
ACS_ERROR_HANDLER "* reason" ACS_ERROR_HANDLER '903 "Your access has been revoked"' ACS_ERROR_HANDLER "/foo/* * /cgi-bin/dacs/foohandler" ACS_ERROR_HANDLER "/foo/foo.html NO_AUTH /cgi-bin/foo-login.cgi"
ACS_ERROR_HANDLER "* expr '\"<em>Today is</em> \" . strftime(\"%D\")'"
<em>Today is</em> 05/16/07
ACS_ERROR_HANDLER "* message 'Hello world.'" ACS_ERROR_HANDLER "* \"Hello world.\""
Hello world.
If dacs_acs denies access, the given
expression is evaluated just before the ACS_ERROR_HANDLER[16]
directive, if any, is processed. This directive provides a hook for
post-authorization actions to be performed. The namespaces in effect during
authorization processing are accessible to the expression. The value of the
expression is discarded and any errors are ignored.
ACS_INACTIVITY_LIMIT_SECS (Optional1)
This directive enables inactivity detection if
it is set to a non-zero unsigned integer. Inactivity detection is applicable
only when valid selected credentials accompany a request (i.e., at least one
identity is associated with the request - see
dacs_select_credentials(8)[38]).
There are two cases. If an activity tracking cookie is not sent with the current
request (see ACS_TRACK_ACTIVITY[39]), the user is deemed to be inactive
if the newest credentials are older than ACS_INACTIVITY_LIMIT_SECS seconds. If
an activity tracking cookie is received, the user is deemed to be inactive if
the date/time that it asserts is older than ACS_INACTIVITY_LIMIT_SECS seconds.
If inactivity is detected by dacs_acs(8)[5], access is denied and an
INACTIVITY error ( 909) is raised; see ACS_ERROR_HANDLER[16]. At
present, the only way for a user to continue after an inactivity error is to
explicitly delete DACS cookies or implicitly delete them by restarting
the browser. A non- DACS-wrapped web page or CGI program might be
invoked as an error handler to assist.
Different jurisdictions may independently configure different inactivity
thresholds, disable inactivity detection, or disable activity tracking - the
degree to which this feature improves security or is annoying to users depends
on thoughtful cooperation amongst jurisdictions and adequate clock
synchronization.
ACS_POST_BUFFER_LIMIT (Optional1)
This is the counterpart to the
SetDACSAuthPostBuffer[40] directive of DACS's
mod_auth_dacs[6] Apache module. It establishes the maximum
number of bytes of environment and POST stream that DACS should read
from mod_auth_dacs[6], overriding the compile-time default. To allow
for encoding overhead when serializing the message body, ACS_POST_BUFFER_LIMIT
should be at least 50% larger than the SetDACSAuthPostBuffer size. A value of
zero imposes no limit. (Ideally, only one of these values would need to be
configured but you must currently ensure that both of them are set to
reasonable values.)
ACS_POST_EXCEPTION_MODE (Optional1)
In the event that the web server has not made
all of the request's arguments available to DACS for access control
processing (see SERVICE_ARGS_TRUNCATED[41]), this directive tells
dacs_acs(8)[5] what to do. The following keywords are recognized
values:
abort
ACS_PRE_AUTH (Optional)
Access control processing stops and access is
denied.
default
This is equivalent to discard.
discard
Processing continues, but all web service
arguments are ignored and none will be available to access control
rules.
proceed
Continue processing, even though one or more
arguments may be corrupted or missing. This may result in a segmentation fault
or other unrecoverable error.
query
Continue processing, discarding all POST
arguments but including any arguments that were passed in the request URI's
query component.
Similar to the pre-authorization
authentication feature configured through the HTTP_AUTH[42] directive,
this directive provides a way to authenticate - or identify - a user at access
control time. Rather than involving HTTP Basic or Digest authentication,
however, the value of the directive is an expression that is evaluated. If the
result is a syntactically valid username[43], credentials are created
that (normally) exist only for the duration of the authorization check and
which are associated with the current jurisdiction[44]. This directive
provides a hook for associating an identity with a request based on the
request itself (such as the request URI, its arguments, and other
context).
As a simple example, the following directive checks if the request includes a
USERNAME argument, and if so, just uses it:
Note the single quotes around the expression so that it is evaluated at access
control time instead of configuration processing time.
The ACS_PRE_AUTH directives are processed if a request is received that does not
include valid credentials and if not disabled by
ACS_AUTHENTICATED_ONLY[45]. If more than one ACS_PRE_AUTH directive is
given, they are evaluated in the order in which they appear until one returns
a valid username. If that expression sets the variable ${Auth::ROLES}
to a valid role string, it will be included in the credentials (see
dacs_authenticate(8)[46]). Evaluation errors are ignored. If no
expression returns a valid username, access control processing continues.
These directives are processed before any HTTP_AUTH directives; if a
ACS_PRE_AUTH directive is successful, the user will effectively be
authenticated and so no HTTP_AUTH directives will be processed.
If the request includes a -rname flag with the DACS_ACS[47]
argument, its value is ${Args::RNAME}.
Unlike when authentication is done through dacs_authenticate(8)[48],
credentials are not returned to the client. This means that no
DACS session state exists outside of dacs_acs and therefore some
DACS web services may be unavailable or may not operate in the same way
they would if credentials were provided by the client. This mechanism may also
be less efficient than one that returns credentials because authentication
will be performed each and every time the client makes a request that triggers
it.
ACS_SUCCESS (Optional)
ACS_PRE_AUTH '${Args::USERNAME:e} ? ${Args::USERNAME} : ""'
If dacs_acs grants access, immediately
before it terminates it evaluates the given expression. This directive
provides a hook for post-authorization actions to be performed, which can be
user-specific. The namespaces in effect during authorization processing are
accessible to the expression. The value of the expression is discarded and any
errors are ignored.
Also see the on_success()[49] function.
Note
While it is typically true that if DACS grants a request, the web server
will go on to process the request (and eventually return a web page to the
user agent, execute a program, etc.), it is not necessarily so. For example,
access may still be denied by the web server for other reasons, or an error
can occur during subsequent processing. This may be relevant in situations
where ACS_SUCCESS is used to decrement a counter[50], for instance,
because it is possible that the user may not actually see a successful result,
in which case the counter value should not have been changed and so corrective
action would be required.
ACS_TRACK_ACTIVITY (Optional1)
This directive is associated with the
inactivity timeout feature whereby an authenticated user is denied access (at
any jurisdiction where it is enabled within the current federation[51])
if no web service request is made within a certain time period (also at any
jurisdiction where it is enabled within the current federation[51]).
See ACS_INACTIVITY_LIMIT_SECS[52]. This feature is disabled by default.
It is enabled on a per-jurisdiction basis, and in the usual configuration all
jurisdictions within a federation will enable the feature if it is required.
If the directive's value is "yes", dacs_acs(8)[5] emits a
federation-wide HTTP cookie that notes the jurisdiction and date/time at which
each DACS-wrapped service request is processed. The cookie is emitted
regardless of whether access was granted, although some error conditions may
prevent a cookie from being sent. No cookie is set for an effectively
unauthenticated request.
The name of the activity tracking cookie has the following format:
where federation-name is the official name assigned to the federation for
which the cookie is valid ( FEDERATION_NAME[53]). Activity tracking may
be enabled without enabling inactivity detection (via
ACS_INACTIVITY_LIMIT_SECS[52]). This feature depends on an appropriate
level of clock synchronization at all participating jurisdictions.
ADMIN_IDENTITY (Optional)
DACS: federation-name::::ACTIVITY
This repeatable directive specifies a
DACS identity (group names are currently not allowed) that DACS
grants special privileges. If omitted, the current federation and
jurisdiction[51] are implied. The usernames "unauth" and
"unauthenticated" are disallowed, whether qualified with a
jurisdiction or not. The function dacs_admin()[54] tests whether the
user making a service request has any credentials that match any
ADMIN_IDENTITY. This enables boilerplate access control rules to be written
that need to restrict access to an administrator - the rules need only invoke
dacs_admin(). Changes to the list of DACS administrators take
effect immediately. Comparison of these identities with credentials is
controlled by the NAME_COMPARE[55] directive.
Some DACS services call an internal version of this function to ensure
certain operations are limited to a DACS administrator.
Security
Consider requiring more secure authentication for administrator identities, such
as using a two-factor authentication method or combining two different
authentication methods.
ALLOW_HTTP_COOKIE (Optional1)
If "yes", DACS components
will allow the environment variable HTTP_COOKIE to be used to pass
DACS credentials. This is currently necessary when DACS
components are invoked through IIS (except in conjunction with DACS
proxied operation). On secure systems, this method of passing credentials may
be acceptable, but in general it is not secure and must not be allowed because
environment variables are essentially public on some systems. If undefined or
not "yes", DACS components will fail if HTTP_COOKIE is
present.
AUTH_AGENT_ALLOW_ADMIN_IDENTITY (Optional1)
Unless this directive has the value
"yes", dacs_auth_agent will not return credentials that have
been designated as an ADMIN_IDENTITY.
AUTH_CREDENTIALS_ADMIN_LIFETIME_SECS (Optional1)
The lifetime, in seconds, of all credentials
created by this jurisdiction for internal use. These credentials are used in
certain internal transactions, such as when dacs_authenticate sends an
HTTP request to an authentication or roles module. Although they are only
supposed to be held by trusted components, because these credentials can
convey special privileges their lifetime should not be much longer than
required. It is sometimes necessary to increase this lifetime when debugging
or if a recipient server is slow.
AUTH_CREDENTIALS_DEFAULT_LIFETIME_SECS (Required1)
The default lifetime, in seconds, of all
credentials created by this jurisdiction for users. The jurisdiction's
authentication services may override this value on a case-by-case basis,
either through an authentication module (see auth_reply.dtd[56]) or by
setting ${Auth::CREDENTIALS_LIFETIME_SECS} (see
dacs_authenticate(8)[48]).
Security
The lifetime should be chosen such that it strikes a balance between security
and user convenience that is appropriate for the jurisdiction and federation.
AUTH_ERROR_HANDLER (Stack)
If dacs_authenticate(8)[48] is not able
to successfully authenticate a user, the resulting action can be customized in
ways that depend on the reason for the failure. This provides a way for the
system administrator to display a custom error message or redirect the user's
browser.
Note
This feature is activated only if dacs_authenticate is passed an
ENABLE_AUTH_HANDLERS parameter that has a value of 1.
The following error code numbers and corresponding descriptive text are defined:
When this type of response is returned, a program needs to only examine the
three digit code to determine why access was denied. No blanks may precede the
code, any number of blanks may follow it. The descriptive-text consists only
of printable characters (e.g., no tabs or newlines) and may not contain a
colon. The descriptive-text is subject to change, but the meaning of the code
number is fixed. Optionally, the standard text may be followed by a single
space, a colon, at least one space, and a more detailed error message.
The dacs_authenticate service recognizes a FORMAT argument that is
used to select between an XML-aware user agent (FORMAT=XML) and an HTML
capable user agent ( FORMAT is not specified or is not XML). In the
case of an XML result, dacs_auth_reply.dtd[57] is used. The behaviour
of this directive with respect to FORMAT is described below on a
case-by-case basis.
The following directives are supported:
The optional keywords are treated case-insensitively.
The AUTH-error-code is either a defined authentication error code (listed
above) or the special symbol "*", which means the directive applies
to any authentication error code for which there is no explicit directive.
This directive may appear multiple times, although multiple directives for the
same AUTH-error-code are not allowed. Any invalid directive will
generally be treated as a fatal error. A directive with a syntactically valid
but undefined AUTH-error-code is ignored, however.
AUTH_FAIL (Optional1)
800 Authentication failed, invalid authenticating information 801 Authentication failed, invalid argument 802 Authentication failed, internal error 899 Authentication failed, reason unknown
1.AUTH_ERROR_HANDLER
"AUTH-error-code reason"
DACS will return an HTML (or XML, if FORMAT=XML) document that describes
why authentication failed, such as the following:
This is the default behaviour.
800 Authentication failed, invalid authenticating information
2.AUTH_ERROR_HANDLER
"AUTH-error-code [url] URL"
This form causes DACS to redirect the client to the specified URL, which
may be a relative or absolute URL. If the keyword url is absent, URL
must begin with the four characters http. The GET method will be used. The URL
may contain a properly escaped query string; DACS will append the
following parameters, in the order given, to the URL:
The values of these parameters are URL encoded.
1.DACS_ERROR_CODE, the AUTH-error-code
that identifies the failure.
2.DACS_VERSION, the version number of
DACS (e.g., "1.4").
3.DACS_FEDERATION, the federation that
received the service request, if available.
4.DACS_JURISDICTION The jurisdiction
that received the service request, if available.
5.FORMAT, the value of this parameter
will be either HTML or XML, as determined by the value of the parameter of the
same name passed to dacs_authenticate or the default (HTML if
FORMAT was not specified).
3.AUTH_ERROR_HANDLER
"AUTH-error-code [file] full-pathname"
This form causes the contents of the file named by full-pathname to be
returned without regard to the presence of a FORMAT argument.
Note
The file must include any header lines it requires, such as a Content-Type line,
a header-terminating blank line, and then the document content. Note also that
the "full-pathname" usage differs from the "local-URL"
usage of the ACS_ERROR_HANDLER directive, though both elements begin with a
slash character; the former specifies the absolute pathname of a file, while
the latter specifies a URL local to the receiving web server.
4.AUTH_ERROR_HANDLER
"AUTH-error-code [message] \" message\""
This form causes the given message, surrounded by escaped double quote
characters, to be returned as HTML (or XML if FORMAT=XML).
If dacs_authenticate fails to
authenticates a user, the given expression is evaluated just before the
AUTH_ERROR_HANDLER[58] directive, if any, is processed. This directive
provides a hook for post-authentication actions to be performed. The
namespaces in effect during authentication processing are accessible to the
expression. The value of the expression is discarded and any errors are
ignored. Note that since authentication failed, only the user's purported
identity may be available ( ${Args::USERNAME}), or if the user was
previously authenticated successfully, as ${Env::REMOTE_USER}.
AUTH_FAIL_DELAY_SECS (Optional1)
If assigned a positive integer value, a
particular user (ordinarily the one identified by the USERNAME argument
to dacs_authenticate) will not be allowed to reauthenticate following a
failed attempt within this many seconds. If assigned the value of zero
seconds, this feature is disabled. If this directive is absent or assigned an
illegal value, a compile-time value is used instead. Authentication modules
may indirectly impose their own delays following unsuccessful authentication;
this is system dependent and not under the control of DACS.
AUTH_SINGLE_COOKIE (Optional1)
By default, each set of credentials that is
returned in an HTTP cookie is assigned a cookie name[59] that
corresponds to the identity represented by the credentials. If a user
authenticates as two different identities through dacs_authenticate,
for example, he will be given two cookies with different names. Because in
some situations multiple credentials can be problematic, this directive
provides a way to effectively limit a request to a single set of credentials
by using one cookie name for all credentials. When an already-authenticated
user authenticates again, either at the same jurisdiction or any jurisdiction,
the user's browser will replace the previous cookie with the new one.
This directive also controls cookie names associated with credentials generated
by dacscookie(1)[29], dacs_auth_agent(8)[60], and
dacs_auth_transfer(8)[27]. Also see ACS_CREDENTIALS_LIMIT[61].
By setting AUTH_SINGLE_COOKIE to "jurisdiction" (case insensitive),
the username component of an authentication cookie issued by the jurisdiction
is suppressed. This means that every authentication cookie it creates will
have the same name. By setting it to "federation" (case
insensitive), the jurisdiction and username components of an authentication
cookie issued by the jurisdiction are suppressed. This means that every
authentication cookie that it creates will have the same name, but also that
any two jurisdictions that use this configuration will create cookies with the
same name. Any other value results in the default behaviour, which is to
include both the jurisdiction name and the username in the names of
authentication cookies. The directive has no effect on the name of the
identity encapsulated within an HTTP cookie.
If an authentication cookie is received that was created by the jurisdiction and
has a cookie name with a component that it has been configured to suppress,
the cookie is ignored. A cookie issued by a different jurisdiction with a
suppressed cookie name component is acceptable regardless of how this
directive is configured at this jurisdiction. DACS will reject all
credentials if a request includes more than one cookie with the same cookie
name.
In typical use, each jurisdiction that performs authentication will configure
this directive identically. To limit each user to associating a single
identity with their request, simply set AUTH_SINGLE_COOKIE to
"federation" at each jurisdiction in the federation.
Security
This directive indirectly limits the number of credentials that can be
associated with a single request. It does not prevent the same individual from
sending different requests, from the same browser or different browsers, each
associated with a different identity. Also, it does not limit the number of
concurrent logins of the same identity (such as by different individuals
sharing the same account).
Changing this directive's value may render existing credentials invalid at this
jurisdiction. For example, after changing the directive it is possible for a
user to obtain two authentication cookies with different names for the same
identity. DACS does not allow a request to include multiple credentials
for the same identity.
AUTH_SUCCESS (Optional)
If dacs_authenticate successfully
authenticates a user, the given expression is evaluated just before the
AUTH_SUCCESS_HANDLER[62] directive, if any, is processed. This
directive provides a hook for post-authentication actions to be performed,
which can be user-specific. The namespaces in effect during authentication
processing are accessible to the expression. The value of the expression is
discarded and any errors are ignored.
Also see the on_success()[49] function.
As an example, the following directive will run a web service after every
successful login:
AUTH_SUCCESS_HANDLER (Optional1)
If dacs_authenticate successfully
authenticates a user, the resulting action can be customized. This provides a
way for the DACS administrator to redirect a user's browser after
login.
Note
This feature is enabled only if dacs_authenticate is passed an
ENABLE_AUTH_HANDLERS parameter that has a value of 1.
The dacs_authenticate service recognizes a FORMAT argument that is
used to select between an XML-aware user agent (FORMAT=XML) and an HTML
capable user agent ( FORMAT is not specified or is not XML). In the
case of an XML result, dacs_auth_reply.dtd[57] is used. The behaviour
of this directive with respect to FORMAT is described below on a
case-by-case basis.
The following syntaxes are supported:
The optional keywords are treated case-insensitively.
AUTH_TRANSFER_EXPORT (Optional)
1.AUTH_SUCCESS_HANDLER "[url]
URL"
This form causes DACS to redirect the client to URL, which may be
a relative or absolute URL. If the keyword url is absent, URL must
begin with the four characters http. The GET method will be used. The URL may
contain a properly escaped query string; DACS will append the following
parameters, in the order given, to the URL:
DACS_VERSION
The values of these parameters are URL encoded.
The version number of DACS (e.g.,
"1.4").
DACS_FEDERATION
The federation that received the service
request, if available.
DACS_JURISDICTION
The jurisdiction that received the service
request, if available.
DACS_USERNAME
The username associated with the new
credentials.
FORMAT
The value of this parameter will be either
HTML or XML, as determined by the value of the parameter of the same name
passed to dacs_authenticate or the default (HTML if FORMAT was
not specified).
2.AUTH_SUCCESS_HANDLER "[file]
full-pathname"
This form causes the contents of the file named by full-pathname to be
returned without regard to the presence of a FORMAT argument. The file
must include any header lines it requires, such as a Content-Type line, a
header-terminating blank line, and then the document content.
Note
The "full-pathname" usage differs from the "local-URL" usage
of the ACS_ERROR_HANDLER directive, though both elements begin with a slash
character; the former specifies the absolute pathname of a file, while the
latter specifies a URL local to the receiving web server. To specify a
relative URL, use the url keyword.
3.AUTH_SUCCESS_HANDLER "[message]
\" message\""
This form causes the given message, surrounded by escaped double quote
characters, to be returned as HTML (or XML if FORMAT=XML).
4.AUTH_SUCCESS_HANDLER
"credentials"
This form causes the user's credentials to be displayed, either as an HTML or
XML (if FORMAT=XML) document. This is the default behaviour.
Each use of this directive identifies a target
federation and the corresponding URL of a program to invoke the TOKEN
operation phase of the protocol in that federation. The federation identifier
is simply a label; it must be a syntactically valid federation name.
Whitespace separates the federation name from the URL. Please refer to
dacs_auth_transfer(8)[27] for details.
AUTH_TRANSFER_TOKEN_LIFETIME_SECS (Optional1)
This is the lifetime, in seconds, of a token
produced by the TOKEN operation of dacs_auth_transfer(8)[27] and
consumed by its IMPORT operation. That is, it is the time a user (or
middleware) has to submit the token before it becomes invalid. It should be on
the order of a few seconds.
COMPAT_MODE (Optional1)
This indicates that, to the extent possible,
credentials issued by a different release of DACS should be accepted.
At present, the only supported values are off (the default, which disables
this mode) and 1.2.
Important
This directive is not intended to provide complete interoperability among
DACS releases and in fact it does not in certain situations. Old
releases of DACS may contain security-related bugs, or may rely on
third-party software that contains security-related bugs. DACS
installations are urged to upgrade rather than to depend on the limited
backward compatibility supplied by this directive. There is no guarantee
that any particular level of backward compatibility will be carried forward in
subsequent releases of DACS.
COOKIE_HTTPONLY (Optional1)
If "yes", the HttpOnly attribute
will be included with cookies produced by DACS. This attribute is a
Microsoft extension that is used to " mitigate the risk of information
disclosure with a cross-site scripting (XSS) attack[63]". This
attribute is not recognized by all browsers but these browsers should ignore
it. The default is "no".
Security
Methods of defeating this attribute are known[64], so administrators may
need to take additional precautions against XSS attacks.
COOKIE_NO_DOMAIN (Optional1)
If "yes", no domain attribute will
appear when DACS returns a cookie, such as after authenticating
successfully from a browser. The browser will take the default action, which
is to associate the cookie with the domain name or IP address of the request
that returned the cookie. This will obviously limit DACS's single
sign-on feature since the cookie (credentials) will only be sent with requests
made to that domain name or IP address.
This directive is sometimes useful when DACS is deployed in an
environment where fully qualified domain names are not used. In this case,
FEDERATION_DOMAIN must still be configured, although it will not be used in
conjunction with the domain of cookies.
The default is "no".
COOKIE_PATH (Optional1)
This allows the path component of a Set-Cookie
(and Set-Cookie2) HTTP response header to be specified for the jurisdiction.
These headers are sent to a user agent after successful authentication or
signout. Refer to the Netscape HTTP Cookies Specification[65] and
RFC 2965[66] for details.
Security
The default value is "/", which means that the cookie will be sent by
a user agent along with every request sent to the jurisdiction's host.
The value should be set to the most specific URL path under which all
DACS-wrapped services appear so that DACS credentials will only
be sent with requests to those URLs. It is critical to do this if your server
runs arbitrary user CGI programs because a malicious user might be able to
cause a DACS-authenticated user to visit a service that is not
DACS-wrapped and capture cookies that represent DACS identities.
For example, if a jurisdiction segregated its DACS-wrapped static
content under /dacs/content and its DACS-wrapped CGI programs under
/dacs/cgi-bin, then COOKIE_PATH should have the value "/dacs".
CSS_PATH (Optional1)
This path is used as the value of the href
attribute of the HTML link element used to specify the root location of style
files used by HTML-producing DACS web services and utilities. The
mapping between this path and a local directory, if any, depends on
Apache's configuration; for example, if its value is "/css",
the location of the corresponding directory will depend on the location of the
server's document root and any applicable Alias directive.
If this directive is not used, a compile-time default of "/css" is
used, which assumes that an Apache directive like this one is used:
Please refer to dacs.install(7)[67] for additional information about use
of the Alias directive.
DTD_BASE_URL (Optional1)
Alias /css "/usr/local/dacs/www/css/"
When DACS services are asked to send an
XML response (FORMAT=XML) and DTD_BASE_URL is configured, services will emit a
DOCTYPE with the keyword SYSTEM followed by a value derived from DTD_BASE_URL;
e.g.,
If DTD_BASE_URL is not configured, an internal DTD will be emitted. Also see the
description of the FORMAT web service argument[68].
EVAL (Optional)
<!DOCTYPE foo SYSTEM "http://example.com/dacs/dtd-xsd/foo.dtd">
The EVAL directive is special in that it may
appear in any clause and because it is always evaluated when it is first
seen during processing of site.conf, the Default section of dacs.conf, or
the applicable Jurisdiction section of dacs.conf (i.e., before any section
merging occurs). The purpose of the directive is purely for its side effect,
such as initializing a configuration variable (see Advanced
Techniques[69]). Because these directives are scanned early during
configuration processing, their right-hand sides cannot reference directives
as configuration variables because those directives have not yet been
evaluated (so they cannot reference ${Conf::FEDERATION_DOMAIN}, for
example). Example:
FEDERATION_DOMAIN (Required1)
EVAL ${Conf::a_special_path} = "/my/path"
The suffix of the domain name (RFC
1035[70] 2.3.1) that is common to all jurisdictions in the federation.
Note that the domain name associated with a jurisdiction is not explicitly
configured (but see dacs_url in dacs.groups(5)[71]), and that this is a
one-to-many association (see dacs.conf(5)[72]). Example:
example.com
FEDERATION_NAME (Required1)
The name for the federation of jurisdictions.
The syntax is the same as for JURISDICTION_NAME[73]: an alphabetic
followed by zero or more alphanumeric characters, '-', or '_'. By convention,
this is in all-caps, however. Please see dacs(1)[74] for additional
information. Example: FEDROOT
HTTP_AUTH (Stack)
This directive is used to perform user
authentication at access control time rather than in a separate step. This
authentication is triggered through DACS's internal implementation of
HTTP Basic or Digest authentication (see RFC 2617[75]). If prompting is
enabled, the user will be asked for his username and password by the user
agent's usual prompting method. If prompting is disabled, the user agent must
know how to send an Authorization request header without first receiving a
WWW-Authenticate response header. The username and password obtained from the
user can be directed to any suitable DACS authentication method for
validation. The resulting identity is associated with the current
jurisdiction[44].
Other than by placing the resource or resources specified by this directive
under the control of DACS, no additional Apache configuration
needs to be done to use this feature. Please refer to the section on HTTP
Authentication[76] for additional information about this feature and how
it is used. Also consult the HTTP_AUTH_ENABLE[77] directive.
Two different mechanisms are available: pre-authorization testing and
post-authorization testing. The HTTP_AUTH_ENABLE directive is used to
enable one or both mechanisms.
The pre-authorization testing mechanism is used if:
This mechanism can be useful with simple user agents that understand Basic
authentication but cannot handle redirection or sometimes even the
WWW-Authenticate response header. It may also be appropriate in situations
where a user agent cannot or will not handle HTTP cookies. If dacs_acs
is allowed to respond with a WWW-Authenticate response header, the
configuration variable ${Conf::http_auth_401} must be set to
"yes".
The post-authorization testing mechanism is used if:
One important difference between the two mechanisms is that while the
post-authorization mechanism works by redirecting the user to
dacs_authenticate(8)[48] after authorization checking denies a request,
the pre-authorization mechanism does not involve any redirection and
dacs_authenticate is not used. Instead, dacs_acs performs
authentication internally (by calling dacsauth as a function) and
credentials are not returned to the client; credentials are created
that (normally) exist only for the duration of the authorization check, which
means that no DACS session state exists outside of dacs_acs and
therefore some DACS web services will either be unavailable or not
operate in the same way they would if credentials were provided by the client.
Pre-authorization may also be less efficient than returning credentials
because authentication will be performed each and every time the client makes
a request that triggers it. Note that only authentication modules that
implement the password or expr authentication styles[80] can be used by
this mechanism, and only if no redirection of the client is necessary. Because
web browsers only prompt for a username and password, if an AUXILIARY
argument is also required it must be entered with either the username or
password (i.e., combined in some way, perhaps separated by punctuation) and
then parsed into an AUXILIARY argument using a run-time configuration
directive. With pre-authorization, roles can be assigned to the temporary
credentials (refer to the description of the -r flag and the
role-module-spec in dacsauth(1)[30] for details).
Security
Like dacsauth and dacs_authenticate, if dacs_acs uses a
built-in module to perform authentication, it must run setuid or setgid (
chmod(2)[81]). to obtain sufficient privileges to access the required
files; this is true for Unix password authentication, for example. Programs
should run at the lowest level of authorization that is necessary, however,
and it is generally preferable to only run authentication modules at a higher
authorization level.
The value of the HTTP_AUTH directive follows any one of the following three
forms:
The first syntactical form is for the post-authentication mechanism:
The second syntactical form is for the pre-authentication mechanism. Its first
three components are like those for the first form, and must appear in the
order specified above. The following components are then added, and may follow
the three initial components in any order:
In the third syntactical form, the except keyword identifies portions of the URL
space that should not trigger HTTP authentication.
The HTTP_AUTH directives "stack", like the
ACS_ERROR_HANDLER[16] directive. DACS will search for the first
exact url_pattern that matches or will select the closest wildcard
url_pattern. Two or more directives with the same url_pattern
should not be configured.
The first of the two directives in the following example may trigger Basic
authentication for the realm called "Info Realm" when either
/cgi-bin/dacs/dacs_prenv or /cgi-bin/dacs/dacs_version (relative to the
current jurisdiction[44]) is requested. The second directive may
trigger Basic authentication for the realm called "CGI Realm" for
any other resource subordinate to /cgi-bin/dacs. The first directive will
override the second because an exact match overrides a wildcard match.
In the next example, the two directives associate the Basic authentication
scheme with everything under /cgi-bin/dacs/, except for
/cgi-bin/dacs/dacs_prenv (because the second directive is an exact match,
which overrides the first directive):
Tip
An administrator can take advantage of DACS's active configuration
processing to decide at run-time which auth_scheme, auth_realm,
or password file to use, for instance, perhaps depending on the request's
arguments.
As an example of pre-authorization testing authentication, consider the
following configuration directives:
The first directive above enables this feature. The second directive disables
responding with a WWW-Authenticate header; changing its value to
"yes" enables the response. The third directive associates the
DACS dacs_prenv(8)[82] service with the built-in Basic
authentication feature at pre-authorization testing time. Given this
configuration, if a client requests dacs_prenv but does not include
credentials:
Tip
You can create an Authorization header by constructing a string consisting of an
account name, a colon, and the account's password. MIME encode the resulting
string - you can use dacsexpr(1)[83] and the encode()[84]
function:
The header for the example above would look like:
And using http(1)[3], you could use the flag:
The example that follows shows how LDAP authentication[85] using the
direct method might be configured. In an appropriate place in dacs.conf, we
might insert these directives:
In the file /usr/local/dacs/ldap/ldap_auth_options_direct (which must be
readable at run-time by dacs_acs(8)[5]), we might put:
Note the use of the LDAP_USERNAME_EXPR* directive. Because authentication
against the directory uses a Common Name attribute in the example, and a
Common Name may not be a valid DACS username, it must be replaced by
(or mapped to) an acceptable DACS username. The first time a user
attempts to access a resource that matches the URL pattern /basic/*, he will
prompted by his web browser for a username (in this case, a Common Name must
be provided) and password. The directory on windex.example.com will be used by
the local_ldap_authenticate module to validate the information provided
by the user.
To also obtain the user's roles from the directory, the set_roles style modifier
and an LDAP_ROLES_SELECTOR* directive can be added to the configuration:
And to /usr/local/dacs/ldap/ldap_auth_options_direct:
Tip
Since the pre-authorization mechanism does not return DACS credentials to
the user's web browser, a subsequent invocation of
dacs_current_credentials(8)[86] will not display information that
resulted from the authentication procedure. If the URL that triggers
pre-authorization is for a script or other program that is executable by
Apache with access permitted by DACS, however, the program can
display its environment, which will include DACS_USERNAME,
DACS_ROLES, and so on. For example, dacs_prenv(8)[82] can be
used for this, as can this simple PHP script ( phpinfo.php):
To authenticate against a Unix account and assign the user's group membership as
roles, this configuration might be used:
Note that local_unix_authenticate must run with sufficient privileges to
validate the username/password pair.
HTTP_AUTH_ENABLE (Optional1)
1.a request is received that does not include
valid credentials;
2.the feature is enabled by HTTP_AUTH_ENABLE
(i.e., it is set to "pre_acs_only" or "both") and not
disabled by ACS_AUTHENTICATED_ONLY[45];
3.no ACS_PRE_AUTH[78] directive is
successful;
4.the applicable directive includes the
-pre flag ( see below[79]); and
5.either the request includes an
Authorization request header or the return of an HTTP WWW-Authenticate
response header is enabled.
1.a request is denied because the user was
not authenticated;
2.the feature is enabled by HTTP_AUTH_ENABLE
(i.e., it is set to "post_acs_only" or "both") and not
disabled by ACS_AUTHENTICATED_ONLY;
3.the applicable directive does not include a
-pre flag (see below).
1.
auth_scheme auth_realm url_pattern+
2.
auth_scheme auth_realm url_pattern+ -pre [[-param] param-string]
{-m auth-module-spec [auth-flag]*}+ {-r roles-module-spec}*
3.
except url_pattern+
•auth_scheme is the
(case-insensitive) authentication scheme to use (e.g., Basic);
•auth_realm is the
(case-sensitive) realm-value string associated with the resource (see RFC
2617[75]);
•url_pattern+ is a list of one or
more URI path components that are matched against the request for which access
was denied to an unauthenticated user. Each of these components is like the
url_pattern attribute used in access control rules[35] in that
it can either specify an exact match or, by ending in "/*", a
wildcard match; no query argument component is allowed. Each
url_pattern begins with a / character.
•-pre selects the
pre-authorization testing mechanism; the default is to use post-authorization
testing. Because each url_pattern begins with a / character, the
-pre flag implicitly ends the url_pattern list.
•param-string is an optional
string consisting of authentication parameters as per RFC 2617 (note: Basic
auth does not permit any optional parameters). For clarity, or if
param-string might be confused with another syntactic element, it can
be preceded by a -param flag. In the absence of the -param flag,
any non-flag argument is assumed to be the param-string. Only one
param-string is allowed.
•-m auth-module-spec
specifies an authentication module using the command-line syntax of
dacsauth(1)[30]. This argument must occur at least once. Following the
auth-module-spec can be zero or more auth-flag arguments to
apply to the module's authentication context. The
-Ddirective =value flag, -fj
jurname flag, and the -fn fedname flag
are recognized and have the same semantics as when used by
dacsauth(1)[30].
•-r roles-module_spec
specifies a roles module. This argument may occur zero or more times.
HTTP_AUTH "basic \"Info Realm\" /cgi-bin/dacs/dacs_prenv /cgi-bin/dacs/dacs_version" HTTP_AUTH "basic \"CGI Realm\" /cgi-bin/dacs/*"
HTTP_AUTH "basic \"CGI Realm\" /cgi-bin/dacs/*" HTTP_AUTH "except /cgi-bin/dacs/dacs_prenv"
HTTP_AUTH_ENABLE "pre_acs_only"
EVAL ${Conf::http_auth_401} = "no"
HTTP_AUTH "basic \"dacs_prenv Realm\" /cgi-bin/dacs/dacs_prenv -m unix passwd suff"
•if no Authorization header was sent and
${Conf::http_auth_401} is "no", then execution will proceed
as if the feature were disabled (i.e., the user will be unauthenticated)
•if no Authorization header was sent and
${Conf::http_auth_401} is "yes", then DACS will
respond with a WWW-Authenticate response header and 401 status
code
•if an Authorization header was sent,
the username and password will be validated using the built-in Unix
authentication module:
•if authentication succeeds, temporary
credentials will be created and used for the request, but will not be returned
to the client
•if authentication fails, access will be
denied
% dacsexpr > encode(mime, "guest:apassword") "Z3Vlc3Q6YXBhc3N3b3Jk"
Authorization: Basic Z3Vlc3Q6YXBhc3N3b3Jk
-header Authorization "Basic Z3Vlc3Q6YXBhc3N3b3Jk"
HTTP_AUTH_ENABLE "pre_acs_only"
HTTP_AUTH "basic \"LDAP Login Using Your Common Name\" /basic/* -pre \
-m https://example.example.com/cgi-bin/dacs/local_ldap_authenticate \
password sufficient -Of /usr/local/dacs/ldap/ldap_auth_options_direct"
LDAP_BIND_METHOD=direct LDAP_USERNAME_URL*="ldap://windex.example.com/CN=" . encode(url,${Args::USERNAME}) . ",CN=Users,DC=example,DC=com" LDAP_USERNAME_EXPR*="${LDAP::sAMAccountName}"
HTTP_AUTH_ENABLE "pre_acs_only"
HTTP_AUTH "basic \"LDAP Login Using Your Common Name\" /basic/* -pre \
-m https://example.example.com/cgi-bin/dacs/local_ldap_authenticate \
password,set_roles sufficient -Of /usr/local/dacs/ldap/ldap_auth_options_direct"
LDAP_BIND_METHOD=direct LDAP_USERNAME_URL*="ldap://windex.example.com/CN=" . encode(url,${Args::USERNAME}) . ",CN=Users,DC=example,DC=com" LDAP_ROLES_SELECTOR*="${LDAP::attrname}" eq "memberOf" ? strtr(ldap(rdn_attrvalu e, ldap(dn_index, "${LDAP::attrvalue}", 1)), " ", "_") : "" LDAP_USERNAME_EXPR*="${LDAP::sAMAccountName}"
<html><head></head><body> <p> <?php phpinfo(); ?> </p> </body> </html>
HTTP_AUTH_ENABLE "pre_acs_only"
HTTP_AUTH "basic \"Login Using Your Unix Account\" /basic/* -pre \
-m https://example.example.com/cgi-bin/dacs/local_unix_authenticate \
password sufficient -Of /usr/local/dacs/ldap/ldap_auth_options_direct \
-r https://example.example.com/cgi-bin/dacs/local_unix_roles"
This directive's value must be
"post_acs_only" if only post-authorization testing HTTP
Authentication[76] may be used, "pre_acs_only" if only
pre-authorization testing HTTP authentication may be used, or "yes"
or "both" if either mechanism may be used. Refer to
HTTP_AUTH[42] for additional details.
HTTP_PROG (Required1)
The full pathname of the executable
http(1)[3] program, a utility distributed with DACS. This
program is used by DACS components to invoke local services, optionally
using SSL.
INFOCARD_AUDIENCE (Optional)
This directive must be configured for
DACS to function as a Relying Party. When DACS acts as a Relying
Party, each of these directives is applied to the value of an Audience element
(a URI) in a secure token's AudienceRestrictionCondition element until a
successful match is found. Several matching functions are available using the
following syntax:
function is case insensitive.
uri match-URI
regex/ flags match-regex
INFOCARD_AUDIENCE_RESTRICTION (Optional)
function [space+ arg-to-match-against-Audience]
The match-URI is compared with the
entire Audience URI for an exact URI match. URI matching syntax is used,
meaning that only the scheme and hostname components are case insensitive.
any
INFOCARD_AUDIENCE "uri http://DACS.DSS.CA/infocard-demo"
Any Audience is acceptable.
regex match-regex
INFOCARD_AUDIENCE "any"
In the first form, the regular expression
match-regex is matched (unanchored) against the Audience URI. In the
second form, one or more flags can precede the regular expression: 'i'
specifies case-insensitive matching and 'e' specifies "extended"
regular expressions rather than the default "basic" regular
expressions. IEEE Std 1003.2 ("POSIX.2") regular expressions are
supported ( regex(3)[87]).
The following directives are equivalent:
host match-hostname
INFOCARD_AUDIENCE "regex/i ^https://dacs.dss.ca:8443"
INFOCARD_AUDIENCE "regex .*" INFOCARD_AUDIENCE "any"
The match-hostname, which may be a
domain name or an IP address, is matched case-insensitively against the host
name in the Audience URI.
prefix match-URI
INFOCARD_AUDIENCE "host dacs.dss.ca"
The match-URI is matched against the
Audience URI to test if the former is a prefix of the latter. The
case-sensitivity rules for URI components is respected (e.g., the scheme and
host name components are treated case-insensitively, but the path components
are not).
INFOCARD_AUDIENCE "prefix https://dacs.dss.ca/infocards"
Used by dacs_sts(8)[88], this optional
directive specifies the value of an Audience element in an
AudienceRestrictionCondition.
INFOCARD_CARD_DATETIME_EXPIRES (Optional1)
This optional directive specifies the date and
time of expiration for a managed InfoCard created by
dacs_managed_infocard(8)[89]. The XML Schema dateTime format
must be used (see XML Schema Part 2: Datatypes Second Edition[90]);
e.g.,
Also see INFOCARD_CARD_LIFETIME_SECS[91].
INFOCARD_CARD_DEFS_URL (Optional1)
INFOCARD_CARD_DATETIME_EXPIRES "2010-06-15T09:46:31-08:00"
This optional directive is used by
dacs_managed_infocard(8)[89] to specify a web service that defines the
claims supported by a new managed InfoCard. If it is not defined, the default
claim dacs_identity is used. To prevent abuse, arbitrary compile-time limits
are imposed on the number of claims (20) and the lengths of various claim
components: name (32 bytes), value (64 bytes), URI prefix (128 bytes), label
(20 bytes), and description (40 bytes). (These limits should be run-time
configurable.) The distribution's infocard directory includes an example
program, demo_card_defs.php, which documents the program's arguments
and output syntax.
INFOCARD_CARD_FILL_URL (Optional1)
This optional directive is used by
dacs_sts(8)[88] to specify a web service that retrieves the values of
claims requested by a Relying Party. If it is not defined, only the value of
the default claim dacs_identity is available. Access to this web service must
be appropriately restricted and secured, although it does not need to be
DACS-wrapped. It is passed special DACS credentials (as an HTTP
cookie). The distribution's infocard directory includes an example program,
demo_fill_claims.php, which documents the program's arguments and
output syntax.
INFOCARD_CARD_IMAGE_BASE_URL (Required1-C)
This directive is required by
dacs_managed_infocard(8)[89]. It is the initial part of a DACS
VFS URI[92] from which image files for managed InfoCards can be
retrieved. The general idea is that the particular image associated with a
card depends on the STS authentication credential that is used by the card.
For example, the configuration variable infocard_card_image_passwd, if
set, specifies the filename (relative to INFOCARD_CARD_IMAGE_BASE_URL) of an
image associated with InfoCards that use the username/password type of
authentication between its owner and the STS; if unspecified, a compile-time
default (dacs_username_password_credential.png) is used. Similarly, the
variables infocard_card_image_cert (default value:
dacs_x509certificate_credential.png) and infocard_card_image_card
(default value: dacs_selfissued_credential.png) specify filenames for images
associated with the X.509 V3 certificate credential type and the self-issued
InfoCard credential type, respectively. The value of
INFOCARD_CARD_IMAGE_BASE_URL is typically the absolute pathname of a directory
containing the image files or the initial part of a URL to which a final path
component will be appended. Also see the CARD_IMAGE_URL[93] argument to
dacs_managed_infocard.
An image should be in the range of 60 pixels wide by 45 pixels high and 200
pixels wide by 150 pixels high. Only certain image formats are allowed by the
specification; the image format is deduced from the filename extension (case
insensitively): ".png", ".gif", ".tiff" (or
".tif"), ".bmp", and ".jpeg" (or
".jpg"). If the format cannot be deduced, PNG is assumed.
INFOCARD_CARD_LIFETIME_SECS (Optional1)
If INFOCARD_CARD_DATETIME_EXPIRES is not
defined, the expiration date and time of a managed InfoCard created by
dacs_managed_infocard(8)[89] can be specified relative to the current
time as this many seconds. If neither this directive nor
INFOCARD_CARD_DATETIME_EXPIRES is defined, a compile-time default lifetime is
used (currently, 365 days). Also see
INFOCARD_CARD_DATETIME_EXPIRES[94].
INFOCARD_CARD_OUTPUTDIR (Optional1)
If a managed InfoCard generated by
dacs_managed_infocard(8)[89] is stored in a file, it is written to this
directory. The name of the file is of the form
username_random.crd. See
INFOCARD_CARDID_BASE_URL[95].
INFOCARD_CARD_VERSION (Optional1)
This directive is used by
dacs_managed_infocard(8)[89] to provide a value for the CardVersion
element in a managed InfoCard. The default is "1".
INFOCARD_CARDID_BASE_URL (Required1-C)
This directive is required by
dacs_managed_infocard(8)[89]. It is used as the base URL for the CardId
of a new managed InfoCard. If this URL is set so that it points into the
directory specified by INFOCARD_CARD_OUTPUTDIR[96], then the resulting
CardId URLs can be used to fetch the card by its owner, assuming appropriate
access control rules are also configured. Also see
INFOCARD_CARDID_SUFFIX[97].
INFOCARD_CARDID_SUFFIX (Optional1)
This optional directive is used by
dacs_managed_infocard(8)[89] and specifies a string to be appended as a
final path element to the value of INFOCARD_CARDID_BASE_URL[95] to form
a new card's CardId. If the value of INFOCARD_CARDID_SUFFIX is:
identity
If the value of INFOCARD_CARDID_SUFFIX does not match (case-insensitively) any
of these strings, it is interpolated verbatim. Regardless of how it was
derived, the result string must be a syntactically valid URI path segment (
RFC 2396[98]).
INFOCARD_DIGEST (Optional1)
The specified or implied identity assigned to
the card is interpolated; this is the default.
username
The specified or implied username assigned to
the card is interpolated.
random
A safely-encoded 20-byte random string is
interpolated.
default
The default is used
("identity").
The name of the hash algorithm to use in
account files for self-issued InfoCard-based authentication (see
dacs_infocard(8)[99]). The syntax is the same as for the
PASSWORD_DIGEST[100] directive. The default is
"SHA256".
INFOCARD_IP_PRIVACY_URL (Required1-C)
This directive is required by
dacs_managed_infocard(8)[89] and specifies the URL of the Identity
Provider's PrivacyNotice. A default notice is configured.
INFOCARD_IP_PRIVACY_VERSION (Optional1)
This optional directive is used by
dacs_managed_infocard(8)[89] and specifies an integer version number
(greater than zero) of the document returned by the
INFOCARD_IP_PRIVACY_URL[101]. If it is set to the empty string,
however, no version number will be specified for the PrivacyNotice. The
default is "1".
INFOCARD_ISSUER_INFO_ENTRY (Optional)
This optional directive, which may be
repeated, is used by dacs_managed_infocard(8)[89] to specify arbitrary
descriptive information to be included in managed InfoCards. This information
may be displayed by an Identity Selector. The value of the directive is a
string of the form " EntryName:EntryValue".
INFOCARD_MEX_URL (Required1-C)
This directive, used by
dacs_managed_infocard(8)[89], specifies the URL of the
WS-MetadataExchange responder for managed InfoCards. Also see
dacs_mex(8)[102].
INFOCARD_REQUIRE_APPLIES_TO (Optional1)
Used optionally by
dacs_managed_infocard(8)[89], this directive controls a managed
InfoCard's RequireAppliesTo element, which by default is omitted. This element
is used to control whether the card's Identity Provider (e.g.,
dacs_sts(8)[88]) will be informed as to the identity of the Relying
Party via the wsp:AppliesTo element (when it is informed, it is called an
auditing card, which is used in auditing mode). Following the
Identity Selector Interoperability Profile, this directive may have any of the
following values:
no
INFOCARD_STRONG_RP_IDENTITY (Optional1)
The RequireAppliesTo element is omitted
(called a non-auditing card).
yes
RequireAppliesTo is emitted, but with its
optional attribute omitted (an auditing card).
true
RequireAppliesTo is emitted with the attribute
Optional="true" (called an auditing-optional card).
false
RequireAppliesTo is emitted with the attribute
Optional="false" (an auditing card).
Used optionally by
dacs_managed_infocard(8)[89], if the value of this directive is
"yes" RequireStrongRecipientIdentity is present in new managed
InfoCards, which indicates that a Relying Party must use a cryptographically
protected identity; i.e., an X.509 server certificate.
INFOCARD_STS_AUTH_TYPE (Required1-C)
This directive, required by
dacs_managed_infocard(8)[89], specifies (case-insensitively) the
authentication credential type, which identifies an Identity Selector user to
an IP/STS (see dacs_sts(8)[88]). The value of this directive is
consulted when a new managed InfoCard is created; the type may be changed
without affecting the authentication credential type assigned to InfoCards
created before the change. Recognized values are:
password
passwd
Note
Although the specification allows an ordered list of STS endpoints to appear, at
present only a single endpoint may be configured.
INFOCARD_STS_CACERTFILE (Required1-C)
This is the username/password credential type.
See INFOCARD_STS_PASSWORD_METHOD[103].
cert
This is the X.509 V3 certificate credential
type. An SSL client certificate must be used with the request to
dacs_managed_infocard(8)[89] for a managed InfoCard, and the same
certificate must be used when the managed InfoCard is submitted to a Relying
Party. A self-signed certificate may be used.
card
This is the self-issued credential type. A
self-issued InfoCard must be submitted with the request to
dacs_managed_infocard(8)[89] for a managed InfoCard, and the same
self-issued InfoCard must be available to the user's Identity Selector when
the managed InfoCard is submitted to a Relying Party. This self-issued
InfoCard does not need to be separately registered using
dacs_infocard(8)[99].
kerberos
This is the Kerberos V5 credential type. This
authentication credential type is currently unsupported.
This directive, which is required by
dacs_managed_infocard(8)[89], specifies the filename of the certificate
authority's PEM-encoded X.509 certificate for
INFOCARD_STS_CERTFILE[104].
Note
File permissions and ownership must be set appropriately to allow run-time
access.
INFOCARD_STS_CERTFILE (Required1-C)
This directive, which is required by
dacsinfocard(1)[105], dacs_infocard(8)[99], and
dacs_managed_infocard(8)[89], specifies the filename of the PEM-encoded
X.509 certificate for the Secure Token Service provided by
dacs_sts(8)[88].
Note
File permissions and ownership must be set appropriately to allow run-time
access. If a self-signed certificate is being used, the appropriate root
certificate must be installed on the system that is running the Identity
Selector.
INFOCARD_STS_KEYFILE (Required1-C)
This directive, which is required by
dacsinfocard(1)[105], local_infocard_authenticate[106],
dacs_infocard(8)[99], dacs_managed_infocard(8)[89], and
dacs_sts(8)[88], specifies the filename of the key for the X.509
certificate specified by INFOCARD_STS_CERTFILE. If this file is password
protected, INFOCARD_STS_KEYFILE_PASSWORD[107] must be configured.
Note
File permissions and ownership must be set appropriately to allow run-time
access.
INFOCARD_STS_KEYFILE_PASSWORD (Required1-C)
If INFOCARD_STS_KEYFILE[108] is
encrypted, this directive is required to specify the password.
INFOCARD_STS_PASSWORD_METHOD (Required1-C)
If the username/password credential type is
needed by a managed InfoCard, dacs_sts(8)[88] requires this directive
to specify how the username and password are to be validated:
empty
INFOCARD_STS_RP_ENDPOINT (Optional)
The password is no password at all (i.e., the
empty string). If a password is given, authentication will fail.
ignore
Any password string, including no password at
all (i.e., the empty string), is acceptable.
sts
The given password string must exactly match
the authentication-time value of the configuration variable
infocard_sts_password.
account: id
The given username and password must be valid
relative to the specified DACS authentication module identified by the
Auth clause label id, which must be enabled and configured as per
dacs_authenticate(8)[48]. (Note: This form is currently
unsupported.)
This directive causes dacs_sts(8)[88]
to issue security tokens only to selected identified Relying Parties; if the
identity of a Relying Party, as provided by the Address endpoint appearing in
the token request's AppliesTo element (apparently the URL of the Relying
Party's web page) does not match any instance of this directive, a token will
not be returned. A token will be returned if this directive is not used or if
the Relying Party is not identified. Not all Relying Parties are identified;
see INFOCARD_REQUIRE_APPLIES_TO[109]. The syntax for this directive is
identical to that of INFOCARD_AUDIENCE[110]. Although the Relying
Party's server certificate can be provided with the identification material in
the token request, it is not currently accessible to this directive.
INFOCARD_STS_URL (Required1-C)
This directive, used by
dacs_managed_infocard(8)[89], dacs_mex(8)[102], and
dacs_sts(8)[88], specifies the URL of the Secure Token Service for
managed InfoCards.
INFOCARD_TOKEN_DRIFT_SECS (Optional1)
A security token (produced by
dacs_sts(8)[88], for instance) bears a validity condition; a relying
party may reject a token if its current system date/time lies outside of the
time window prescribed by the token. Because the clock at the IP/STS (which
issued the token) and the clock at the relying party may not be closely
synchronized - the relying party's clock may be faster or slower than the
IP/STS's clock - a relying party may be willing to permit a certain amount of
"clock drift" before it rejects a token. This directive specifies
the maximum number of seconds that the IP/STS's clock may be too fast or too
slow. If the directive's value is zero, or if the directive is not configured,
a compile time default value is used (currently, 300 seconds). If the
directive's value is "disable", the validity test is
suppressed.
INFOCARD_TOKEN_ISSUER (Required1-C)
This directive, used by
dacs_managed_infocard(8)[89] and dacs_sts(8)[88], specifies the
Issuer of a managed InfoCard as a URI. The value "self" can be used
to represent the special URI identifying a self-issued InfoCard.
Note
If your Identity Selector does not let you choose a managed InfoCard when you
think that it ought to (i.e., the value of this directive in effect when the
managed InfoCard was created matches the web page's issuer parameter), it
seems that the INFOCARD_TOKEN_ISSUER is ignored by an Identity Selector in
preference to the name in the Identity Provider's SSL certificate. It has been
noted that if a Relying Party uses a wildcard certificate[111], an
Identity Selector may have trouble matching the issuer parameter in an
HTML OBJECT request with an InfoCard; it may be necessary for the Relying
Party to specify the value of the issuer parameter as the empty string.
INFOCARD_TOKEN_LIFETIME_SECS (Optional1)
This optional directive specifies the
lifetime, in seconds, of a secure token created by dacs_sts(8)[88]. If
not provided, a compile-time value is used. To reduce the window of
vulnerability where a token might be captured and used by an attacker, this
period should be relatively short (on the order of a few seconds). Note that a
Relying Party is free to account for inadequately synchronized clocks when
deciding whether it should accept a token, so this lifetime is effectively a
recommendation for the recipient of the token. If the clocks at the Identity
Selector and token issuer are not sufficiently synchronized, the Identity
Selector will reject a token if the token's validity window is outside of its
clock's current value.
INFOCARD_TOKEN_MAX_LENGTH (Optional1)
A relying party can use this directive to
specify the maximum size (in bytes) of a security token that it will accept.
If this directive is not configured or is zero, a compile time default value
is used (currently, 16384 bytes).
INFOCARD_USERNAME_SELECTOR (Optional1)
This directive determines how the DACS
username is selected for a self-issued InfoCard during registration by
dacs_infocard(8)[99]. The resulting identity is relative to the
current jurisdiction[44]; that is, if the InfoCard is used to sign on
at a jurisdiction where it was registered, the jurisdiction will issue
credentials for the username that was registered with the InfoCard. The
following directive values are recognized:
credentials
JURISDICTION_NAME (Required1)
The username is obtained from the identity in
effect at registration time; there may only be one such set of credentials and
they must have been issued by the jurisdiction at which registration is
occurring. This is the default behaviour if the directive is not given.
email
The username is obtained from the email
address field of the InfoCard; the email address must be a syntactically valid
username (see dacs(1)[74]).
webpage
The username is derived from the web page URL
field of the InfoCard; this is not currently implemented. (see
dacs(1)[74]).
The name of the jurisdiction. The syntax is
the same as for FEDERATION_NAME[53]: an alphabetic followed by zero or
more alphanumerics, '-' (hyphens), or '_' (underscores). Note that periods are
not permitted. By convention, this name is in all-caps, Please see
dacs(1)[74] for additional information. Example: METALOGIC
LOGINGEN_FILE (Optional1)
Reserved for future use. (Used with the
DACS logingen utility, this directive gives the full pathname of
the template file.)
LOGINGEN_PROG (Optional1)
Reserved for future use. (Used with the
DACS logingen utility, this directive specifies a program which
will read LOGINGEN_FILE on its stdin and write the filtered output to
stdout.)
LOG_FILE (Optional1)
DACS uses the LOG_FILE directive to
identify the primary file to which it should write log information.
DACS performs directory name interpolation on the pathname string using
a syntax and method similar to Apache's
mod_vhost_alias[7] module (see String Interpolation[22]).
The result after interpolation must either be the absolute pathname of a file to
write log information to, or the word "syslog". In the latter case,
syslog(3)[112] is used, with an ident argument of
"dacs" and a facility of "user". Each DACS logging
level is mapped to the corresponding syslog level, with the trace level
mapped to syslog's debug level.
While DACS is starting and before it reads and processes its
configuration files, this directive is not yet available to it; until
DACS knows what LOG_FILE is, or should LOG_FILE not be writable, the
value of LOG_FILE is obtained from the value of DACS_LOG. A compile-time
specified value, DACS_LOG can be specified when DACS is built (the
default is equivalent to ${Conf::DACS_HOME}/logs/error_log). If DACS_LOG is
unusable, stderr is used.
LOG_FILTER (Stack)
This directive configures a fine-grained way
of specifying which messages will be written compared to the
LOG_LEVEL[113] directive. The directive, which may be repeated, selects
the types of events that DACS should log; unselected events are
not recorded in a log file. It also provides a way for different kinds of
messages to be logged to different files.
Because this directive is in the Stack category[12], "later"
directives supercede earlier ones. When a directive is found that allows a
message to be logged, no additional directives are examined for the message.
If this directive is not given, the default filtering is done based on the
LOG_LEVEL and LOG_SENSITIVE directives.
The syntax is one of:
The type, which is one of the keywords program, module, filename, or
function (case insensitive), specifies the type of the event source to which
this filter applies; i.e., it indicates what name is to be matched
against. If type is filename, for instance, it means that for this
filter to be applicable to a particular log message, the name must
match the filename from which the log message is generated.
A list of comma-separated, case-insensitive modifier flags specifies how
matching of type is done against name. A flag can have
the value exact, regex, icase, sensitive, user, audit, or normal.
The name is matched against type case sensitively, unless the
icase flag is present. Matching is performed using regex(3)[114]
regular expression matching if the regex flag is present, or using a string
comparison if the exact flag is present (these two flags are mutually
exclusive).
A message can have no attributes associated with it, or any combination of the
attributes sensitive, user, and audit. Messages with the sensitive attribute
might include potentially private information, such as a password. Messages
with the audit attribute include relatively high-level events, such as
successful and unsuccessful authentication results, signouts, and access
control decisions. The user attribute is associated with messages produced by
the print()[115] and printf()[116] functions.
Modifier flags are used to select (or deselect) messages to be logged. By
default, only normal messages are logged; these are messages without any
attributes. The LOG_SENSITIVE[117] directive can change the default to
enable sensitive messages.
If the audit flag is given, a message is logged only if it has that attribute.
Messages with the sensitive attribute are not logged unless the sensitive flag
is given, and messages with the user attribute are not logged unless the user
flag is given.
Assuming the type and level do not deselect the message, here are
some example cases:
If the directive's value begins with the keyword any, the filter matches any
source, so there is no name and the modifier flags related to matching
name are ignored.
In order of increasing importance and decreasing amount of detail, level
is one of the following case-insensitive keywords:
Any log message having a lower importance than level will not satisfy the
filter. If the logging level is set to info, for example, messages having a
lower level (debug and trace) will not be recorded. These levels are intended
to have semantics similar to those of the logging levels used by Apache
and syslog(3)[112].
The file field, which is optional, is used instead of (or in addition to)
LOG_FILE and interpolation is performed in the same way. If file is
syslog, all messages matching the filter will be written using
syslog(3) instead of to LOG_FILE. If file is prefixed with a
'+', output will be written to both LOG_FILE and the expansion of file;
if it is prefixed with nothing or -, the default behaviour results; the
initial character can be escaped using a backslash. In some situations, using
/dev/null for file is useful to discard unhelpful messages.
Without regard to how LOG_LEVEL and LOG_SENSITIVE are configured, this directive
says that all messages generated by any function located within the
DACS source file named crypto.c having a level of at least debug,
should be logged, including those marked as sensitive:
Tip
The directive:
causes all log messages with the audit modifier having level trace or higher to
be written to both syslog(3) and LOG_FILE. If you want to use the
syslog feature in this way, you will need a section in the syslog(3)
configuration file (typically /etc/syslog.conf) that looks something like the
following, depending on the flavour of syslog(3) that your system uses:
The following directive is similar except that it causes log messages classified
as either audit or sensitive (or both) to be written to both LOG_FILE and the
file logs/Audit_log, relative to the root of the DACS installation
directory:
By removing the '+' character, the log messages would not be written to
LOG_FILE.
Please refer to dacs(1)[118] for general information about logging.
LOG_FORMAT (Optional1)
LOG_FILTER " type flag[,flag]* level name [[+|-]file]" LOG_FILTER "any flag[,flag]* level [[+|-]file]"
•a message without any attributes will
be logged provided the audit flag is not specified
•a message with both the audit and
sensitive attributes will be logged only if the filter specifies the audit
flag, and either the sensitive flag is given or LOG_SENSITIVE is enabled
•
trace (or tracing, least important messages)
•
debug (or debugging)
•
info
•
notice (or notices)
•
warn (or warning or warnings)
•
error (or errors)
•
critical (or crit)
•
alert (or alerts)
•
emerg (or emergency, most important messages)
LOG_FILTER 'filename exact,sensitive debug crypto.c'
LOG_FILTER 'any audit trace +syslog'
!dacs *.* /usr/local/dacs/logs/audit_log
LOG_FILTER 'any audit,sensitive TRACE +%bD/logs/Audit_log'
This directive is used to specify the format
of log messages produced by DACS. Interpolation is controlled by
printf-like format specifiers, as follows:
%%
If a % is followed by any other character, that character is printed. Other
characters in the format specifier are interpolated verbatim. If a requested
value is not available, nothing is interpolated.
LOG_LEVEL (Optional1)
Insert a literal percent character
%a
Insert the application name, which is
typically the basename of argv[0].
%c
Insert the value of a per-process message
counter, which is then incremented.
%F
Insert event descriptor flags, which indicate
whether the message is an audit event ("A"), a potentially sensitive
event ("S"), a user event ("U"), or a normal event
("-").
%fn
Interpolate the federation name.
%fd
Interpolate the federation domain.
%j
Interpolate the jurisdiction name.
%l
Interpolate the log level of the
message.
%p
Interpolate the process id of the process
generating the message.
%sF
Interpolate the name of the function
generating the message.
%sf
Interpolate the name of the file generating
the message.
%sl
Interpolate the line number within the file
that is generating the message.
%sm
Interpolate the name of the module generating
the message.
%sp
Interpolate the name of the program generating
the message.
%t
Interpolate the current time and date.
This directive specifies the minimum default
logging level in effect - log messages less important than this will be
discarded. For example, if LOG_LEVEL is warn, only log message of that level
or more important will be written and all others will be discarded. If there
is an applicable LOG_FILTER[119] directive it overrides this behaviour,
however.
Briefly, in order of increasing importance, the names of the levels are: trace,
debug, info, notice, warn, error, critical, alert, and emerg. The trace
logging level emits the most detail and the emerg level emits the least. Refer
to the LOG_FILTER[119] directive for additional information.
The LOG_LEVEL overrides the compile-time default, which is obtained using the
LOG_DEFAULT_LEVEL symbol.
The "verbose" command line flag ( -v) or the VERBOSE_LEVEL
directive overrides this directive, which are in turn overridden by the
-t command line flag ("trace") or the TRACE_LEVEL directive.
A verbose level of one is equivalent to the info level; a verbose level
greater than one is equivalent to the debug level. Enabling a trace level,
with any value, is equivalent to requesting the trace logging level.
Also see debug_dacs[120].
LOG_SENSITIVE (Optional1)
This directive determines the default
behaviour for logging messages with the sensitive attribute. It may have the
values "yes" (to enable logging sensitive messages) or
"no" (the default, which discards such messages).
Note
Sensitive messages may include passwords and other authentication material that
should remain private. This directive will not suppress potentially sensitive
messages generated by third-party support packages (e.g., Samba or
OpenLDAP), Apache (including mod_auth_dacs), or the
operating system. For example, requests for CGI programs invoked using the GET
method will be logged in the Apache Access Log, and the request's query
string will typically be printed; password parameters may be present in the
log (see mod_log_config[121] for details of how to change the log
format. If sensitive messages are being logged, make doubly-sure that log
files have appropriate permissions. Also, unencrypted logging messages
directed over a network (e.g., through syslog(3)[112]) may be visible
to an attacker.
NAME_COMPARE (Optional1)
This directive sets the default method used to
compare DACS names in various contexts. Ordinarily, federation,
jurisdiction, usernames, and group names are compared case-sensitively. If the
value of this directive is case, then case-sensitive comparisons are used, if
its value is nocase, then case-insensitive comparisons are used, and if its
value is default, then the application default (either case or the value
selected by the application) is used. This directive can be overridden on a
case-by-case basis (pun intended); refer to the user() function (
dacs.exprs(5)[18]) for details.
Security
The selected comparison method applies to all components of DACS
names; if this is not desired, the strtr() function might be helpful.
Note that this directive does not alter the DACS name determined by
authentication, only the way the name is compared. While it's unlikely (and
bad practice) for federation names (or jurisdiction names) to differ only in
their case, it is not unusual for usernames to be treated case-insensitively
for authentication purposes and for this reason this feature should be used
with care. When case-insensitive comparisons are used, the usernames bob and
BOB will be considered to be equivalent, for example; sometimes this is useful
but it can also be a security hole, depending on how authentication is
configured.
Changing the comparison method from case-insensitive back to case-sensitive may
have undesirable consequences; identities that were formerly equivalent might
suddenly become distinct, which at the very least may confuse users.
The recommended practice is to not define NAME_COMPARE or set it to case because
of its system-wide effects. When needed, use the user() function with
an appropriate comparison method argument.
NOTICES_ACCEPT_HANDLER (Optional1)
This directive provides a URL (absolute or
relative) to which a user agent will be redirected by the notice
acknowledgement handler after a positive acknowledgement to a notice has been
received (i.e., when the notice or notices were "accepted"), but
only if it is not possible to redirect the user agent to the request that
initiated notice acknowledgement processing (e.g., if that request used the
POST method). If not provided, a default HTML page will be returned.
NOTICES_ACK_HANDLER (Optional1)
This directive provides the URL of the notice
acknowledgement handler, which is the program that receives a user's response
to a request to acknowledge one or more notices. If not provided or if it is
the empty string, the notice presentation handler should assume that it must
also act as the notice acknowledgement handler.
NOTICES_DECLINE_HANDLER (Optional1)
This directive provides a URL (absolute or
relative) to which a user agent will be redirected by the notice
acknowledgement handler after a negative acknowledgement to a notice has been
received (i.e., when the notice or notices were "declined"). If not
provided, a default HTML page will be returned.
NOTICES_NAT_NAME_PREFIX (Optional1)
The default prefix of the name of the HTTP
cookie bearing a notice acknowledgement token is "NAT-DACS". This
directive can be used to override the default.
NOTICES_SECURE_HANDLER (Optional1)
By default, dacs_notices(8)[122] takes
steps to prevent attempts to simply ask for notice acknowledgement tokens
(NATs), effectively bypassing having to see notices. If the value of this
directive is "no", however, these steps will be disabled. Please
refer to the description of dacs_notices' Secure Mode[123] of
operation.
NOTICES_WORKFLOW_LIFETIME_SECS (Optional1)
By default, a secure notice acknowledgement
workflow must complete within 120 seconds. This directive can be used to
specify an unsigned integer value that will override the default.
PAMD_HOST (Optional1)
When local_pam_authenticate[124] is
used, this directive is required to specify the domain name or IP address of
the host where pamd(8)[125] is executed.
PAMD_PORT (Optional1)
When local_pam_authenticate[124] is
used, this may be used to specify the port number or service name on PAMD_HOST
where the pamd(8)[125] server accepts connections. This directive can
be overridden on the pamd command line. If no value is explicitly
specified, programs will use the compile-time symbol PAMD_SERVICE_NAME (by
default, "dacs-pamd"), which assumes that /etc/services has been
configured accordingly.
PASSWORD_CONSTRAINTS (Optional1)
This directive describes requirements that
must be met by new passwords created by dacs_passwd(8)[126], other than
when used by a DACS administrator. In other situations, where a
DACS administrator must be running the program (such as with
dacspasswd(1)[127] or dacstoken(1)[128]), a warning message is
produced if a new, non-conforming password or PIN is set but the password can
still be used.
This directive's syntax is also used by the PASSWORD_AUDIT[129]
directive, which may appear in an Auth clause.
The format of the constraint string is a set of zero or more comma-separated
terms. Each term consists of an unsigned integer (zero or greater) followed
immediately by a single character (case sensitive) that indicates a
constraint type:
A constraint type may not appear more than once. Not all constraint types need
to be specified. If this directive is not given, or is the empty string, or
the word "none" (case insensitive), a minimum password length of any
six characters is used. If a constraint type is missing, a minimum of zero is
used. In no event is a password of fewer than six characters allowed for a
non-administrator, however.
Security
No check is made for constraints that are impossible to satisfy.
For example, the following directive says that passwords must be at least eight
characters long and include at least one digit and one upper case and one
lower case character, with no punctuation characters required:
PASSWORD_DIGEST (Optional1)
•L refers to the minimum length of a
password, in characters;
•C is the minimum number of characters
from each case that must be present (e.g., 3C means a password must
have at least three upper case characters and three lower case
characters);
•D is the minimum number of digits (0-9)
that must be present;
•and P is the minimum number of
punctuation characters (see ispunct(3)[130]) that must be
present.
PASSWORD_CONSTRAINTS "8L,1D,1C,0P"
By default, SHA-1 is used as the secure hash
function by dacstoken(1)[128], dacspasswd(1)[127],
dacstoken(1)[128], dacs_passwd(8)[126], and
dacs_admin(8)[131] for computing password digests. The value of this
directive can be (case insensitively):
CRYPT
SHA224
SHA256
SHA384
SHA512
The system crypt() function may have platform-dependent limitations on
the number of characters that are significant in a password or the maximum
length of a password, but the other digest algorithms use all of the
characters and impose no maximum password length. .sp The digest algorithm
used is stored with the password entry, so the algorithm can be changed
without voiding pre-existing passwords.
PASSWORD_OPS_NEED_PASSWORD (Optional1)
for the Unix crypt(3)[132]
function
MD5
for the MD5 function[133]
(deprecated).
SHA1
, , , , for one of the variants of the Secure
Hash Standard ( FIPS 180-3[134]).
Ordinarily, dacspasswd(1)[127] will not
allow password maintenance operations (other than listing) unless the user has
authenticated as an ADMIN_IDENTITY[135] or provides a valid password
for the username being administered (one that was created by
dacspasswd(1)[127]). If this directive is "no", a password is
not required and dacspasswd will assume that all necessary access
control has already been performed.
PASSWORD_SALT_PREFIX (Optional1)
This string is prepended to a random salt
string used when creating a digest of a password used by DACS in
various contexts (e.g., dacspasswd(1)[127]). This may be of interest
when PASSWORD_DIGEST[100] is CRYPT because some versions of
crypt(3)[132] interpret the salt string.
PERMIT_CHAINING (Optional1)
If "yes", credentials exported by
dacs_acs(8)[5] anywhere in the federation as a result of a rule having
the permit_chaining attribute set to yes will be honoured at this jurisdiction
for access control purposes.
Security
Enabling this feature weakens security because it may allow misappropriated
DACS identities to be used at a jurisdiction that has enabled
PERMIT_CHAINING. Use of this feature is discouraged but is sometimes
necessary; use with care. Refer to the description of the permit_chaining
attribute in dacs.acls(5)[23].
PROXY_EXEC_DOCUMENT_ROOT (Optional1)
Reserved for future use.
PROXY_EXEC_MAPPER_DEFAULT_ACTION (Optional1)
Reserved for future use.
PROXY_EXEC_MAPPER_LOGGING (Optional1)
Reserved for future use.
PROXY_EXEC_MAPPER_LOG_FILE (Optional1)
Reserved for future use.
PROXY_EXEC_MAPPER_RULES_FILE (Optional1)
Reserved for future use.
PROXY_EXEC_PROG_URI (Optional1)
Reserved for future use.
RLINK (Optional)
This directive, which may be repeated, is used
to determine whether the current request includes an Rlink[136]. The
RLINK directives are processed in the order in which they occur. The value of
the directive is a space-separated pair: the first is an expression[18]
that is evaluated at rule-processing time, and the second is a VFS
specification[137] for the location of the Rlinks (i.e., a DACS
URI, an item type, or an absolute pathname). If the expression evaluates to a
non-empty string:
If the expression evaluates to the empty string or an error occurs, the
directive is ignored and the next one, if any, is processed. Example:
In the example above, the directive specifies that if the current request
includes a non-empty argument called RNAME, then its value is an Rname,
Rlink processing is enabled, and the Rlink can be found in the
/usr/local/dacs/rlinks directory.
ROLE_STRING_MAX_LENGTH (Optional1)
•the string is assumed to be an
Rname[136], which is relative to the VFS specification,
•Rlink processing is enabled for the
current request, and
•no other RLINK directives are
considered or evaluated.
RLINK '"${Args::RNAME:?}" /usr/local/dacs/rlinks'
A limit is imposed on the length of the role
string returned by any authentication or roles service, the length of any
intermediate role string formed by concatenation during determination of the
role string, and the length of the final role string, which is used in
credentials. A string that exceeds the limit is invalid and treated as an
empty string. The limit is necessary because credentials (which may contain a
role string) are encapsulated within an HTTP cookie and browsers have
context-dependent and implementation-dependent restrictions on cookie lengths.
This directive is used to set the limit, overriding a compile-time value of
200 bytes. Please refer to dacs_authenticate(8)[46] for additional
information about roles.
Warning
A role string that is too long may cause the user to experience strange and
possibly incorrect behaviour from DACS because the browser may discard
cookies produced by DACS.
SECURE_MODE (Optional1)
This directive causes DACS to operate
"insecurely" only if its value is "no" or "off"
(case insensitive), otherwise DACS will use a more secure mode of
operation. In secure mode, DACS requires all user interactions to be
through SSL (HTTPS) and cookies will have the secure attribute. The default is
"yes". Odd behaviour may result if interactions between DACS
and a particular client mix http and https requests (such as when handlers are
involved).
Security
Always use the secure mode of operation unless you fully understand the
consequences of disabling it. For DACS to be a secure system, secure
mode should be disabled only for testing purposes or if all HTTP traffic is
protected by some secure means other than SSL.
SIGNOUT_HANDLER (Optional1)
After dacs_signout(8)[31] successfully
logs a user off, the subsequent action can be customized. In particular, this
directive provides a way for the system administrator to redirect the user's
browser, such as back to a login page.
The following syntaxes are supported:
The optional keywords are treated case-insensitively.
SSL_PROG (Optional1)
1.SIGNOUT_HANDLER "[url]
URL"
This form will cause DACS to redirect the client to the specified URL,
which may be a relative or absolute URL. If the keyword url is absent,
URL must begin with the four characters http. The GET method is used.
The URL may contain a properly escaped query string; DACS will append
the following parameters, in the order given, to the URL:
DACS_VERSION
The values of these parameters are URL encoded.
The version number of DACS (e.g.,
"1.4").
DACS_FEDERATION
The federation that received the service
request, if available.
DACS_JURISDICTION
The jurisdiction that received the service
request, if available.
2.SIGNOUT_HANDLER "[file]
full-pathname"
This form causes the contents of the file named by full-pathname to be
returned. The file must include any header lines it requires, such as a
Content-Type line, a header-terminating blank line, and then the document
content.
Note
The "full-pathname" usage differs from the "local-URL" usage
of the ACS_ERROR_HANDLER directive, though both elements begin with a slash
character; the former specifies the absolute pathname of a file, while the
latter specifies a URL local to the receiving web server. To specify a
relative URL, use the url keyword.
3.SIGNOUT_HANDLER "[message]
\"message\""
This form causes the given message, surrounded by escaped double quote
characters, to be returned as HTML.
4.SIGNOUT_HANDLER "credentials"
This form causes the user's remaining credentials to be displayed as an HTML
document. This is the default behaviour.
The full pathname of the command used to
provide an SSL connection for group information distribution. Currently, only
sslclient(1)[138] is supported for this purpose.
SSL_PROG_ARGS (Optional1)
Additional command line arguments to be passed
to SSL_PROG.
Note
This directive is "global" in that it applies to all internal
invocations of SSL_PROG. SSL options should probably be more flexibly
configurable (e.g., from within Auth and Roles clauses).
SSL_PROG_CA_CRT (Optional1)
The full pathname of the file containing the
CA certificate shared by this DACS federation. This is passed to
SSL_PROG so that certificates can be validated.
SSL_PROG_CLIENT_CRT (Optional1)
This provides the name of a private key and
certificate chain PEM file. Please refer to sslclient(1)'s[138]
-ccf flag.
STATUS_LINE (Optional1)
If this directive is set to "on",
dacs_acs(8)[5] will emit a DACS-Status-Line[139] header in the
response from the server. The default value is "off". See the
description of the DACS_ACS argument[47] for additional details.
TEMP_DIRECTORY (Optional1)
A directory where DACS can create
temporary files. If the value is not an absolute path, the location is
relative to DACS_HOME[140]. Lock files, for example, are put in this
directory. If not configured or if this directory does not exist, a
compile-time path (DEFAULT_TEMP_DIRECTORY) is used (currently: /tmp). It is
always safe to delete the contents of this directory if DACS is not
running.
TOKEN_REQUIRES_PIN (Optional1)
If set to no, then dacstoken(1)[128]
does not require created or imported accounts to have a PIN. The default value
is yes, and a PIN is required.
TOKEN_HOTP_ACCEPT_WINDOW (Optional1)
When validating or authenticating against a
given one-time password, this is the maximum number of successive counter
values to consider, if necessary, after the expected counter value. A value of
zero disables this search. If not configured, a compile-time value is used
(currently, 3).
TRACE_LEVEL (Optional1)
If assigned a non-zero value, tracing is
enabled in various DACS services. Larger values will cause more events
to be traced. This is intended to give an indication of the steps a
DACS service takes during execution for debugging purposes. Logging
information is generally written to the web server's log file or to a file
configured into DACS at compile time. Also see LOG_LEVEL and
VERBOSE_LEVEL.
UNAUTH_ROLES (Optional1)
This directive is used to assign a role
descriptor string[141] to unauthenticated users. Association with
these roles can be tested using the user()[142] predicate.
If a jurisdiction configures this directive:
then the following predicates would both return True when applied to an
unauthenticated user:
A useful application of this directive is to classify unauthenticated users
based on contextual elements. Consider this directive:
If an unauthenticated user submits a request from a local IP address between
10.0.0.0 and 10.0.0.255, the user would be treated as having the role user,
otherwise the user would have no roles. This might be used to conveniently
grant limited access to "local" users without them having to
authenticate. A rule could be written to grant access based on having the role
user, for example, without needing to consider whether or not the user has
authenticated.
Unlike roles assigned to credentials, roles specified in this way are strictly
local to the jurisdiction that configures them. Some form of coordination is
required if different jurisdictions need to assign the same roles to
unauthenticated users. These roles are not reported by
dacs_current_credentials(8)[86].
UPROXY_APPROVED (Stack)
UNAUTH_ROLES "anonymous"
user("unauth")
user("%:anonymous")
UNAUTH_ROLES from("10.0.0.0/24") ? "user" : ""
This directive is used by
dacs_uproxy(8)[143] to enable proxying to one or more hosts and to
configure each of those mappings. Each directive specifies a member of the
"approved list" (i.e., a host that may be proxied) using the
following syntax:
dacs_uproxy is invoked with a URI with the following syntax:
A proxied-hostname is matched against the hostname of each entry
in the list, according to the stacked directive ordering, until a (case
insensitive) match is found. If the proxied-hostname is followed by a
port number, that port number must be explicitly specified in a directive for
a match to occur. If no scheme is specified, http is used, regardless of what
protocol the port may imply. If a path is given, it is appended
to the proxied-path-prefix.
For example, consider the directives:
A request for the proxied hostname foo.example.com, such as this:
will be forwarded by dacs_uproxy as the URI:
And the proxied request:
will be forwarded by dacs_uproxy as the URI:
This request would fail because there is no approved entry for
bar.example.com:80:
VERBOSE_LEVEL (Optional1)
[{'http' | 'https'} '://'] hostname [:port] [path]
.../dacs_uproxy/ proxied-hostname[:proxied-port][proxied-path-prefix]
UPROXY_APPROVED "example.com" UPROXY_APPROVED "https://foo.example.com" UPROXY_APPROVED "http://bar.example.com:8080" UPROXY_APPROVED "https://baz.example.com:8443/some/path"
.../dacs_uproxy/foo.example.com/a/b/c.cgi
.../dacs_uproxy/baz.example.com/a/b/c.cgi
.../dacs_uproxy/bar.example.com:80/a/b/c.cgi
If assigned a non-zero value, debugging output
is enabled in various DACS services. Larger values will cause more
output to be generated. This is intended to display input arguments and the
values of variables as a DACS service is executed, for debugging
purposes. Logging information is generally written to the web server's log
file or to a file configured into DACS at compile time. Also see
LOG_LEVEL and TRACE_LEVEL.
VERIFY_IP (Required1)
If "yes", then the IP address in
credentials must exactly match the IP address from which a service request is
made. For example, if DACS issued credentials in response to an
authentication request that came from the IP address 10.0.0.123, then these
credentials will only be considered valid for service requests that come from
that IP address. If the directive's value is "no", this verification
is not performed. Any other value is assumed to be a valid argument to the
from()[144] predicate:
Tip
Verification might be turned off, for example, in an environment where a user
might legitimately submit service requests associated with different IP
addresses. Refer to dacs_authenticate(8)[59] for additional
information.
VERIFY_UA (Optional1)
# Only credentials that were issued to an address on this subnet # are acceptable VERIFY_IP "10.0.0.0/24"
If "yes", then the user agent string
presented when authentication occurred (the USER-AGENT request header,
exported by Apache as HTTP_USER_AGENT) must match the user agent
string that is sent with subsequent requests using those credentials. This is
the default. If the directive's value is "no", this verification is
not performed at this jurisdiction but credentials it produces can still be
verified by other jurisdictions. If the directive's value is
"disable", the feature is totally disabled at this jurisdiction. The
feature is always disabled for certain internally-generated credentials.
Security
In typical use of DACS, this feature should be enabled because it makes
it somewhat more difficult for misappropriated DACS credentials to be
used. It is not a foolproof measure, however, because a sophisticated attacker
may be able to obtain or guess a user agent string and use it with stolen
credentials, although guesses may draw attention by causing log messages to be
emitted.
Some user agents, including http(1)[3], Mozilla, Firefox,
curl, wget, and Konqueror, allow the user agent string to
be set. Including a random or unusual component in the string will strengthen
this feature. Also, middleware may be able to take advantage of its ability to
send a string of its choosing in the User-Agent header field.
Verification might be turned off, for example, in proxying situations or if
credentials are cached by middleware and then legitimately used with different
user agents. The feature should be disabled for backward compatibility with
releases earlier than DACS 1.4.14.
VFS (Stack)
These directives are used to configure the
virtual filestore (VFS) subsystem (see dacs.vfs(5)[145] and
dacsvfs(1)[146] for details).
The value of this directive (a vfs_uri) has the following syntax:
As specified in RFC 2396[98] and RFC 3986[147], the general form
of the URI syntax is:
The item_type (see dacs(1)[148]) is optional in some cases - it
can usually be omitted if the directive will not be referenced and if it does
not refer to an indexed object. It is a case-sensitive label that associates
this directive with a class of objects used by DACS. Some labels are
reserved and have predefined meaning to DACS; these are always
lowercase; dacsconf(1)[1] can list them. Any label can be defined by a
DACS administrator, but a reserved item type should only be defined for
its intended use; user-defined item types should therefore include at least
one uppercase letter. For example, here are a few reserved item types: passwds
(used by dacspasswd(1)[127] and others), federation_keys and
jurisdiction_keys (used by dacskey(1)[149] and others), revocations
(used by dacs.acls(5)[23] and others), and stdin (used by
get()[150] and others).
Although the scheme is case-insensitive, the canonical form is lowercase.
The authority, query, and fragment URI components are
often absent. The query component is used to specify options.
The path component of a URI has the format:
For paths that have a separate key relative to the naming context, its start is
delimited by a comma.
The scheme may be:
dacs-db
fs
file
https
A vfs-ref is a reference to a virtual filestore definition and can be a vfs_uri
or an item_type defined by a VFS directive. In some situations it can also be
an absolute pathname.
Note
At present, the VFS does not implement much in the way of concurrency control.
Some DACS components use coarse-grained locking to ensure that only a
single user can access resources, however, and databases may implement their
own concurrency control. Only a few of these resources are not used in a
read-only fashion; administrators should adopt appropriate data management
practices for them to ensure concurrent updates cannot occur.
XSD_BASE_URL (Optional1)
vfs_uri -> [ '[' item_type ']' ] URI
scheme : [ // authority] [path] [query] [fragment]
[ naming_context ] [ "," rel-path ]
A Berkeley DB[151], a hash-based
database that manages a collection of objects within a regular file. The
item_type is required because it forms the initial part of the
key.
dacs-ndbm
The Unix dbm(3)[152] API (includes
GNU gdbm[153]), which is similar to dacs-db. The item_type is
required because it forms the initial part of the key.
dacs-fs
Files and directories managed through
filesystem operations. Where path names a directory, each key maps to a
regular file within that directory.
dacs-sqlite
An SQLite[154] database that manages a
collection of objects within a regular file. The item_type is required
because it is used as the SQL table name.
http
HTTP-based object access. For example,
example.com might configure access to its revocation list like this (with
appropriate access controls):
dacs-kwv
VFS "[revocations]https://example.com/dacs/revocation_list"
A keyword-value organization that is managed
within a single object associated with another item type. In other words, it
says that another object, configured with its own VFS directive, has an
internal structure where each line of the object represents one record. Each
record consists of a keyword, followed by a separator character, and the value
associated with the keyword. A keyword consists of a sequence of printable,
non-whitespace characters. By default, the separator character is a colon. (A
well-known example of a file having this format is /etc/password.) To specify
a different separator, the vfs_uri should include the query argument
field_sep whose value is the separator character to use. The
path component gives the name of the item_type that should be used to
manage the underlying objects.
For example, components of DACS expect the passwds item type to be
defined. Taken together, the following pair of directives specify that the
plain file /usr/local/dacs/passwd consists of keyword-value pairs:
To specify a space as the separator character instead of the colon (which is the
default), use the directives:
Because these are URIs, they must be properly encoded and the '+' character
represents a space. If the passwords are to be stored in a Berkeley DB
database, the directive would be:
dacs-kwv- subscheme
VFS "[password_file]dacs-fs:/usr/local/dacs/passwd" VFS "[passwds]dacs-kwv:password_file"
VFS "[password_file]dacs-fs:/usr/local/dacs/passwd" VFS "[passwds]dacs-kwv:password_file?field_sep=+"
VFS "[passwds]dacs-db:/usr/local/dacs/passwd.db"
A concise way of composing the dacs-kwv scheme
with underlying objects accessed using subscheme. Currently,
subscheme can be fs (for dacs-fs), http, or https. For fs, the
path component is the absolute pathname of a file, its contents having
the keyword-value organization. For http and https, the path component
is the remainder of the URL (i.e., the scheme that specifies the object is
implied), which will be retrieved using the GET method, stored and replaced
using the PUT method, deleted using the DELETE method, and tested for using
the HEAD method. Note that any options (i.e., a query string) bind to
subscheme; if options for dacs-kwv are needed, two separate URIs must
be used instead of this method.
This configuration directive is almost equivalent to the pair of directives
described in the example above:
The following configuration directive states that the password file used by
dacspasswd(1)[127] is to be accessed at the URL
https://example.com/dacs/passwds using the standard HTTP methods:
dacs-vfs
VFS "[passwds]dacs-kwv-fs:/usr/local/dacs/passwd"
VFS "[passwds]dacs-kwv-https://example.com/dacs/passwds"
The DACS CGI-based VFS service,
dacs_vfs(8)[155], which exports VFS operations on VFS objects through a
web service. An item type must be provided and must be configured at the
specified DACS jurisdiction using any of the supported store types
(which means the dacs-vfs scheme can be used to access items stored in a
remote regular file, hash-based database, and so on).
For example, this directive causes DACS to look for password entries used
by local_passwd_authenticate[156] to be accessed through the virtual
filestore at example.com:
VFS "[passwds]dacs-vfs:https://example.com/cgi-bin/dacs/dacs_vfs"
When DACS services are asked to send an
XML Schema response (i.e., they are passed the argument FORMAT=XMLSCHEMA) and
this directive is configured, services will emit xmlns:xsi and
xsi:schemaLocation attributes, the former having a compile-time value (e.g.,
http://www.w3.org/2001/XMLSchema-instance) and the latter being a pair, the
first having the same value as the value of the xmlns attribute and the second
having a value derived from the XSD_BASE_URL directive; e.g.,
If XSD_BASE_URL is not configured, only the default xmlns attribute is
emitted.
<foo xmlns="http://example.com/dacs/v1.4" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://example.com/dacs/v1.4 http://example.com/dacs/dtd-xsd/foo.xsd">
The Auth Clause¶
Each Auth clause configures an authentication module. The Auth clause and its directives are described in dacs_authenticate(8)[25]. Note that the order of these clauses is significant - they are processed in the order in which they appear in the applicable configuration section.The Roles Clause¶
Each Roles clause configures a roles module. Roles clause and its directives are described in dacs_authenticate(8)[157]. The clauses are processed in the order in which they appear. Authentication modules may return roles, to improve efficiency, but roles are usually obtained through a roles module. Roles modules are processed only if authentication is successful.The Transfer Clause¶
Each Transfer clause configures dacs_auth_transfer(8)[27] for importing from one or more federations specified within the clause. The clauses are processed in the order in which they appear. No clause should apply to more than one initial federation, although this is not enforced. Each Transfer element has an id attribute. Its value is merely a label (an alphabetic followed by zero or more alphanumerics, hyphens, and underscores) that allows the clause to be referenced; the syntax is the same as that of a groupname[74]. The attribute values must be unique (case-sensitively). Transfer clause directives are described in dacs_auth_transfer(8)[27].Advanced Techniques¶
Configuration processing is ordinarily quite straightforward, but to accommodate more complicated situations it also supports a few advanced techniques.
After configuration processing determines which directives have been overridden,
those that are in effect have their right hand sides (which are expressions)
evaluated. These expressions are usually simple strings but they can be any
DACS expression.
Tip
When configuration processing begins, variables in the DACS and
Args namespaces[13] can by referenced by configuration
directives.
Security
The ability to reference an argument during configuration processing can be
useful and powerful when used carefully but since argument values are
completely in the hands of the user constructing a request, it is a potential
security weakness, particularly in DACS deployments that are exposed to
the Internet.
For example, an argument might be missing or duplicated, accidentally have a
problematic value (such as containing non-printable or otherwise invalid
characters), or be specifically constructed in an attempt to misconfigure
DACS to thwart security. For this reason, variables in the Args
namespace should be referenced in configuration files only when specifically
indicated in the documentation, or by advanced DACS administrators in
appropriate circumstances and with caution.
As each expression is evaluated to determine the value of the directive, a
variable in the Conf namespace (see dacs.exprs(5)[13]) is
created and assigned the value, and can then be referenced in subsequent
expressions. Variables in this namespace can be referenced within access
control rules, permitting rules to be written that depend on how the
particular site, federation, and jurisdiction have been configured. In
addition, during the remainder of the configuration processing stage, the
variable's value can be modified, effectively changing the value associated
with the directive. After completion of configuration processing, the
variables in the Conf namespace become read-only. It is these variables
that are displayed by the -vars option of dacsconf(1)[1].
For example, if the directive
is in effect when directive evaluation begins, the variable
${Conf::FEDERATION_DOMAIN} will be created and assigned the value
"example.com".
Variables within the Conf namespace[13] can be created as needed
within expressions (using the EVAL directive, for example). Care should be
taken not to unintentionally modify the value of a DACS directive,
however.
A standard set of variables is always instantiated when available:
APACHE_HOME
Authentication and Roles
FEDERATION_DOMAIN "example.com"
The value of the corresponding build-time
symbol
CGI_SUFFIX
The file name extension for CGI executables,
specified at build-time
DACS_CONF
The full pathname for this jurisdiction's
dacs.conf file
DACS_CONF_SPEC
The pathname specification template used for
this jurisdiction's dacs.conf file
DACS_HOME
The value of the corresponding build-time
symbol, from the path set by the --prefix flag or defaulting to
/usr/local/dacs
Important
This directory should be writable only by an administrator.
DACS_CGIBINDIR
The value of the corresponding build-time
symbol
DACS_RELEASE
The value of the the compile-time symbol
DACS_VERSION_RELEASE
DACS_BINDIR
The location of the DACS bin
directory
DACS_SBINDIR
The location of the DACS sbin
directory
DACS_SITE_CONF
The full pathname for this jurisdiction's
site.conf file , if any
.RE DACS_SITE_CONF_SPEC
.RE DACS_SITE_CONF_SPEC
The pathname specification template used for
this jurisdiction's site.conf file, if any
DACS_VERSION
The value of the compile-time symbol
DACS_VERSION_NUMBER
DOCUMENT_ROOT
Apache's DOCUMENT_ROOT
environment variable
EXE_SUFFIX
The file name extension for non-CGI
executables
FEDERATIONS_ROOT
The value of the corresponding build-time
symbol
HTTP_HOST
Apache's HTTP_HOST environment
variable, obtained from the HTTP Host request header
JURISDICTION_URI
The initial part of the request URI, including
scheme and port number, that uniquely identifies the jurisdiction receiving
the service request (also see JURISDICTION_URI_PREFIX)
JURISDICTION_URI_PREFIX
The URI prefix that uniquely identifies the
jurisdiction receiving the service request (also see
JURISDICTION_URI)
OPENSSL_PROG
The full pathname of the openssl
command, if available
SERVER_ADDR
Apache's SERVER_ADDR environment
variable
SERVER_NAME
Apache's SERVER_NAME environment
variable
SERVER_PORT
Apache's SERVER_PORT environment
variable
URI_SCHEME
Set to https if the service request came over
SSL ( HTTPS == "on"), otherwise http
This section unfortunately left blank.
SEE ALSO¶
dacsconf(1)[1], dacs_conf(8)[2], dacs.exprs(5)[18]BUGS¶
There's no way to turn off inherited defaults in a jurisdiction section or Default section; i.e., one cannot turn off all Auth or handler directives for just one jurisdiction section.AUTHOR¶
Distributed Systems Software ( http://www.dss.ca)COPYING¶
Copyright2003-2012 Distributed Systems Software. See the LICENSE[158] file that accompanies the distribution for licensing information.NOTES¶
- 1.
- dacsconf(1)
- 2.
- dacs_conf(8)
- 3.
- http(1)
- 4.
- dacs(1)
- 5.
- dacs_acs(8)
- 6.
- mod_auth_dacs
- 7.
- mod_vhost_alias
- 8.
- LOG_FILE
- 9.
- pathname()
- 10.
- Jurisdiction section's
- 11.
- Configuration.dtd
- 12.
- Stack category
- 13.
- namespace
- 14.
- EVAL directive
- 15.
- undef()
- 16.
- ACS_ERROR_HANDLER
- 17.
- effective jurisdictional URIs
- 18.
- expression
- 19.
- configuration variables
- 20.
- example configuration
- 21.
- Jurisdiction Selection by URI
- 22.
- string interpolation
- 23.
- access control rules
- 24.
- INIT*
- 25.
- Auth clause
- 26.
- section merging
- 28.
- Authorization Caching
- 29.
- dacscookie(1)
- 30.
- dacsauth(1)
- 31.
- dacs_signout(8)
- 32.
- The DACS_APPROVAL environment variable
- 33.
- description of the ErrorDocument directive
- 34.
- redirect()
- 35.
- access control rules
- 36.
- Bug 3641
- 37.
- Bug 42430
- 39.
- ACS_TRACK_ACTIVITY
- 40.
- SetDACSAuthPostBuffer
- 41.
- SERVICE_ARGS_TRUNCATED
- 42.
- HTTP_AUTH
- 43.
- syntactically valid username
- 44.
- current jurisdiction
- 45.
- ACS_AUTHENTICATED_ONLY
- 47.
- DACS_ACS
- 49.
- on_success()
- 50.
- counter
- 51.
- current federation
- 52.
- ACS_INACTIVITY_LIMIT_SECS
- 53.
- FEDERATION_NAME
- 54.
- dacs_admin()
- 55.
- NAME_COMPARE
- 56.
- auth_reply.dtd
- 57.
- dacs_auth_reply.dtd
- 58.
- AUTH_ERROR_HANDLER
- 59.
- cookie name
- 61.
- ACS_CREDENTIALS_LIMIT
- 62.
- AUTH_SUCCESS_HANDLER
- 63.
- mitigate the risk of information disclosure with a cross-site scripting (XSS) attack
- 64.
- are known
- 65.
- Netscape HTTP Cookies Specification
- 66.
- RFC 2965
- 67.
- dacs.install(7)
- 68.
- FORMAT web service argument
- 69.
- Advanced Techniques
- 70.
- RFC 1035
- 71.
- dacs.groups(5)
- 72.
- dacs.conf(5)
- 73.
- JURISDICTION_NAME
- 74.
- dacs(1)
- 75.
- RFC 2617
- 76.
- HTTP Authentication
- 77.
- HTTP_AUTH_ENABLE
- 78.
- ACS_PRE_AUTH
- 79.
- see below
- 80.
- authentication styles
- 81.
- chmod(2)
- 82.
- dacs_prenv(8)
- 83.
- dacsexpr(1)
- 84.
- encode()
- 85.
- LDAP authentication
- 87.
- regex(3)
- 88.
- dacs_sts(8)
- 90.
- XML Schema Part 2: Datatypes Second Edition
- 91.
- INFOCARD_CARD_LIFETIME_SECS
- 92.
- VFS URI
- 93.
- CARD_IMAGE_URL
- 94.
- INFOCARD_CARD_DATETIME_EXPIRES
- 95.
- INFOCARD_CARDID_BASE_URL
- 96.
- INFOCARD_CARD_OUTPUTDIR
- 97.
- INFOCARD_CARDID_SUFFIX
- 98.
- RFC 2396
- 99.
- dacs_infocard(8)
- 00.
- PASSWORD_DIGEST
- 01.
- INFOCARD_IP_PRIVACY_URL
- 02.
- dacs_mex(8)
- 03.
- INFOCARD_STS_PASSWORD_METHOD
- 04.
- INFOCARD_STS_CERTFILE
- 05.
- dacsinfocard(1)
- 06.
- local_infocard_authenticate
- 07.
- INFOCARD_STS_KEYFILE_PASSWORD
- 08.
- INFOCARD_STS_KEYFILE
- 09.
- INFOCARD_REQUIRE_APPLIES_TO
- 10.
- INFOCARD_AUDIENCE
- 11.
- wildcard certificate
- 12.
- syslog(3)
- 13.
- LOG_LEVEL
- 14.
- regex(3)
- 15.
- print()
- 16.
- printf()
- 17.
- LOG_SENSITIVE
- 18.
- dacs(1)
- 19.
- LOG_FILTER
- 20.
- debug_dacs
- 21.
- mod_log_config
- 22.
- dacs_notices(8)
- 23.
- Secure Mode
- 24.
- local_pam_authenticate
- 25.
- pamd(8)
- 26.
- dacs_passwd(8)
- 27.
- dacspasswd(1)
- 28.
- dacstoken(1)
- 29.
- PASSWORD_AUDIT
- 30.
- ispunct(3)
- 31.
- dacs_admin(8)
- 32.
- crypt(3)
- 33.
- MD5 function
- 34.
- FIPS 180-3
- 35.
- ADMIN_IDENTITY
- 36.
- Rlink
- 37.
- VFS specification
- 38.
- sslclient(1)
- 39.
- DACS-Status-Line
- 40.
- DACS_HOME
- 41.
- role descriptor string
- 42.
- user()
- 43.
- dacs_uproxy(8)
- 44.
- from()
- 45.
- dacs.vfs(5)
- 46.
- dacsvfs(1)
- 47.
- RFC 3986
- 48.
- dacs(1)
- 49.
- dacskey(1)
- 50.
- get()
- 51.
- Berkeley DB
- 52.
- dbm(3)
- 53.
- GNU gdbm
- 54.
- SQLite
- 55.
- dacs_vfs(8)
- 56.
- local_passwd_authenticate
- 58.
- LICENSE
| 10/22/2012 | DACS 1.4.27b |