Ubuntu Manpage: dacs_authenticate - DACS authentication service

NAME

       dacs_authenticate - DACS authentication service

SYNOPSIS

       dacs_authenticate [dacsoptions[1]]

DESCRIPTION

This web service is part of the DACS suite.

The dacs_authenticate web service is an authentication "driver" for DACS. When it receives
a request to authenticate a user, it usually invokes one or more authentication modules,
depending on its configuration. Successful authentication assigns a DACS user identity to
the user and roles modules may be invoked to determine the roles with which the identity
is associated; DACS credentials are generated and returned to the user. The caller of
dacs_authenticate can be redirected to a configured URL, called the post-authentication
handler (or just the handler), depending on whether authentication fails or succeeds.

General DACS configuration directives are discussed in dacs.conf(5)[2]. Configuration
directives specific to authentication are described here.

DACS expressions are described in dacs.exprs(5)[3].

dacs_authenticate might be called from an HTML form (see the distribution's
html/examples[4] directory for examples of simple login pages), directly through a link on
a web page, indirectly by DACS HTTP Authentication[5], or from middleware.

Command line authentication functionality is provided by dacsauth(1)[6]. Other
authentication mechanisms are provided by dacs_auth_agent(8)[7], dacs_auth_transfer(8)[8],
and dacscookie(1)[9].

Authentication
Authentication is the procedure by which a claimed identity is confirmed. Following
successful authentication, DACS credentials may be created that represent the identity.
For maximum convenience and interoperability in a web environment, DACS credentials are
usually encapsulated within an HTTP cookie and transmitted over a TCP/IP connection
secured by SSL/TLS. Any secure method of transporting credentials can be used instead,
however, such as the value of an HTTP extension-header entity-header field in a request
message sent over a VPN.

While dacs_authenticate provides powerful and flexible ways to combine and compose a
variety of authentication methods, most DACS jurisdictions will configure only one method,
or perhaps just a few methods, in simple ways.

To help integrate DACS seamlessly within a web site, dacs_authenticate allows handlers to
be configured. Handlers allow various exceptions to be caught and processed so that an
appropriate flow of control can occur. For example, if authentication succeeds the user
can be redirected to a specific page, including the one originally requested before the
exception occurred.

Authentication succeeds (and the user is authenticated) if and only if:

• at least one Auth clause[10] has been configured,

• the semantics of all CONTROL[11] directives satisfy the requirements for success,

• the DACS username[12] arrived at is syntactically valid, and

• the identity's access has not been revoked or denied (see dacs.acls(5)[13]).

An incorrect password, for instance, is not considered to be an error; it will cause its
Auth clause to fail but depending on the control directives that have been configured, the
user may still be successfully authenticated by some other Auth clause. True errors are
fatal and cause dacs_authenticate to terminate without issuing credentials and possibly
without invoking a handler.

If a DACS identity reauthenticates, the user agent is expected to replace the old
credentials with new ones; if re-authentication fails (e.g., the password is incorrect),
the old credentials should continue to exist. If a user establishes multiple concurrent
identities, the user agent is expected to send all credentials with each service request
in accordance with the relevant standards. This is standard behaviour for most common web
browsers.

As an efficiency measure, the authentication architecture allows an authentication module
to return roles.

Names
Please refer to dacs(1)[14] for details about naming.

Credentials and Cookies
DACS credentials are cryptographically protected XML documents (credentials.dtd[15]).
They have been carefully designed to make it extremely difficult for an attacker to
generate valid credentials, modify captured credentials to impersonate another user,
or obtain greater access rights without being detected. DACS is careful to not
produce log information or error messages that might benefit an attacker.

User agents and other software outside of DACS do not need to decrypt the credentials
and do not possess the required encryption key.

New credentials are created and returned to the user after successful authentication.
The lifetime of each set of credentials is independently configurable, but they are
intended to be fairly transitory. If a user reauthenticates, new credentials different
than previous credentials might well be returned (e.g., with different roles).

DACS does not verify that a user's browser is configured to accept cookies - this is
the responsibility of the DACS administrator (by supplying client-side code to test
that cookies have been enabled, for instance). Failure to accept cookies may cause
some features to be unavailable or work incorrectly. Also note that despite what DACS
(or any other program) tells a browser about the lifetime of an HTTP cookie, browsers
may be configured to impose a shorter lifetime and can delete a cookie at any time.
(Aside: Firefox 2.0.0.3 appears to show cookies that have been deleted.)

Security
• For DACS to operate securely, communication between a user (or middleware) and
dacs_authenticate, which may include information such as passwords, must only
be transmitted over a secure connection (SSL/TLS).

• Communication between dacs_authenticate (and dacsauth) and an external (not
built-in) authentication module may include information such as passwords and
therefore should only be transmitted over a secure connection (SSL/TLS) or in
a way that is not subject to eavesdropping or attack.

• For DACS to operate securely, regardless of how they are obtained, DACS
credentials must only be transmitted over a secure connection (SSL/TLS) so
that they cannot easily be captured and reused by an attacker.

• It is unwise to configure both SSL/TLS and non-SSL/TLS communication. Besides
providing an avenue for attack, it may cause DACS to behave strangely (e.g.,
infinite loops may occur because cookies obtained over an SSL/TLS connection
are not subsequently forwarded over a non-SSL/TLS connection).

• The apparent IP address of an authenticated user, as provided by the web
server, is stored in credentials. DACS can be configured to consider
credentials to be valid only for requests that come from that address (refer
to the VERIFY_IP[16] configuration directive), making it more difficult for an
attacker to replay captured credentials.

In some environments this constraint is a good idea, but in general it is of
dubious value so enable it with care. Where a user is behind a firewall or
router that has multiple IP addresses, successive service requests might
legitimately not appear to be coming from the same address and some requests
would be denied if this constraint were enabled. In situations where
credentials are being forwarded between web services they might be rejected.
In the case of dial-up Internet access, a user might be issued credentials,
lose the connection, and be assigned a different IP address upon reconnecting;
the user would be forced to reauthenticate. Also, more than one user may be
associated with a particular IP address, as when a Network Address Translation
(NAT) facility such as natd(8)[17] is used, so the check does not guarantee
uniqueness.

• Information associated with a user's browser can be included in credentials
created for that user to make it difficult to reuse captured credentials with
a different browser. Please refer to VERIFY_UA[18] for details.

• Credentials have a limit on their lifetime that is independent of the lifetime
of the HTTP cookie that contains them; that is, credentials can expire without
their cookie having expired, and vice versa. Expired credentials are
recognized and will not be used by DACS. Refer to the
AUTH_CREDENTIALS_DEFAULT_LIFETIME_SECS[19] configuration directive for
details.

• Passwords do not appear in any credentials and are not stored once the user
has been authenticated.

• It is forbidden to submit multiple credentials for the same identity to DACS
and such a request will trigger an error.

All DACS jurisdictions within the same federation share an algorithm and key to
encrypt and decrypt credentials. A cryptographically secure, symmetric encryption
function, Rijndael (the Advanced Encryption Standard[20] (AES) algorithm and Federal
Information Processing Standard[21]), is used. The same 128 bit key is used by all
DACS jurisdictions. AES also supports 192 and 256 bit key lengths and either can be
configured at build-time.

A cryptographically secure message authentication code (MAC) is used to detect
modification of credentials. A key different from the encryption key is used. The
Keyed-Hash Message Authentication Code (HMAC, FIPS 198[22], RFC 2104[23], RFC
4635[24], RFC 4868[25]), is employed using the 160-bit NIST[26] secure hash standard,
SHA-1 (FIPS 180-1[27], RFC 4634[28], RFC 6234[29]). In addition to SHA-1, SHA-224,
SHA-256, SHA-384, and SHA-512 (FIPS 180-4[30]) can be used, although they must be
configured at build-time.

The AES key length and HMAC digest algorithm used by a federation can be changed at
any time, perhaps forcing some users to reauthenticate, but the same key length and
digest algorithm must be used throughout a federation.

Security
DACS can be configured to use the less secure but widely-used and somewhat more
efficient MD5 algorithm[31] instead, although it is deprecated and it will
eventually be removed.

The Netscape HTTP Cookies Specification[32] defines the syntax and semantics of the
HTTP response header that a web server sends to a client; this syntax is used by
default, but the COOKIE_SYNTAX[33] argument can be used to request a different syntax.
The Netscape format is as follows:

Set-Cookie: NAME=VALUE; expires=DATE; path=PATH; domain=DOMAIN_NAME; secure

DACS formulates these response headers as follows.

The NAME attribute of an authentication cookie returned to the user (e.g., by
dacs_authenticate) has the following default format:

DACS:federation-name::[jurisdiction-name]:[username]

where federation-name is the official name assigned to the federation for which the
cookie is valid, jurisdiction-name is the name of the authenticating jurisdiction, and
username is the authenticated name of the user. If the jurisdiction-name is omitted,
the username must also be omitted. Semicolons, commas, and whitespace within the name
must be URL-style encoded. Colons are not allowed in any of the name components. Here
is an example of a cookie name:

DACS:EXAMPLE::METALOGIC:rick@example.com

DACS can also return HTTP cookies for other purposes. The NAME attribute of these
cookies has the same format as an authentication cookie but is followed by a colon and
a keyword; e.g., DACS:EXAMPLE:::SELECTED.

The default format of the NAME attribute can be overridden through the
COOKIE_NAME_TERMINATORS[34] directive.

The VALUE attribute of a cookie is a printable text encoding of credentials.

Security
• Although DACS performs validity tests on cookie names, middleware should not
rely on cookie names for any purpose. An apparently valid DACS cookie can
easily be crafted with any value. Also, an apparently legitimate cookie might
convey expired or otherwise invalid credentials. Middleware should use
dacs_current_credentials(8)[35] to validate an authentication cookie and not
trust cookie names.

• No expires attribute is set; this will cause the cookie to be automatically
deleted by a conforming browser when the user's browser session ends and not
made persistent (i.e., not stored on disk for use in a subsequent browser
session), closing a potential security hole.

• By default, the value of the path attribute is "/", meaning the cookie will be
sent with every request to the domain that created the cookie, whether it is
for a DACS-wrapped service request or not. The COOKIE_PATH[36] configuration
directive can specify an alternative value. Using a more restricted path can
potentially improve security. All of the jurisdiction's DACS-wrapped services
must appear under that path, of course, or the cookie will not be sent;
ideally, no non-DACS wrapped service would appear under that path.

The value of the domain attribute associated with the cookie is dependent on the
uniform domain name scheme chosen for the jurisdictions. The value will be configured
to be the most specific tail string that tail matches all participating domain names.
For example, if the uniform domain name scheme has hostnames of the form
xxx.example.com, yyy.example.com, and zzz.example.com, then the value of the attribute
will be example.com. This will ensure that the user agent sends the cookie with any
service request directed to a hostname ending in example.com.

Tip
The HTTP cookie specifications appear to say that a cookie having a domain
attribute of example.com should not be sent to a host of the same name, yet both
Mozilla and IE (and perhaps other browsers) do just that. Without this behaviour,
it would not be possible to use a single domain name with multiple DACS
jurisdictions below it; that is, given domain=example.com, it is expected that
jurisdictions can be identified by URI path prefixes such as
example.com/metalogic, example.com/test, and so on.

When operating securely (see the SECURE_MODE[37] directive in dacs.conf(5)[2]) or when
an authentication request is sent over SSL/TLS, the secure attribute will be present
so that the cookie will only be transmitted if the communications channel with the
host is a secure one. At present, browsers define this to mean that secure cookies
will only be sent to HTTPS (HTTP over SSL/TLS) servers.

Web Service Arguments
In addition to the standard CGI arguments[38], dacs_authenticate understands the following
CGI arguments. Some arguments are optional, while others are required depending on the
authentication configuration. An invalid argument value will usually cause authentication
to fail immediately. Unrecognized arguments are ignored.

AUTH_ID
This optional argument is used with the user_sufficient keyword (refer to the
CONTROL[11] directive).

AUTH_PROMPT_VAR_PREFIX
Reserved for use by local_pam_authenticate[39].

AUTH_TRANSID
Reserved for use by local_pam_authenticate[39].

AUTHORIZATION
Used internally with HTTP Authentication[5].

AUXILIARY
This argument can be used to pass additional authentication material to authentication
modules. A compile-time maximum length of 128 characters is imposed.

COOKIE_SYNTAX
By default, the de facto standard Netscape HTTP Cookies Specification[32] syntax is
followed when cookies are created (COOKIE_SYNTAX=COOKIE_NETSCAPE). The value
COOKIE_EXT_NETSCAPE selects an "extended" Netscape spec syntax (it is not the Netscape
syntax but it is not fully RFC 2109 compliant either); instead of using the expires
attribute it will use the Max-Age attribute as defined in RFC 2109[40], RFC 2965[41],
and RFC 6265[42]. Attribute values are not quoted and there is no support for the
Comment field. Parameter values COOKIE_RFC2109, COOKIE_RFC2965, and COOKIE_RFC6265 are
recognized but not implemented.

Note
RFC 2109[40], RFC 2965[41], and RFC 6265[42] forbid the following characters from
appearing within an HTTP cookie's NAME attribute:

( ) < > @ , ; : \ " / [ ] ? = { }

Additionally, the space, tab, and all US-ASCII control characters (octets 0 - 31)
and DEL (127) are disallowed (refer to the definition of a token in RFC 2616[43],
S2.2). By default, DACS currently follows the original Netscape spec syntax in
this respect and produces cookies that are invalid according to RFC 2109, RFC
2965, and RFC 6265 because colons are used within cookie names[44]. While this
limitation does not appear to cause problems for web browsers in practice, it may
be noteworthy for users of some cookie handling APIs. When necessary, the cookie
name format can be customized using the COOKIE_NAME_TERMINATORS[34] directive.

DACS_AUTH_SUCCESS_HANDLER
This argument provides a way for the caller to specify where the user agent should be
redirected after successful authentication, regardless of whether authentication
handlers are configured or enabled. If its value is DACS_ERROR_URL and an argument by
that name is present, the user agent will be redirected to the value of that argument;
otherwise, the user agent will be redirected to the value of
DACS_AUTH_SUCCESS_HANDLER. The DACS_ERROR_URL is passed to this web service by
dacs_acs(8)[45] as part of an authentication workflow initiated by a request that is
denied because no credentials were supplied; DACS_ERROR_URL should not be generated by
any non-DACS software.

DACS_BROWSER
If an argument named DACS_BROWSER is present and has the value 1, it signifies that
the request is coming from a browser rather than middleware. If the request comes from
a browser, DACS will return a cookie using the Set-Cookie HTTP response header,
otherwise it will not.

DACS_DEBUG
If this argument is present, the web service will produce more detailed log
information.

ENABLE_AUTH_HANDLERS
The jurisdiction's authentication handler directives are honoured if and only if this
argument is present and has the value 1.

OPERATION
This is used with the identity selection mechanism described by
dacs_select_credentials(8)[46]. If the value of this parameter is SELECT and
authentication is successful, any currently selected credentials are deselected and
the new credentials are selected.

PASSWORD
This argument is the password that corresponds to USERNAME. A compile-time maximum
length of 128 characters is imposed.

USERNAME
This argument, which is almost always required, is the name provided by the user and
is usually the name being authenticated. It will not necessarily be the same as the
final DACS username. For example, if the value of USERNAME is not a syntactically
valid DACS username (see dacs(1)[12]), the authentication procedure must transform it
into something acceptable (using the strtr()[47] function, for instance; see
dacs.exprs(5)[3]). A compile-time maximum length of 64 characters is imposed.

WWW_AUTHENTICATE
Reserved for internal use by HTTP Authentication[5].

Auth Clause Directives
Each Auth clause in a DACS configuration file contains directives that describe a
procedure for authenticating users. Some of these directives are common to all
authentication modules, while others are understood only by a certain module; for example,
LDAP_USERNAME_URL[48] is only meaningful to the local_ldap_authenticate[49] module. The
general-purpose OPTION[50] directive may sometimes be used to specify an argument to an
authentication module.

Important
The order in which the Auth clauses appear is significant. See the CONTROL[11]
directive.

Every Auth element must have 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. Each id attribute value must be unique (case-sensitively) within the
Jurisdiction section that contains it.

The following configuration directives are recognized by dacs_authenticate within any Auth
clause (see dacs.conf(5)[51] for general information about directives).

Auth Clause Common Directives Index:

1. CONTROL (Required1)

2. CREDENTIALS_LIFETIME_SECS (Optional1)

3. EXIT* (Optional1)

4. EXPR (Optional1)

5. FLAGS (Optional1)

6. INIT* (Optional1)

7. OPTION (Optional)

8. OPTION* (Optional)

9. PASSWORD_AUDIT (Optional)

10. PREDICATE (Optional1)

11. STYLE (Required1)

12. URL (Optional1)

13. URL* (Optional1)

CONTROL (Required1)
This directive specifies a PAM-like control keyword that determines what will happen
if the authentication module succeeds or fails; see pam(3)[52] and the X/Open Single
Sign-On Service (XSSO) preliminary specification[53] (page 30), from which the
description of these directives was adapted. Although this control mechanism allows
for rather complicated authentication sequences to be described, in practice
jurisdictions tend to construct fairly simple configurations. Most processing errors
(other than errors encountered by a module) are considered fatal.

The first Auth clause that appears after configuration merging (see dacs.conf(5)[54])
is the "top" or first module in the stack, the next one is the second module in the
stack, and so on.

The value of this directive is a case-insensitive keyword that can be abbreviated up
to the indicated minimum:

• require[d]

• requisite

• opt[ional]

• suff[icient]

• user_suff[icient]

For example, the keywords require and required are equivalent.

The control flow of authentication module processing is as follows:

1. If a requisite module fails, authentication fails and dacs_authenticate stops
processing the module stack, returning the error reported by the requisite module;

2. If all requisite and required modules in the stack succeed, then authentication
succeeds (any errors reported by optional, sufficient, and user_sufficient modules
are ignored);

3. If one or more required modules fail, then the error value from the first required
module that failed is returned; unlike failure of a requisite module, processing
continues;

4. If none of the modules in the stack are designated as required or requisite, then
dacs_authenticate requires that at least one optional, sufficient, or
user_sufficient module succeed. If all fail, then the error value from the first
module in the stack is returned;

5. The first exception to the above is caused by the sufficient keyword. If a module
that is designated as sufficient succeeds, then dacs_authenticate immediately
returns success (all subsequent modules are ignored, even required and requisite
ones), given that all prior required and requisite modules have also succeeded. If
a prior required module failed, then the error value from that module is returned;

6. The second exception to the above involves the user_sufficient keyword, which
enables at most one user_sufficient Auth clause and disables all other
user_sufficient and sufficient Auth clauses. This control simplifies configuring
user-selectable authentication methods. Note that this mechanism will necessarily
reveal additional information about a jurisdiction's authentication configuration.

If the AUTH_ID argument is not given, then all Auth clauses with the
user_sufficient control are disabled - none of their directives are evaluated -
and any sufficient controlled clauses are processed normally. If the AUTH_ID is
present, then only an Auth clause with a user_sufficient control and an exactly
matching id attribute is used. There can be at most one such Auth clause; all
other Auth clauses having a user_sufficient or sufficient control is disabled. In
all other respects, an enabled user_sufficient Auth clause is processed as for the
sufficient control;

7. If an error occurs while processing a directive, then dacs_authenticate fails
immediately.

CREDENTIALS_LIFETIME_SECS (Optional1)
The lifetime, in seconds, of credentials returned after successful authentication.
This overrides the general directive of the same name, and may in turn be overridden
by setting the variable ${Auth::CREDENTIALS_LIFETIME_SECS}. Authentication will fail
if this value is invalid.

EXIT* (Optional1)
If authentication is successful, this expression is evaluated immediately after the
module's authentication processing is executed (but refer to the FLAGS directive).

EXPR (Optional1)
This directive, which is required when STYLE is expr, gives an expression that is
evaluated to decide whether to grant credentials and the DACS identity to use. See
Authenticating Using an Expression[55].

FLAGS (Optional1)
This directive gives control flags that are interpreted by dacs_authenticate. Each
directive consists of a whitespace-separated list of values.

The only value currently recognized is the keyword ident.

Important
If there is more than one Auth clause, the ident flag should ordinarily be
specified in at least one of them to indicate that the username returned by the
module, if authentication is successful, is to become the "current" username.
Those Auth clauses without the ident flag will not change the current username.
After the last Auth clause is processed, the current username is used in the
resulting credentials.

The ${Auth::CURRENT_USERNAME} variable (see below) is updated only if there is
exactly one Auth clause or if the ident flag is given. This update occurs
immediately prior to execution of any EXIT* directive.

If ident is not specified in any successfully processed Auth clause (i.e., one
where authentication succeeds), the username returned by the last successfully
processed clause is used. If the ident flag is specified in one or more
successfully processed clauses, the username returned by the last such module will
be used.

INIT* (Optional1)
The given expression is evaluated immediately prior to the URL* and EXPR expressions,
all of which are evaluated before a module's authentication processing is invoked.

OPTION (Optional)
The directive value is a name=value pair that may be interpreted by dacs_authenticate
or the authentication module specified by the Auth clause. It causes a variable called
name to be put into the Options namespace, which only exists within the context of the
Auth clause containing this OPTION. The variables in this namespace are passed as
arguments to the authentication module. Whitespace may not precede or follow the '='
and any quotes around the value are considered to be part of the value. A given name
may not be specified more than once within a particular Auth clause. The Options
namespace is initialized with USERNAME, PASSWORD, AUXILIARY, DACS_JURISDICTION, and
DACS_VERSION variables. If these variables are specified by an OPTION, the argument
ordinarily used will be overridden.

For example, this directive causes SAMBA_PORT=139 to be passed as a POST method
parameter:

OPTION "SAMBA_PORT=139"

OPTION* (Optional)
The given expression is evaluated before the module is called, and after all OPTION
directives and all OPTION* directives that appear earlier. The value of the expression
must be a name=value pair, as with the OPTION directive, and overrides any name in the
Options namespace.

PASSWORD_AUDIT (Optional)
This directive is used to audit password-type arguments passed to authentication
modules by dacs_authenticate, regardless of the authentication method, against the
criteria selected by the specified constraint string, which is in the format used by
PASSWORD_CONSTRAINTS[56]. If any password does not meet the requirements, a log
message will be emitted (which does not include the password itself). The message will
be tagged as audit and sensitive; please refer to the LOG_FILTER[57] directive. This
feature can be used to notify the administrator about weak passwords.

The directive value can be a variable name, which is matched exactly against the
PASSWORD or AUXILIARY arguments, or a keyword in one of the OPTION directives within
the same clause. In this form, the PASSWORD_CONSTRAINTS directive must be configured
and its value is used as the constraint. In the second form, the directive value is a
variable name as in the first form, followed by spaces or tabs, followed by the
constraint string to use in the syntax of PASSWORD_CONSTRAINTS. Consider the following
directives:

PASSWORD_CONSTRAINTS "8L,1C,1P"

<Auth id="auth1">
URL "https://foo.example.com/cgi-bin/dacs/local_woof_authenticate"
STYLE "pass"
CONTROL "sufficient"
PASSWORD_AUDIT "PASSWORD 10L"
PASSWORD_AUDIT "AUXILIARY"
</Auth>

Here, the PASSWORD argument must be at least ten characters long but AUXILIARY must
only be eight characters long and include an upper case character and punctuation.

Note
Not all authentication modules require a PASSWORD argument, such as
local_cas_authenticate[58] in its interactive mode. This directive is ignored if
the argument is not passed to the module.

PREDICATE (Optional1)
If provided, this expression is evaluated before any other authentication module
processing is done. If there is an evaluation error or it returns False (zero or the
empty string), processing continues just as if the module were run and indicated that
authentication failed. Otherwise, processing of the clause continues normally.

This directive provides a way to effectively enable or disable a module based on run
time context. This can be used to configure layered authentication or risk-based
authentication because a predicate can examine various aspects of an authentication
request, such as the USERNAME, current date and time, IP address from where the
request originates, and so on.

STYLE (Required1)
Each authentication module implements one or more authentication styles. The value of
the STYLE directive is a comma-separated list of case-insensitive style names and
style options; the order is insignificant. No whitespace is allowed. Keywords can be
abbreviated up to the indicated minimum.

cas
This style selects username/password authentication using the Central
Authentication Service (CAS)[59] protocol through the local_cas_authenticate[58]
authentication module.

cert[ificate]
An X.509 client certificate, obtained from the SSL/TLS layer, will be provided for
authentication. The request must be sent using SSL/TLS and the client certificate
must be provided by Apache through the SSL_CLIENT_CERT environment variable.

digest
This selects the RFC 2617[60] Digest Access Authentication scheme as implemented
by DACS in conjunction with the local_apache_authenticate[61] authentication
module. See HTTP Authentication[5].

expr
No authentication module will be used; expression evaluation[55] will be used
instead.

infocard
A self-issued or managed Information Card[62] (InfoCard) must be provided for
authentication. To be recognized, the InfoCard must have been previously
registered at this jurisdiction using dacsinfocard(1)[63], dacs_infocard(8)[64],
or dacs_managed_infocard(8)[65]. This style is implemented by the
local_infocard_authenticate[66] authentication module.

managed_infocard
A managed Information Card[62] (InfoCard) must be provided for authentication. To
be recognized, the InfoCard must have been previously registered at this
jurisdiction using dacs_managed_infocard(8)[65]. This style is implemented by the
local_infocard_authenticate[66] authentication module.

nat[ive]
The user is expected to have already authenticated through the web server's native
authentication mechanism (e.g., HTTP Basic or Digest authentication, RFC
2617[60]); DACS will import this identity without any additional requirements. The
AUTH_TYPE environment variable but be available and have the value Basic or Digest
(case insensitive), and the REMOTE_USER environment variable must be set.

pass[word]
passwd
The username must be provided through a USERNAME argument and the password must
accompany the authentication request through a PASSWORD argument.

prompt[ed]
A dialog-based interaction will be conducted, such as one based on Pluggable
Authentication Modules (PAM). See local_pam_authenticate[39].

selfissued_infocard
A self-issued Information Card[62] (InfoCard) must be provided for authentication.
To be recognized, the InfoCard must have been previously registered at this
jurisdiction using dacsinfocard(1)[63] or dacs_infocard(8)[64]. This style is
implemented by the local_infocard_authenticate[66] authentication module.

simple
This style of authentication merely requires a recognized username, provided
through a USERNAME argument and therefore offers little security. Still, it can be
used in appropriate situations to authenticate a user that can provide a valid
account name, which might be a membership number or randomly generated (and
perhaps hard to guess) username. If a PASSWORD argument is provided, it is logged
as sensitive data, much as an anonymous FTP password might be logged. This style
is implemented by the local_simple_authenticate[67] authentication module.

tgma
Experimental. This interactive style of authentication requires only USERNAME and
JURISDICTION arguments to be selected by the user. Refer to the TGMA
authentication module for details.

This style is implemented by the local_tgma_authenticate[68] authentication
module.

set_roles
If the authentication module returns roles, this style modifier says that they
should override any other roles currently in effect and no roles module should be
executed. This option may appear at most once among all Auth clauses and only if
add_roles[69] is not used.

add_roles
If the authentication module returns roles, this style modifier says that they
should be appended to any other roles currently in effect. Any configured roles
modules will still be executed. This option may be repeated in other Auth clauses
but may not appear if the set_roles[70] option also appears.

URL (Optional1)
URL* (Optional1)
Exactly one of these two directives must be specified, except when STYLE is expr,
where neither directive is used. These directives specify the URL to be used to invoke
the authentication module. Use of an absolute URL is recommended.

The difference between the two directives is that the value of URL* is an expression
that is evaluated immediately before the module is invoked to determine the URL to be
used.

In the current implementation, the standard set of modules must run within the context
of a DACS jurisdiction. This is not an architectural limitation, however.

Tip
Some authentication modules are available as built-in components of
dacs_authenticate and dacsauth. These modules are identified by specific relative
URLs. A module's description will provide its built-in name when this capability
is available. The built-in capability will automatically be provided if the module
has been enabled at build-time.

Although it will be more efficient (and possibly more secure) to use a built-in
module, they are executed on the same host as dacs_authenticate thereby giving up
some flexibility because access control rules are not applied to them (other than
the one for dacs_authenticate), and dacs_authenticate may need to be executed
setuid root or setgid www so that it can access password files. When an external
module is used, it is subject to normal DACS access control rules. In contrast to
a built-in module, the additional level of indirection makes it simple to
substitute a custom version of an external module. The same comments apply to
dacsauth.

Here is an example of a configuration that will authenticate using Unix user names and
passwords:

<Auth id="passwd">
URL "https://foo.example.com:8443/cgi-bin/dacs/local_unix_authenticate"
STYLE "pass"
CONTROL "sufficient"
</Auth>

In the following example, dacs_authenticate will first try to authenticate using a Unix
login name and password; if that fails, it will then try a DACS account name and password.

<Auth id="passwd">
URL "https://foo.example.com:8443/cgi-bin/dacs/local_unix_authenticate"
STYLE "pass"
CONTROL "sufficient"
</Auth>

<Auth id="passwd2">
URL "https://foo2.example.com/cgi-bin/dacs/local_passwd_authenticate"
STYLE "pass"
CONTROL "sufficient"
</Auth>

The preceding example can be changed to try authenticating using a DACS account name and
password if and only if the AUXILIARY argument has the value "guest" (which might have
been provided when the user selected a button on a login form):

<Auth id="passwd">
URL "https://foo.example.com:8443/cgi-bin/dacs/local_unix_authenticate"
STYLE "pass"
CONTROL "sufficient"
PREDICATE '${Args::AUXILIARY} ne "guest"'
</Auth>

<Auth id="passwd2">
URL "https://foo2.example.com/cgi-bin/dacs/local_passwd_authenticate"
STYLE "pass"
CONTROL "sufficient"
PREDICATE '${Args::AUXILIARY} eq "guest"'
</Auth>

In this example, a jurisdiction offers users a choice from among three authentication
methods: a Googleaccount, a Windows NTLM account, or a DACS password-based account. The
jurisdiction's login form would be written to provide the appropriate AUTH_ID argument for
the corresponding method;

# For AUTH_ID=google
<Auth id="google">
URL "local_http_authenticate"
STYLE "password"
CONTROL "user_sufficient"
OPTION 'AUTH_URL="https://www.google.com/accounts/ClientLogin"'
OPTION 'AUTH_METHOD=POST'
OPTION 'USERNAME_PARAMETER="Email"'
OPTION 'PASSWORD_PARAMETER="Passwd"'
OPTION 'service=xapi'
OPTION "source=DSS-DACS-1.4"
</Auth>

# For AUTH_ID=ntlm
<Auth id="ntlm">
URL "local__ntlm_authenticate"
STYLE "password"
CONTROL "user_sufficient"
OPTION 'SAMBA_SERVER="samba.example.com"'
OPTION 'SAMBA_PORT="139"'
EXIT* '${Auth::CURRENT_USERNAME}=strtr(${Auth::CURRENT_USERNAME}, "a-z", "A-Z")'
</Auth>

# For AUTH_ID=passwd
<Auth id="passwd">
URL "local_passwd_authenticate"
STYLE "password"
CONTROL "user_sufficient"
</Auth>

Initialization and the Auth Namespace
dacs_authenticate uses a variable namespace called Auth to make authentication-related
context available to its configuration directives (see dacs.exprs(5)[71]). Aspects of
dacs_authenticate's behaviour can be controlled by modifying these variables. This
namespace disappears when dacs_authenticate terminates. The next section describes how
these variables are used.

Additionally, all environment variables are accessible through the Env namespace (e.g.,
${Env::REMOTE_ADDR}) during authentication processing.

Authentication Clause Control Flow
Auth clauses are processed in the order in which they appear in the configuration file,
subject to the semantics of the CONTROL directives.

dacs_authenticate is typically configured so that the last thing it does is to redirect
its caller to an appropriate web page. If authentication is successful, any
AUTH_SUCCESS[72] expression is evaluated and the AUTH_SUCCESS_HANDLER[73] directive is
consulted; if authentication fails, the AUTH_ERROR_HANDLER[74] and
AUTH_FAIL_DELAY_SECS[75] directives are used. This behaviour is partially under the
control of the caller through the DACS_AUTH_SUCCESS_HANDLER[76] and
ENABLE_AUTH_HANDLERS[77] arguments, however.

Tip
To redirect the newly authenticated user to a web page based on the user's identity,
jurisdiction, roles, or other contextual state, configure AUTH_SUCCESS_HANDLER to
specify the URL of a DACS-wrapped CGI program. After examining environment variables
automatically passed to it by DACS or its query arguments, this program can emit an
appropriate redirect. To test this, configure:

AUTH_SUCCESS_HANDLER "url /cgi-bin/dacs/dacs_prenv"

(making sure that dacs_prenv(8)[78] has been installed) and examine the information
that is available.

An Auth clause is processed in a sequence of steps, and with various hooks to provide
fine-grained control. Only advanced DACS administrators usually need to be concerned with
this level of detail.

Before the first clause is examined, the variable ${Auth::CURRENT_USERNAME} is set to the
empty string; this variable is automatically updated by dacs_authenticate. The contents of
the Args, DACS, Conf, and Env namespaces[71] are made available to all expressions
evaluated during authentication module processing. Processing of each Auth clause is
performed in the following sequence:

1. If the clause has a PREDICATE directive, it is evaluated in the current context. If
the value is not True (including cases where the expression was invalid), processing
of the clause terminates immediately with the same result as if its authentication had
been unsuccessful.

2. If a variable named ${Auth::ABORT} has the value yes (case insensitive),
authentication terminates. If the variable ${Auth::MODULE_SKIP} has the value yes
(case insensitive), processing of the clause terminates immediately with the same
result as if its authentication had been unsuccessful.

3. If the clause has an INIT* directive, it is evaluated; if an error occurs,
authentication terminates.

4. If the clause has a URL directive, it names the authentication module to be invoked
(or is the name of a built-in module).

If the URL* directive is used instead, it is evaluated to obtain the URL to be
invoked; if an error occurs, authentication terminates.

5. If a variable named ${Auth::ABORT} has the value yes (case insensitive),
authentication terminates. If the variable ${Auth::MODULE_SKIP} has the value yes
(case insensitive), processing of the clause terminates immediately with the same
result as if its authentication had been unsuccessful.

6. If the clause's STYLE is expr, the EXPR directive is evaluated and is expected to
either return False or a valid DACS username. If the expression's value is False,
processing of the clause terminates immediately with the same result as if its
authentication had been unsuccessful; if its value is an invalid username,
authentication terminates, otherwise the module is deemed to have been successful. If
an error occurs, authentication terminates.

If the clause's STYLE is not expr, the authentication module is invoked.

7. If an error occurs while executing the authentication module, authentication
terminates. If the authentication module does not authenticate the user, the CONTROL
directive determines whether authentication fails or continues.

The username passed to the module, or returned by the module, becomes the tentative
DACS username and the variable ${Auth::CURRENT_USERNAME} is set to it. If the variable
${Auth::ROLES} is set to a valid role descriptor, it becomes the current tentative
roles for the user.

8. The expression given by the EXIT* directive, if any, is evaluated. If an error occurs,
authentication terminates. The expression may update ${Auth::CURRENT_USERNAME}. For
instance, the directive:

EXIT* '${Auth::CURRENT_USERNAME}="bobo"'

completely ignores the username returned by the module and simply assigns one, while
this directive:

EXIT* '${Auth::CURRENT_USERNAME} = \
strtr(${Auth::CURRENT_USERNAME}, "A-Z", "a-z")'

converts all upper case characters in the username returned by the module to their
lower case equivalents.

9. If a variable named ${Auth::ABORT} has the value yes (case insensitive),
authentication terminates despite success of the module. If the variable
${Auth::MODULE_SKIP} has the value yes (case insensitive), processing of the clause
terminates immediately with the same result as if its authentication had been
unsuccessful.

The value of ${Auth::CURRENT_USERNAME} when the last module has been processed is the
username that will be assigned to a successfully authenticated user. If set, the value of
${Auth::CREDENTIALS_LIFETIME_SECS} will be used as the lifetime of the generated
credentials; if not set, the value returned by the last successful authentication module
is used (typically that of the module's CREDENTIALS_LIFETIME_SECS directive), if
available, or the jurisdiction's CREDENTIALS_LIFETIME_SECS directive's value.

Authenticating Using an Expression
Rather than using an authentication module, the expr style of authentication involves
evaluating an expression. The value of the expression is the DACS username to associate
with the user. If no value is returned, an invalid value is returned, or an error occurs,
the Auth clause fails.

Here is a simple example that is unlikely to be used in practice. If the PASSWORD argument
is "xyzzy", then authentication will succeed and the user will be assigned the DACS
username bobo.

<Auth id="expr1">
STYLE "expr"
CONTROL "sufficient"
EXPR '${Args::PASSWORD} eq "xyzzy" ? "bobo" : ""'
</Auth>

This example illustrates how an expression can be used to read a password (its hex-encoded
SHA-256 hash, actually) from a file and compare it with the one provided in the service
request. Each user has his own password file that consists of a single line of text
containing the hash. If a username is given that does not have a corresponding password
file, or if the hash of the provided password does not match the stored one, the Auth
clause will fail, otherwise the given username is returned as the authenticated name.

<Auth id="expr5">
STYLE "expr"
EXPR '${pwd} = get("/usr/local/dacs/pwd/pwd." . ${Args::USERNAME}); \
digest(${Args::PASSWORD}, 0, sha256) eq decode(hex, ${pwd}) \
? ${Args::USERNAME} : ""'
CONTROL "sufficient"
</Auth>

The expression can also assign a valid role string to ${Auth::ROLES} to establish roles
for the user (in conjunction with the add_roles[69] or set_roles[70] style modifier):

<Auth id="expr2">
STYLE "expr,add_roles"
CONTROL "sufficient"
EXPR '${Auth::ROLES}="foo,bar"; ${Args::PASSWORD} eq \
"xyzzy" ? "bobo" : ""'
</Auth>

This style of authentication can be a useful alternative to the cert style with the
local_cert_authenticate module. If the client has provided an X.509 certificate that has
been adequately verified by the web server, then in many cases all that remains to be done
is to assign a syntactically valid DACS username to the client. Environment variables[79]
created by mod_ssl[80] can be referenced as ${Auth::ssl_variable_name}. Something such as
the following might be suitable:

<Auth id="expr3">
STYLE "expr"
CONTROL "sufficient"
EXPR '${Auth::SSL_CLIENT_VERIFY} eq "SUCCESS" and
${Auth::SSL_CLIENT_S_DN_Email:ei} \
? ${Auth::SSL_CLIENT_S_DN_Email:i} : ""'
</Auth>

Another application of this style of authentication is where it is the location of the
user that is important rather than the user's identity per se. For example, if a system
administrator needs to restrict access to a web server to the hosts in a lab or desktops
in a group of offices (that presumably share a subnet) but does not require individual
users to authenticate, a configuration like the following might be adequate:

<Auth id="expr4">
STYLE "expr"
CONTROL "sufficient"
EXPR '${Auth::CURRENT_USERNAME} = "user-${Env::REMOTE_ADDR}"'
</Auth>

A user would not provide a username or a password; by simply clicking on a link that
invokes dacs_authenticate, a user from the computer with IP address 10.0.0.213 (for
example) would be assigned the identity user-10.0.0.213. Access control rules could be
expressed in terms of those identities or the corresponding IP addresses.

Middleware Support
As with most DACS web services, the FORMAT argument can be used to request a particular
type of output (see dacs.services(8)[81]) from dacs_authenticate. If any XML type is
specified, the reply from dacs_authenticate will conform to the DTD
dacs_auth_reply.dtd[82]. The reply indicates whether the user has been successfully
authenticated or not. If authentication was successful, a description of the new
credentials is returned as a dacs_current_credentials element, (as described by
dacs_current_credentials.dtd[83]). If authentication was unsuccessful because of a
transient error condition, a reason may optionally be provided.

Security
This reason is solely used to inform the user; it should not reveal any details that
might compromise security.

Authentication modules return an auth_reply.dtd[84] document to dacs_authenticate.

Authentication Modules
Important
DACS provides a set of authentication modules. At the time DACS is compiled, some
standard modules are enabled by default while others needed must be specifically
enabled (see dacs.install(7)[85]). You should not enable authentication modules that
you do not plan to use.

Security
• As a security measure, these modules should be executable only by
dacs_authenticate, which is the default.

• By default, access control rules are configured to restrict access to all
authentication and roles modules. This prevents an attacker from calling an
authentication module directly in an attempt to guess account names, passwords,
and so on.

• Modules may need to be installed setuid or setgid as appropriate so that it is
possible for them to read the password files that they require or obtain
encryption keys.

• Modules may need to be installed setuid or setgid, and never run as the UID of a
less-privileged user, so that it is impossible to circumvent the module's
functionality (e.g., by attaching to the running module with a debugger).

Each authentication module is called with the following arguments. Authentication modules
are always invoked using the POST method.

AUXILIARY
The value of the AUXILIARY argument to dacs_authenticate if one was given, otherwise
the empty string.

DACS_JURISDICTION
The value of the DACS_JURISDICTION argument to dacs_authenticate.

DACS_VERSION
The DACS_VERSION_NUMBER for this version of dacs_authenticate.

PASSWORD
The value of the PASSWORD argument to dacs_authenticate if one was given, otherwise
the empty string.

USERNAME
The value of the USERNAME argument to dacs_authenticate.

Directives
Each directive in the Auth section being processed and its value is passed.

SSL/TLS environment variables
Each SSL/TLS environment variable passed to dacs_authenticate is passed.

Transaction state data
With respect to the prompted style of authentication, transaction state variables are
passed.
Ordinarily, a particular argument may not appear more than once.

Authentication Module Index:

1. local_apache_authenticate: Password-protected accounts maintained by Apache utilities

2. local_cas_authenticate: Central Authentication Service (CAS)

3. local_cert_authenticate: SSL-based X.509 client certificates

4. local_grid_authenticate: Grid-based one-time passwords

5. local_http_authenticate: Generic authentication via HTTP

6. local_infocard_authenticate: Information Card-based accounts and identities

7. local_ldap_authenticate: Lightweight Directory Access Protocol (LDAP) / Microsoft
Active Directory

8. local_native_authenticate: Importing an identity established by Apache

9. local_ntlm_authenticate: Microsoft Windows NT LAN Manager usernames and passwords

10. local_pam_authenticate: Pluggable Authentication Modules (PAM)

11. local_passwd_authenticate: Password-protected DACS accounts

12. local_simple_authenticate: Account name without a password

13. local_tgma_authenticate: Time-Gated Mutual Authentication (experimental)

14. local_token_authenticate: One-time passwords, two-factor authentication

15. local_unix_authenticate: Unix usernames and passwords

local_apache_authenticate
The local_apache_authenticate module is used to authenticate against password files
used by the Apache mod_auth[86], mod_auth_digest[87], or mod_auth_dbm[88] modules.
These password files are managed by Apache's htpasswd(1)[89], htdigest(1)[90], and
htdbm(1)[91] utilities, respectively. An administrator can configure DACS to use an
existing htpasswd file, for instance, and so avoid dealing with creating and managing
a duplicate set of usernames and passwords.

If HTTP Basic authentication (RFC 2617[60]) is used, the STYLE should be password. If
Digest authentication is used, because no password is passed to DACS, the STYLE for
this module should be configured as digest.

The following configuration options are recognized by this module. They should be
provided using the OPTION directive.

AUTH_MODULE
This must be "mod_auth" (or "htpasswd"), "mod_auth_digest" (or "htdigest"), or
"mod_auth_dbm" (or "htdbm"), depending on which module's authentication method is
to be used. This value is case-insensitive.

AUTH_FILE
This is the absolute pathname of the flat-file or database file to use.

Note
This pathname is resolved on the host that runs this module. This should
eventually be extended to accept a DACS virtual filestore URI.

DBM_TYPE
Required only in conjunction with mod_auth_dbm compatibility, this argument
identifies the database format of AUTH_FILE. The names "sdbm" (not yet
implemented), "gdbm", "ndbm", and "db" are recognized, although not all types may
be available on a particular platform.

Notes
• This module does not rely on any Apache module (other than mod_auth_dacs).

• This module does not require any Apache configuration with respect to
authentication; only DACS needs to be configured.

• It is not necessary to use DACS's HTTP Authentication[5] feature in order to
use this module. For example, using HTTP Basic authentication (RFC 2617[60]),
the USERNAME and PASSWORD arguments can be submitted from a site's login page
and verified by this module against an htpasswd file.

• htpasswd allows plaintext passwords to be stored in a password file, although
httpd apparently restricts the use of these passwords. This module imposes no
such restrictions. Under normal circumstances passwords should not be stored
in plaintext form.

• The major difference between this module and local_native_authenticate[92] is
that the latter "imports" an identity already established by an Apache
authentication module, whereas this module authenticates using information
that can also be used by Apache and which is administered using Apache
utiltities.

• DACS will access Apache password files in read-only mode only; DACS never
modifies those files.

• Some platforms may not support all possible DBM-type databases and some types
of database may not have been configured at build-time.

Here is an example configuration that uses an htpasswd-managed file for
authentication:

HTTP_AUTH_ENABLE "yes"
HTTP_AUTH "Basic \"DACS Basic Auth Area\" /restricted/*"

<Auth id="apache-htpasswd">
URL "https://example.com/cgi-bin/dacs/local_apache_authenticate"
STYLE "pass"
CONTROL "sufficient"
OPTION "AUTH_FILE=/usr/local/apache2/conf/passwords"
OPTION "AUTH_MODULE=mod_auth"
</Auth>

If the passwords were kept in a Berkeley DB database instead, the configuration might
look like:

HTTP_AUTH_ENABLE "yes"
HTTP_AUTH "Basic \"DACS Basic Auth Area\" /restricted/*"

This example configuration is similar; the difference is that the username and
password obtained through HTTP Basic authentication are verified against a Unix
account:

HTTP_AUTH_ENABLE "yes"
HTTP_AUTH "Basic \"DACS Basic Auth Area\" /private/*"

<Auth id="basic">
URL "https://example.com/cgi-bin/dacs/local_unix_authenticate"
STYLE "pass"
CONTROL "sufficient"
</Auth>

This example configures HTTP Digest authentication and references an htdigest-managed
file:

HTTP_AUTH_ENABLE "yes"
HTTP_AUTH "Digest \"DACS Digest Auth Area\" /digest/*"

<Auth id="apache-htdigest">
URL "apache"
STYLE "digest"
CONTROL "sufficient"
OPTION "AUTH_FILE=/usr/local/apache2/conf/passwords.digest"
OPTION "AUTH_MODULE=mod_auth_digest"
</Auth>

Tip
A built-in version of this module can be selected by using the URL
local_apache_authenticate or just apache.

local_cas_authenticate
This module coordinates with a specified Central Authentication Service (CAS)[93]
server to authenticate a user that is purportedly known to that server. The module
implements the client side of the CAS 2.0 Protocol[94] and can be used in two
different modes: interactive and non-interactive.

Interactive mode is employed if neither a USERNAME nor a PASSWORD argument is given to
dacs_authenticate. When dacs_authenticate is called, whether directly or as the result
of redirection after access was denied to an unauthenticated user, it redirects the
user to a CAS login page. After successful CAS authentication (which may return a
ticket granting cookie to the user's browser), CAS redirects the user to
dacs_authenticate, passing it the CAS session ticket as an argument called ticket.
After successfully validating the session ticket at the CAS server, DACS
authentication succeeds.

Security
When interactive mode is used, DACS does not see the username and password, only
CAS does. The username is obtained by the module as part of the session ticket
validation protocol. This mode of operation is similar to, but simpler than, the
OpenID[95] Authentication protocol.

A variant of this flow of control can occur if the user has authenticated against the
CAS server outside of DACS and therefore holds a ticket granting cookie. This cookie
will automatically be sent by the user's browser when it is redirected to the CAS
server; as a result, the CAS server may not prompt the user to authenticate.

In non-interactive mode, both a USERNAME and a PASSWORD argument are passed to
dacs_authenticate. This module will use these arguments to authenticate the user
against the CAS server. In this mode, no ticket granting cookie will be returned to
the user. This mode can be used with the DACS HTTP authentication[5] feature.

The STYLE should be configured as cas for this module.

The following module-specific OPTION directive value is understood:

CAS_SERVER_URI (Required1)
This is the URI of the CAS server to authenticate against. For example, dacs.conf
might contain authentication configuration similar to the following:

<Auth id="CAS">
URL "cas"
STYLE "cas"
CONTROL "sufficient"
OPTION "CAS_SERVER_URI=https://cas.example.com/castest"
</Auth>

The module recognizes the following arguments (which are automatically passed to it as
necessary by dacs_authenticate):

CAS_TICKET (Required1-C)
This is the session ticket returned by CAS via a callback to dacs_authenticate
(i.e., the ticket argument).

CAS_REDIRECT_ARGS (Optional1)
These are additional arguments to dacs_authenticate that must be provided when CAS
performs its callback to dacs_authenticate to preserve user preferences. The
DACS_BROWSER, FORMAT, DACS_ERROR_URL, and ENABLE_AUTH_HANDLERS arguments may be
forwarded in this way.

CAS_SERVER_URI (Required1-C)
This argument has the value specified in the Auth clause's OPTION directive. Note
that HTTP redirects are not handled in this context, so invoking GET on
CAS_SERVER_URI must return a valid document.

Note
The local_cas_authenticate module extends the response of the validate service of
the CAS protocol to allow a role descriptor string (role_string) to be returned.
If authentication succeeds, the standard service returns the following text:
yes\nusername\n

An invalid role string is discarded. If these roles should be used, it will be
necessary to use either the set_roles[70] or add_roles[69] style modifier with the
STYLE[96] directive.

Tip
The authentication procedure described by the CAS protocol is notable because the
authentication material provided by the user in interactive mode does not flow
through DACS; in particular, DACS does not see a user's password when this module
is used. This may be an important consideration in some environments.

Because the protocol implemented by this module is general purpose and relatively
simple, writing middleware that implements a subset of the server-side CAS
protocol to interface with this module may be a sensible solution for DACS
administrators who require a CAS-like control flow but do not want to use actual
CAS server-side software. The user would be redirected to the middleware component
by local_cas_authenticate to perform the /login service; then it would prompt and
authenticate the user, and redirect the user to a URL provided to it by
local_cas_authenticate; then local_cas_authenticate would call the middleware
component directly, this time to perform the /validate service. The usual flow of
control within DACS would follow.

A simple script for testing and working with local_cas_authenticate is available
in src/cas_middleware_test.

Tip
A built-in version of this module can be selected by using the URL
local_cas_authenticate or just cas.

local_cert_authenticate
The local_cert_authenticate module authenticates a user that supplies an acceptable
X.509 client certificate via SSL/TLS. Apache must be appropriately configured to
request and verify client certificates, check for revocation, and so on (see
SSLVerifyClient[97] and related directives). As part of the SSL/TLS protocol, Apache's
mod_ssl[80] module verifies that the client possesses the private key that corresponds
to the client certificate. Apache will usually be configured to verify the
correctness and suitability of the client certificate. Apache directives such as
SSLRequire[98] might be used, for example.

The STYLE should be configured as certificate for this module.

The verification of the client certificate done by Apache may be sufficient, in which
case the only remaining configuration task for the Auth clause is to assign a username
and possibly extract role information from the certificate; it may impose additional
tests on the certificate, however, by inspecting its fields. If verification beyond
the ability of mod_ssl[80] is required, or if it needs to be performed on a system
other than where the web server is running, local_cert_authenticate can execute an
external program to decide whether the client certificate is suitable for
authentication. This program is currently limited to OpenSSL[99] but this may be
generalized in future versions.

To ensure that local_cert_authenticate is able to obtain information contained within
the client certificate, Apache must be configured so that StdEnvVars and
ExportCertData are enabled in an appropriate SSLOptions[100] directive, such as the
following:

SSLOptions +StdEnvVars +ExportCertData

The following configuration directives are specific to this module:

CERT_CA_PATH (Required1)
This is the absolute pathname of a directory that contains trusted certificates.
Refer to the -CApath argument to OpenSSL's verify command.

CERT_DUMP_CLIENT (Optional1)
If configured, this gives the absolute pathname of a file to which the client
certificate is to be written in PEM format. The file is created or truncated, as
necessary. This is useful for debugging purposes.

CERT_NAME_ATTR (Optional1)
If this directive is configured, it gives the name of an SSL/TLS environment
variable[79]. The value of that variable is used as a key for the certnamemap item
type (which must also be configured); the key's value becomes the username
returned by the module (if the environment variable is not found or the lookup is
unsuccessful, the module will fail to authenticate the user). If the module is not
fully configured for this lookup, the value of the USERNAME is returned by the
module.

To illustrate this, consider the following configuration:

VFS "[certmap]dacs-kwv-fs:/usr/local/dacs/federations/certnamemap"

<Auth id="cert">
URL "https://example.com/cgi-bin/dacs/local_cert_authenticate"
STYLE "cert"
CONTROL "sufficient"
CERT_CA_PATH "/usr/local/apache2/conf/ssl.crt"
CERT_NAME_ATTR "SSL_CLIENT_S_DN_CN"
</Auth>

with the file /usr/local/dacs/federations/certnamemap containing the two lines:

Clark Kent:superman
Bruce Wayne:batman

Given the configuration above, if the value of the SSL_CLIENT_S_DN_CN environment
variable is "Clark Kent", the username returned by the module will be "superman".

As with any module, an expression can be used within an Auth clause to modify or
override the value returned by a module.

CERT_OPENSSL_PATH (Optional1)
This is the absolute pathname of the openssl program. If not provided, a
build-time value is used (OPENSSL_PATH).

Security
The lifetime of credentials obtained through the local authentication service may
be independent of the validity period of the certificate presented for
authentication. It is therefore possible for the certificate to expire before the
DACS credentials. The local authentication service might take this into
consideration before granting access and when computing a lifetime for the
resulting DACS credentials.

local_grid_authenticate
This module works in concert with the dacsgrid(1)[101] utility to provide users with
one-time passwords. It is also an approximation of the "something you have" factor of
two-factor authentication.

The STYLE should be configured as password for this module.

Please refer to dacsgrid(1)[101] for a complete description.

In addition to the usual USERNAME argument, the module requires the PASSWORD argument
to be the user's response to the challenge and the AUXILIARY argument to be the
encoded challenge. The latter two arguments must be produced by dacsgrid(1)[101].

The following OPTION directive values are understood:

AUTH_GRID_CHALLENGE_SECS (Optional1)
The number of seconds between when a challenge is created and when it expires,
overriding the default value. This value should be relatively small, at most on
the order of a few tens of seconds. If this module runs on a host other than the
one running dacs_authenticate, the two system clocks must be suitably
synchronized.

AUTH_GRID_LIFETIME_SECS (Optional1)
The length of time, in seconds, for which a grid is valid. After this period, all
authentication against a grid will fail.

Tip
A built-in version of this module can be selected by using the URL
local_grid_authenticate or just grid.

local_http_authenticate
This module authenticates by invoking a given (non-interactive) web service with
specified arguments. If the web service reports success by returning HTTP status code
200 (see RFC 2616[43], Section 10), then the module succeeds, otherwise it fails. No
session is established with the web service and no additional requests are made to it.

In its simple (default) mode of operation, any output returned by the web service is
discarded, including cookies. The web service is used solely to determine whether a
username/password is correct. In its alternate mode, the web service can return a
document that specifies a replacement username, lifetime of generated credentials, and
a role string.

This module can be used to authenticate against any existing web service that follows
the expected protocol, or provide a way to add a new, custom authentication method to
DACS.

The STYLE should be configured as password for this module.

The following OPTION directive values are understood:

AUTH_URL (Required1)
The URL of the web service to invoke, which need not be DACS-wrapped. It may use
either the http or https scheme. No DACS credentials will be sent with the
request.

AUTH_METHOD (Optional1)
The HTTP method to use to invoke AUTH_URL. The default is POST. Keep in mind that
if query arguments are present (or if the GET method is used) they may appear in
log files.

PASSWORD_PARAMETER (Optional1)
The name of the argument by which PASSWORD is passed to the web service. The
default is PASSWORD.

USERNAME_PARAMETER (Optional1)
The name of the argument by which USERNAME is passed to the web service. The
default is USERNAME.

USE_AUTH_REPLY (Optional1)
The default behaviour is to ignore any document that is returned by the web
service. If this option is "yes" or "on", however, the web service must return a
syntactically valid auth_reply.dtd[84] document. For authentication to succeed,
the document must indicate successful authentication. The contents of a valid
document will provide the username (overriding USERNAME), and, optionally, the
lifetime of the credentials and a role string. If the STYLE directive does not
include an add_roles[69] or set_roles[70] modifier, the role string will be
ignored. This capability allows a generic web service to be called with arbitrary
arguments to dynamically authenticate a user, and set an identity and roles. The
returned values must be valid.

Any other OPTION directive values are simply passed to the invoked web service,
including any duplicate argument names.

For Google[102] account authentication[103], for instance, the following configuration
might be used:

<Auth id="google">
URL "local_http_authenticate"
STYLE "password"
CONTROL "required"
OPTION 'AUTH_URL="https://www.google.com/accounts/ClientLogin"'
OPTION 'USERNAME_PARAMETER=Email'
OPTION 'PASSWORD_PARAMETER=Passwd'
OPTION 'service=xapi'
OPTION "source=DSS-DACS-1.4"
</Auth>

This web service returns an HTTP status code of 200 if the correct username and
password are given (i.e., login succeeded), and 403 if login fails. If ClientLogin
fails and requests a CAPTCHA challenge the request will not be passed back to the
user.

Note
One of the reasons for inclusion of this module is to support reuse of accounts
widely used by the public. Googleprovides exactly the right interface needed by
systems such as DACS. As of 20-April-2012, Google has officially deprecated
ClientLogin. Accounts provided by eBay[104]and Yahoo![105], for instance, do not
appear to be directly usable in this way. In some cases, dacs_auth_transfer(8)[8]
may be a better approach than this module.

The following outlines a trivial example of authentication using the USE_AUTH_REPLY
directive. Assume that the following shell script can be invoked as
http://example.com/cgi-bin/myauth:

#! /bin/sh

/bin/cat <<HERE

<?xml version="1.0" encoding="US-ASCII"?>
<!DOCTYPE auth_reply SYSTEM "http://example.com/dacs/dtd-xsd/auth_reply.dtd">
<auth_reply>
<ok username="guest">
<roles_reply>
<ok roles="bigwheel,mediumwheel,littlewheel"/>
</roles_reply>
</ok>
</auth_reply>
HERE

exit 0

Also assume the following Auth clause has been configured:

<Auth id="http">
URL "local_http_authenticate"
STYLE "password,set_roles"
CONTROL "required"
OPTION 'AUTH_URL="http://example.com/cgi-bin/myauth"'
OPTION 'AUTH_METHOD=GET'
OPTION 'USE_AUTH_REPLY="YES"'
</Auth>

Invoking this URL will always successfully authenticate any user and issue credentials
for the identity JUR1:guest with roles bigwheel,mediumwheel,littlewheel:

https://example.com/cgi-bin/dacs/dacs_authenticate?USERNAME=alice&PASSWORD=test&DACS_JURISDICTION=JUR1

This expression[3] is equivalent:

% dacsexpr -e 'dacsauth("-m http passwd,set_roles suff -OAUTH_URL=http://bsd9.dss.ca/cgi-bin/dacs/http_auth \
-OAUTH_METHOD=GET -OUSE_AUTH_REPLY=yes -u test -p test")'
{"result",1,"identity","DSS::BSD9:guest","roles","bigwheel,mediumwheel,littlewheel"}

Tip
A built-in version of this module can be selected by using the URL
local_http_authenticate or just http.

local_infocard_authenticate
Deprecated
In early 2011, Microsoft announced[106] that it would not support CardSpace[107]
(aka, Infocards and Information Cards) starting with Windows 8[108]. CardSpace has
been the most widely available identity selector for using Information Cards.

The implementation of Infocards support within DACS remains in the code base and
is documented, but is no longer being actively tested and maintained (neither are
the demos). Support for Information Cards within DACS will likely be removed
eventually. You may notice that other Infocard and CardSpace related projects have
been terminated and their web pages are out of date or no longer available.

References: On the Demise of CardSpace[109]; Open Cardspace opportunity[110];
Personal Reflections on the CardSpace Journey[111]; From CardSpace to Verified
Claims[112]; Change will come: the present is untenable[113]; The Clay Feet of
Giants?[114]; RIP, Windows CardSpace. Hello, U-Prove[115]; and U-Prove[116].

The local_infocard_authenticate module performs DACS authentication using an
Information Card[62] (InfoCard) previously registered at the jurisdiction. Self-issued
InfoCards are registered using dacs_infocard(8)[64] or dacsinfocard(1)[63]. Managed
InfoCards are also supported, provided they have been registered using
dacs_managed_infocard(8)[65] and include a dacs_identity claim in the DACS namespace.
DACS aims to conform to Identity Selector Interoperability Profile (ISIP) 1.5[117].

A DACS role descriptor string[118] can be associated with a managed InfoCard through
the dacs_roles claim name in the DACS namespace (see dacs_infocard(8)[119]. These
roles can be associated with new credentials via the add_roles[69] and set_roles[70]
modifiers.

Security
At present, to be valid for authentication, the dacs_identity claim value must
specify a user at the current jurisdiction; that is, it cannot specify an identity
at a jurisdiction other than the one where authentication is being performed.

The authentication style infocard causes the module to accept either type of InfoCard
- the type of InfoCard actually used will be available in the resulting credentials.
The styles managed_infocard and selfissued_infocard tell the module to limit
authentication to managed InfoCards or self-issued InfoCards, respectively. When
invoked as a web service, local_infocard_authenticate understands an optional
argument, TYPE, that may have the value "selfissued" or "managed" to restrict
authentication to the corresponding InfoCard type; the default behaviour accepts
either type of InfoCard.

Tip
The expression-based authentication style[120], which does not call this module,
provides an alternative way to support InfoCard-based authentication. It is
somewhat more complicated to use, however, and may require a small amount of
programming.

For additional information about InfoCards, please refer to:

• dacs_managed_infocard(8)[121], dacs.conf(5)[122] (the INFOCARD_ prefixed
directives), dacs_mex(8)[123], and dacs_sts(8)[124].

• Using InfoCards With DACS[125], Distributed Systems Software (July, 2009).

• Identity Selector Interoperability Profile specification and companion guides[126]
(August, 2008).

• Introducing Windows CardSpace[127] (April, 2006).

Tip
A built-in version of this module can be selected by using the URL
local_infocard_authenticate or just infocard.

local_ldap_authenticate
The local_ldap_authenticate module performs DACS authentication using the Lightweight
Directory Access Protocol, also known as LDAP, (see RFC 2251[128], RFC 2252[129], RFC
2253[130], RFC 3377[131], and many others). This form of authentication can be used
with Microsoft's Active Directory (ADS)[132]. OpenLDAP[133] is used to supply LDAP
client support.

The STYLE should be configured as password for this module.

In general, authentication using LDAP is challenging because an LDAP name (a
distinguished name, or DN) is typically long and often has a site-specific structure.
For this reason, this module often requires more local expertise for configuring and
testing than other DACS authentication modules. At least a basic familiarity with LDAP
will be required to configure this module.

The module implements two different approaches to authentication:

1. In the direct method, which is the simpler and more efficient approach, the
USERNAME argument is directly mapped to the corresponding DN. The module binds to
that DN using the given PASSWORD. If the bind operation succeeds, the user has
been authenticated.

2. When the simpler method is not possible, the indirect method can be used to bind
to the directory as an LDAP administrator (or an identity with the ability to
search the appropriate portion of the directory tree) and perform an LDAP search
operation for a directory entry having an attribute that matches the USERNAME
argument. If the search returns exactly one entry, it binds to that entry's DN
using the PASSWORD argument; if the bind operation succeeds, the user has been
authenticated.

Regardless of the approach, after successful authentication it may be necessary to map
the USERNAME or the DN into a valid DACS username.

The following configuration directives are specific to this module:

LDAP_ADMIN_PASSWORD (Optional1)
This is the password for the LDAP administrator account that corresponds to
LDAP_ADMIN_URL.

LDAP_ADMIN_URL (Required1-C)
If the indirect method is used, this directive is required. This value is a URI
like LDAP_USERNAME_URL except that it identifies the LDAP directory's
administrator. Example:

LDAP_ADMIN_URL
"ldap://example.com/cn=Administrator, cn=Users, dc=example, dc=com"

LDAP_BIND_METHOD (Required1-C)
This directive tells the module to use the direct method, indirect method, or both
methods (case insensitive). When both are used, the indirect method is attempted
only if the direct method fails.

LDAP_ROLES_SELECTOR* (Optional)
Since LDAP directory operations are usually relatively expensive, this module can
return role information for the authenticated user, avoiding a second LDAP
operation during Roles clause processing. Roles are typically extracted from
information in the user's directory entry. Each occurrence of this directive
specifies an expression that is evaluated by iterating through each attribute of
the entry and making the attribute name (${LDAP::attrname}) and its value
(${LDAP::attrvalue}) available. All of the entry's attribute names and values are
made available within the LDAP namespace. If the result of the expression is a
valid role string (which excludes the empty string, ""), it is added to the list
of roles.

An example:

LDAP_ROLES_SELECTOR* '"${LDAP::attrname}" eq "memberOf" \
? strtr(ldap(rdn_attrvalue, \
ldap(dn_index, "${LDAP::attrvalue}", 1)), " ", "_") \
: ""'

For each instance of the entry's memberOf attribute, this expression selects the
least significant (left-most) component of the attribute value (a DN) using
ldap()[134] and converts spaces to underscores. If the user's entry contains:

memberOf: CN=Domain Guests,CN=Users,DC=example,DC=com
memberOf: CN=Guests,CN=Builtin,DC=example,DC=com

the resulting roles would be Domain_Guests and Guests.

Note
These roles are discarded unless the STYLE[96] directive for this module
allows the roles to be incorporated into the user's credentials.

LDAP_SEARCH_FILTER (Required1-C)
If the indirect method is used, either this directive or LDAP_SEARCH_FILTER* (but
not both) must be configured. This search filter is used to select the unique
directory entry that corresponds to this user.

LDAP_SEARCH_FILTER* (Required1-C)
If the indirect method is used, either this directive or LDAP_SEARCH_FILTER (but
not both) must be configured. This search filter is used to select the unique
directory entry that corresponds to this user. This directive is exactly like
LDAP_SEARCH_FILTER except that it is evaluated just before it is used, allowing
various elements of the execution context to appear in the string. Example:

LDAP_SEARCH_FILTER* '"(sAMAccountName=${Args::USERNAME})"'

LDAP_SEARCH_ROOT_DN (Required1-C)
This is the root DN at which the indirect method should begin searching for user
entries.

LDAP_TIMEOUT_SECS (Optional1)
This is a maximum time limit, in seconds, for any individual LDAP read or search
operation performed by the module. If not specified, there will not be an
application-specified time limit.

LDAP_USERNAME_EXPR* (Optional1)
If authentication succeeds, this directive is evaluated to yield the DACS username
returned to dacs_authenticate. All of the entry's attribute names and values are
made available within the LDAP namespace. If unspecified, the value of the
USERNAME parameter is returned. Example:

LDAP_USERNAME_EXPR* '"${LDAP::sAMAccountName}"'

LDAP_USERNAME_URL (Optional1)
If the direct method is used, either this directive or LDAP_USERNAME_URL*[135]
(but not both) must be configured. This directive identifies both the LDAP server
to use and the user being authenticated. The value of this directive is a URI (see
RFC 2396[136] and RFC 3986[137]) that gives the name of the LDAP server to contact
to authenticate the user (as the scheme and authority part of the URI) and the DN
for the user (as the path part of the URI). The scheme must be either ldap or
ldaps (case insensitive). If no port number is specified, 389 is used with the
former scheme and 636 with the latter.

LDAP_USERNAME_URL
'"ldap://example.com/cn=Auggie%20Doggie, cn=Users, dc=example, dc=com"'

Security
The ldaps scheme is not implemented. Communication between this module and the
LDAP server should use a secure channel or at least not be snoopable.

LDAP_USERNAME_URL* (Optional1)
If the direct method is used, either this directive or LDAP_USERNAME_URL (but not
both) must be configured. This directive is exactly like LDAP_USERNAME_URL except
that it is evaluated just before it is used, allowing various elements of the
execution context to appear in the string. Example:

LDAP_USERNAME_URL*
'"ldap://example.com/cn=${Args::USERNAME}, cn=Users, dc=example, dc=com"'

Tip
Before using LDAP authentication with DACS, you should first make sure that your
LDAP server is functioning as you expect and that the host that will run the
local_ldap_authenticate module can communicate with the LDAP server.

One way to do this is to use the ldapsearch(1)[138] command (found in the
clients/tools directory of the OpenLDAP distribution) to bind to the directory and
perform some searches. You should run this command on the same machine that will
be running DACS's LDAP authentication module (local_ldap_authenticate). Some of
the information that you obtain from this exercise may be helpful when you
configure DACS to use this form of authentication.

Here are some examples to try - you must adapt the names for your environment:

% ./ldapsearch -h win2k.example.com -x -b "dc=example,dc=com" \
-D "CN=Administrator,CN=Users,DC=example,DC=com" -W -LLL
% ./ldapsearch -h win2k.example.com -x -b "dc=example,dc=com" \
-D "CN=Auggie Doggie,CN=Users,DC=example,DC=com" -W -LLL
% ./ldapsearch -h win2k.example.com -x -b "dc=example,dc=com" \
-D "CN=Administrator,CN=Users,DC=example,DC=com" -W -LLL \
"(cn=Administrator)" memberOf
% ./ldapsearch -h win2k.example.com -x -b "dc=example,dc=com" \
-D "CN=Administrator,CN=Users,DC=example,DC=com" -W -LLL \
"(sAMAccountName=auggie)"

In these examples, the LDAP server runs on a host named win2k.example.com (so
change win2k.example.com, example, and com), and it expects a user named "Auggie
Doggie" to exist and have the account name "auggie" (again, change to names that
exist in your LDAP directory). You should be prompted for the LDAP password (in
Windows, that will be the login password) for either Administrator or a user named
"Auggie Doggie", depending on the argument that follows the -D flag.

The following configuration illustrates authentication using this module:

<Auth id="ldap">
URL "https://example.com/cgi-bin/dacs/local_ldap_authenticate"
STYLE "password,add_roles"
CONTROL "required"
LDAP_BIND_METHOD "direct"
LDAP_USERNAME_URL* '"ldap://windows.example.com/cn=" \
. encode(url, ${Args::USERNAME}) . ",cn=Users,dc=example,dc=com"'
LDAP_USERNAME_EXPR* '"${LDAP::sAMAccountName}"'
LDAP_ROLES_SELECTOR* '"${LDAP::attrname}" eq "memberOf" \
? strtr(ldap(rdn_attrvalue, \
ldap(dn_index, "${LDAP::attrvalue}", 1)), " ", "_") \
: 0'
</Auth>

Here, the LDAP authentication module will construct a DN by plugging the user-provided
USERNAME argument into the template and binding to that DN with the PASSWORD argument.
If successful, the DACS username will be the value of the user's entry's
sAMAccountName attribute, and roles will extracted from the entry's memberOf attribute
values, as described above.

Note
In Windows, the SAM-Account-Name Active Directory attribute value (sAMAccountName)
need not be the same as the entry's Common Name; for instance, the former might be
"doggie" and the latter "CN=Auggie Doggie". The sAMAccountName must not exceed 20
characters in length and must be unique within the domain. It is composed of
printable characters other than the following:

\ / [ ] : ; | = , + * ? < > @ "

The userPrincipalName attribute value is a user account name (or "user login
name") that is unique within its domain and a domain name identifying the domain
in which the user account is located. The format is the same as a domain-name
based email address; e.g., doggie@example.com.

local_native_authenticate
The local_native_authenticate module transfers a user's current, context-dependent web
server identity to a DACS identity. The web server will most likely have used HTTP
Basic or Digest authentication (RFC 2617[60]). The user, having already been
authenticated by the web server at a particular jurisdiction, will automatically be
given DACS credentials associated with that jurisdiction and typically having the same
username.

The STYLE should be configured as native for this module.

This method of authentication also depends on a CGI helper program (autologin(8)[139])
and appropriate configuration of Apache authentication. The general idea is that the
helper program must be executable only by users that have been properly authenticated
by the web server (by any Apache method and using any Apache authentication module).
The helper program then invokes dacs_authenticate with appropriate arguments; if this
module has been enabled and accepts its arguments, the user will be given DACS
credentials.

There are no directives or options specific to this module.

local_ntlm_authenticate
The local_ntlm_authenticate module authenticates users through Windows NT LAN Manager
using the NTLM protocol [1[140], 2[141]]. This module, which makes use of Samba[142]
libraries, provides Windows NTLM authentication[143] based on a username and password.
The module does not need to be (and will not usually be) executed on the host running
Windows.

The STYLE should be configured as password for this module.

The following OPTION directive values are understood:

SAMBA_SERVER (Required1)
The domain name or IP address in standard dot notation of the Windows system
providing NTLM authentication.

SAMBA_PORT (Optional1)
The port number to use on SAMBA_SERVER. The default is 0, which tells Samba to use
a sequence of default ports until one works.

SAMBA_DOMAIN (Optional1)
The domain name to use on SAMBA_SERVER. The default is "".

The module-specific option SAMBA_SERVER must be given to provide the domain name of
the host providing the NTLM authentication. The module-specific options SAMBA_DOMAIN
and SAMBA_PORT, which are optional, can be used to override the default port(s) used
by Samba to contact SAMBA_SERVER.

The following illustrates how this module might be configured:

<Auth id="ntlm">
URL "https://example.com/cgi-bin/dacs/local_ntlm_authenticate"
STYLE "pass"
CONTROL "sufficient"
OPTION 'SAMBA_SERVER="10.0.0.123"'
OPTION 'SAMBA_PORT="139"'
</Auth>

Here, dacs_authenticate will invoke the NTLM authentication module at the given URL.
That module will try to authenticate the username and password given to it by asking
the NTLM service at port 139 on the Windows system at 10.0.0.213.

There are no directives specific to this module.

Security
Attacks against some versions of NTLM have been identified[144]. Communication
between this module and the NTLM service should use a secure channel or at least
not be snoopable.

Tip
• A built-in version of this module can be selected by using the URL
local_ntlm_authenticate or just ntlm.

• Before attempting to use this module, it may save a lot of time and
aggravation if you first check that it is possible to authenticate against
NTLM, from the machine on which you intend to run this module, using a
username/password combination that you know is correct. If you are not able to
successfully authenticate in this way, obviously you will not have any luck
with the DACS module.

To test whether it is possible to authenticate using a particular username and
password, you may be able to use smbclient(1)[145]. For example, if C:\Shared
is a network shared folder or HPLaserJ-PS is a shared printer on the Windows
machine on which you want to perform authentication, to authenticate as the
Administrator try something like:

% smbclient //mywinhost/shared -U Administrator

or to authenticate as the user bob, try:

% smbclient //mywinhost/HPLaserJ-PS -U bob

Replace mywinhost with the name of your Windows machine. You should be
prompted for the account's password. If smbclient successfully connects and
establishes a session using the username and password you provide, then this
module should also be able to authenticate that user, otherwise you should see
an error message.

Before you have configured DACS, you can test NTLM authentication from the
command line using dacsauth(1)[6]. For example, try something like:

% dacsauth -m ntlm passwd suff -OSAMBA_SERVER="windows.example.com" -prompt -u bob

Change "bob" to the username you want to authenticate and
"windows.example.com" to the domain name of the Windows machine where the
user's account is. You may also need to specify SAMBA_PORT if a non-standard
port is being used. You will be prompted for the password for the user's
account The program's exit status indicates success ("ok" is exit status 0) or
failure (exit status 1). Repeat this with an invalid password to make sure
that it fails.

After you have configured DACS, there is another method of testing
local_ntlm_authenticate from the command line. Set the environment variable
QUERY_STRING (using your preferred shell's syntax) to something like this:

% export QUERY_STRING="USERNAME=bob&PASSWORD=test&DACS_JURISDICTION=Test\
&SAMBA_SERVER=windows.example.com"

Change "bob" to the username you want to authenticate, "test" to the password
for that username, "Test" to the name of the DACS jurisdiction that will
perform the authentication, and "windows.example.com" to the domain name of
the Windows machine where the user's account is. You may also need to specify
SAMBA_PORT. Then from the distribution's src directory:

% ./local_ntlm_auth -uj Test

Use the -u, -uj, or -us flag to specify a jurisdiction that you have
configured (see dacs(1)[146]). The output, an XML document, indicates success
("ok", exit status 0) or failure ("failed", exit status 1). Repeat this with
an invalid password to make sure that it fails. When you are done, remember to
delete the QUERY_STRING environment variable.

local_pam_authenticate
This module makes a local or remote Pluggable Authentication Modules (PAM)
infrastructure available for authentication. PAM authenticates a user that is known to
the PAM-capable operating system (i.e., a user with an existing account) through one
or more PAM authentication service modules that have been configured by the system
administrator. Other PAM operations, such as password management, are currently
unsupported by DACS. Please refer to X/Open Single Sign-On Service (XSSO) -- Pluggable
Authentication[53] for additional information about PAM.

Notes
• The PAM-based infrastructure described here was mainly developed to allow a
system's PAM authentication services to be used for DACS web-based
authentication. See src/pamd.c for architectural details.

Although a prototype has been developed, no "native" PAM authentication module
for DACS is distributed. Such a module might be used to provide Unix services
with DACS authentication and access control functionality, conceptually
allowing dacsauth(1)[6] or dacscheck(1)[147] to be used by them. For instance,
configuration for ftp authentication that normally uses pam_unix.so might be
replaced by a reference to the module, leveraging any password style of DACS
authentication, such as local_ldap_authenticate[49].

• By default, the pamd server uses "dacs" as the name of the PAM service policy
(see pam_start(3)[148]). Some systems may revert to a default policy (such as
"other") if no "dacs" policy is defined. A policy name can be specified as a
pamd argument.

There is a huge selection of open source and vendor-supplied PAM authentication
modules for a wide variety of platforms, including some that provide functionality
similar to that of DACS authentication modules [GNU/Linux[149], FreeBSD[150],
macOS[151]]. For example, pam_unix(8)[152] performs essentially the same
authentication function as local_unix_authenticate[153], except that the latter is not
interactive (it does not prompt).

The STYLE should be configured as prompted for this module.

Note
While this authentication module has been tested with only a few PAM
authentication service modules, in theory it should work with any conformant PAM
authentication module. If this module is used, the current implementation does not
allow any other authentication modules to be configured for the jurisdiction; this
can be partially ameliorated by configuring PAM to try multiple PAM modules (yes,
writing "PAM modules" might be incorrect in the same way that "ATM[154] machine"
is).

Important
The local_pam_authenticate module depends on functionality provided by
pamd(8)[155] running on a PAM-capable system, which does not need to be the same
host where local_pam_authenticate is run. The local_pam_authenticate module
establishes connections with pamd, which interacts with the pam(3)[52] library.
Unlike the other DACS authentication styles, authentication using the prompted
style may involve more than one request to dacs_authenticate, each of which
supplies additional authentication material.

The prompted authentication style implements a session between the user and the
PAM library that consists of a sequence of operations that comprise a PAM
transaction. For each operation, dacs_authenticate (via local_pam_authenticate and
pamd) supplies the PAM library with authentication material (either initial data
or data requested by the PAM library from the previous operation), determines if
authentication has succeeded or failed, or whether the user must be prompted for
additional data. If the PAM library requires additional data, the user is prompted
for it, and the response is submitted to dacs_authenticate in the transaction's
next operation.

If PAM requires information from the user, local_pam_authenticate can be configured to
prompt for it using one of three methods. The first method is used if the Auth clause
has an OPTION directive that configures PAM_HANDLER_URL; the user will be redirected
to this URL. The other possibilities are selected by the FORMAT argument (see
dacs.services(8)[81]). If any XML type is specified, the reply from dacs_authenticate
will conform to the DTD dacs_auth_reply.dtd[82]. If HTML is specified and PAM
authentication requires additional information from the user, dacs_authenticate will
return a rudimentary HTML form that must be completed and submitted by the user. For
example, if pam_unix is configured, dacs_authenticate may emit a web page that prompts
for a username (if none was provided with the initial invocation of
dacs_authenticate), and after that form has been submitted by the user emit a web page
that prompts for a password.

If PAM_HANDLER_URL is configured, the handler to which the administrator redirects
users has complete control over user prompting. In most implementations, the handler
will emit a web page that includes a form element, with appropriate inputs and hidden
variables, which is submitted to the web service named in the service argument (see
below). The handler is required to obtain values for a set of requested variables and
submit them to a given URL (dacs_authenticate). Each variable has a type, an optional
descriptive text label, and a name. The value of PAM_HANDLER_URL may either be an
absolute URL or a web service name, beginning with a '/', that is interpreted relative
to the current jurisdiction (i.e., the dacs_url[156] is prepended). Query arguments
may be included, provided none of the argument names used by dacs_authenticate,
described below, are duplicated.

The pamd server requires the handler to respond within 60 seconds (configured at
compile time). The local_pam_authenticate module requires pamd to respond to the
initial request with the first prompt within 20 seconds (configured at compile time).
Should the handler encounter a serious error, it can simply terminate; this will cause
pamd to eventually time out, which will abort the PAM transaction.

Security
The handler does not have to be DACS-wrapped, but ideally it should be. If it is,
don't forget to add an access control rule to grant access to any user that might
authenticate through local_pam_authenticate.

This "prompter" service might be configured as follows:

OPTION "PAM_HANDLER_URL=/dacs_pam_handler"

This will be expanded into a URL that looks something like
https://example.com/cgi-bin/dacs/dacs_pam_handler. When a user is redirected to this
handler, dacs_authenticate adds the following query arguments:

• service: This is the URL of the dacs_authenticate service to which the handler
must submit the requested values. This URL will not include any query arguments.
Because private information, such as a password, may be present, it will typically
use the https scheme. The handler should use the POST method to invoke service.

• CSS_PATH: This is the path configured for HTML stylesheets.

• AUTH_TRANSID: This is the unique transaction identifier for this PAM interaction.
As part of a single authentication transaction, the handler may be called several
times with the same AUTH_TRANSID. The handler is not required to retain state
between these calls, but it may do so. The handler must pass this argument when
calling service. Although the lifetime of this identifier is relatively brief, it
should be kept private by the handler.

• auth_prompt_var_prefix: Each requested value will be identified by an argument to
service having this prefix, with a positive integer (int, which is assigned
consecutive integers starting with 1) appended. For instance, if
auth_prompt_var_prefix is "AUTH_PROMPT_VAR", then the handler must submit the
requested values as AUTH_PROMPT_VAR1, AUTH_PROMPT_VAR2, and so on. The first
absent int value signals the end of the variable argument list.

• TYPEint: This is the type ("text", "password", or "error") of the variable
numbered int. The password type indicates the value should not be displayed during
user input.

• LABELint: This argument, which is optional, indicates a label that might be
displayed beside the user prompt (e.g., "Username?") for variable int.

• NAMEint: If this argument is not present for a given int, then no value is
required for this variable - presumably LABELint is informational. If NAMEint is
present, it gives the name of the variable to use when the handler submits the
value. For example, suppose the handler is called with arguments TYPE2 as "text",
LABEL2 as "Login:", and NAME2 as "AUTH_PROMPT_VAR2". This asks the handler to
prompt for text input labeled "Login:". If the user submits the value "Auggie",
then included with the arguments to service there should be a variable named
AUTH_PROMPT_VAR2 with the value "Auggie".

Any other arguments to the handler should be forwarded to service verbatim. Such
arguments include DACS_VERSION, DACS_JURISDICTION, DACS_BROWSER, and
ENABLE_AUTH_HANDLERS.

Note
For testing purposes, it may be helpful to set PAM_HANDLER_URL to dacs_prenv,
which will display the arguments passed to the handler and other context. The DACS
distribution includes an example handler, html/handlers/dacs_pam_handler.

If an HTML form is emitted, its appearance can be customized somewhat through the
default stylesheet local_pam_authenticate.css[157]. The content of the generated web
page can be customized through the local_pam_authenticate VFS item type. The following
items relative to that item type are emitted if they exist:

• header: Initial HTML to emit instead of the default.

• prologue: HTML to emit immediately after the header.

• instructions: HTML to emit immediately after the prologue and before the form.

• form: Additional HTML to emit within the form.

• epilogue: HTML to emit immediately after the form.

• trailer: Final HTML to emit instead of the default.

For example, consider the configuration directive:

VFS "[local_pam_authenticate]dacs-fs:${Conf::DACS_HOME}/pam_auth"

Here, pam_auth is the directory ${Conf::DACS_HOME}/pam_auth. If files named header and
trailer exist in that directory, they are expected to contain the initial and final
HTML content, respectively. These files consist of text and HTML markup but are not
complete HTML documents.

Customization of the HTML form is possible using configuration variables:

• prompt_submit_label: the text label to put in the form's submit button.

For example, the submit button's text can be specified using the directive:

EVAL ${Conf::prompt_submit_label} = " Continue "

Tip
A built-in version of this module can be selected by using the URL
local_pam_authenticate or just pam.

local_passwd_authenticate
The local_passwd_authenticate module provides support for DACS identities, strictly
private to DACS, through password-protected accounts (similar to what Apache's
mod_auth[86] and mod_auth_dbm[88] modules do, along with the htpasswd(1)[89] utility).
A secure hash of a password is stored rather than the plaintext password itself.
Several hashing methods are available (see PASSWORD_DIGEST[158]).

The local_passwd_authenticate module performs authentication by consulting the
USERNAME and PASSWORD parameters and comparing them to the information previously
stored by the administrator.

Security
This module always requires the PASSWORD argument and will not accept the empty
string as a password value (even if that actually is the password). Use
local_simple_authenticate[67] for password-less accounts.

The STYLE should be configured as password for this module.

The dacspasswd(1)[159] utility is used to manage these accounts. The item type is
"passwds".

The following example configuration, which reflects typical usage, maintains user and
password information in a plain text file named /usr/local/dacs/federations/passwd.

VFS "[passwds]dacs-kwv-fs:/usr/local/dacs/federations/passwd"

There are no directives or options specific to this module.

Note
The name "local_passwd_authenticate" may be a little confusing because there are
other modules that implement some form of password-based authentication. This
module might more appropriately be called "local_dacspasswd_authenticate".

Tip
A built-in version of this module can be selected by using the URL
local_passwd_authenticate or just passwd.

local_simple_authenticate
The local_simple_authenticate module supports DACS identities, strictly private to
DACS, through accounts that are not password-protected. The local_simple_authenticate
module performs authentication by looking up an account named by the USERNAME
argument. In typical use, the username will be an email address, account or membership
number, or random character string.

Security
This form of authentication is inherently insecure because no password is
provided. It is only appropriate when the consequences of a valid account name
being guessed or misappropriated are of little concern, such as for restricted
guest accounts. Administrators should not assume that using difficult-to-guess
account names with this module offers much security. Keep in mind that depending
on the larger context of how these identities are used, these usernames may be
publicly visible.

The STYLE should be configured as simple for this module.

The dacspasswd(1)[159] utility is used to manage these accounts. The item type is
"simple".

The following example configuration, which reflects typical usage, maintains user
account information in a plain text file named
/usr/local/dacs/federations/simple_accounts.

VFS "[simple]dacs-kwv-fs:/usr/local/dacs/federations/simple_accounts"

Note
Although it is possible to combine password-protected accounts and password-less
accounts in the same VFS object (i.e., with the item types passwds and simple
pointing to the same file or database), putting them in separate objects is
recommended.

There are no directives or options specific to this module.

Tip
A built-in version of this module can be selected by using the URL
local_simple_authenticate or just simple.

local_tgma_authenticate
Experimental. The local_tgma_authenticate module, together with a TGMA server and
client validator software, implements strong, interactive mutual authentication
without the user having to input a password. The local_tgma_authenticate module
supports DACS identities that are strictly private to DACS.

The user begins the authentication procedure by using a simple sign-on page to submit
an identity (USERNAME and JURISDICTION). A password is not normally required. A
special web-based utility returns a new web page to the user that displays
instructions and another form that the user must submit when she is ready to complete
the procedure. Next, and within a configurable window of time, the user must prove his
ownership of the identity by executing a secure validation protocol. The validation
protocol is conducted from a device, such as a smart phone or tablet, which runs the
custom validator app and has been configured with account information for the user's
identity at the jurisdiction.

This authentication module sends an authentication request message to a TGMA server.
The TGMA server executes an authentication protocol with a user's validator and
returns the result to the module. The TGMA server is a light-weight daemon that may
serve one or more jurisdictions. The mutual authentication protocol, based on Secure
Remote Password authentication (RFC 2945[160], RFC 5054[161]), verifies the user's
identity using account information available to the module, TGMA server, and the
validator. The user's validator confirms the identity of the TGMA server, and
indirectly, the jurisdiction. Communication between the TGMA server and the module may
use TCP, SSL, or UDP, depending on configuration. Likewise, communication between the
TGMA server and a validator may also use TCP, SSL, or UDP. Choice of the networking
protocol will depend on security, performance, and connectivity dependencies. An
instance of the TGMA server must have network connectivity with both users' validator
devices and instances of this authentication module. In a larger organization it will
likely run on a firewall or DMZ-located server.

The STYLE should be configured as tgma for this module.

local_token_authenticate
This module works in concert with the dacstoken(1)[162] utility to support one-time
passwords. Two-factor authentication, a strong authentication method, is supported by
combining hardware token-based one-time passwords ("something you have") with a PIN (a
password, "something you know"). Software-based clients may also be used. The
implementation follows RFC 4226[163], which has been adopted by OATH[164], and other
standards. Please refer to dacstoken(1)[162] for complete details.

The STYLE should be configured as password for this module.

In addition to the usual USERNAME argument, the module requires the PASSWORD argument
to be the next one-time password (e.g., the value produced by the user's hardware
token). If the user's DACS account has a PIN associated with it, the PIN must be
passed as the AUXILIARY argument. The PIN referred to here is the one managed by
dacstoken, not a PIN that may be entered into the token device to unlock it.

One-time password generation depends on a secret that is shared between the client and
DACS, and a non-repeating value that may be based on synchronized counters or clocks.
The client's token can become unsynchronized with the server's state. This can happen
for many reasons, such as if a password is generated by the device but not used, if a
password or PIN is typed incorrectly, or because of a configuration error. The method
can tolerate a configurable deviation of the client's token from the server's state;
that is, provided the client's password falls within a window of N from the one
expected by DACS, DACS will accept the client's token. For counter-based tokens, only
the "forward" side of the window is examined, so DACS can "catch up" to the client.

If the user's password does not fall within the window, it is deemed to have become
unsynchronized with local_token_authenticate and authentication will fail. The user
can attempt to resynchronize by entering a sequence of passwords as PASSWORD, using a
comma to separate them. Three consecutive, valid passwords are required (this number
can be configured at build time). If the account has a PIN, it must be provided to
enable synchronization. If synchronization succeeds, the user's account information is
corrected and the module also reports successful authentication. If synchronization
fails, the module also fails and a DACS administrator must be contacted to
resynchronize the token.

Note
The token value must be entered exactly as it is displayed on the token. Leading
zeroes must be typed, for example, and no spaces or punctuation are allowed.
Whenever authentication fails, the user must obtain a new password from the token.

The following OPTION directive value is understood:

ACCEPT_WINDOW (Optional1)
The (non-negative) size of the acceptance window for one-time passwords,
overriding the default. If the size is zero, DACS will only consider a match with
the expected password and will not try to match the user's password against
"nearby" passwords. With some modes of operation, only forward matches are
allowed.

Tip
A built-in version of this module can be selected by using the URL
local_token_authenticate or just token.

local_unix_authenticate
The local_unix_authenticate module implements native Unix username/password
authentication, allowing a user having a pre-existing Unix account to be authenticated
by DACS using the username and password for that account. Normally, the user's hashed
password is compared to the string obtained by hashing the PASSWORD argument. But
because some platforms do not make stored passwords available to applications (most
notably macOS), a second algorithm can be used; if it is enabled and the pam(3)[165]
library is available, a simple PAM policy is used to validate the plaintext password
provided.

In the password comparison algorithm, the getpwnam(3)[166] library function is passed
the USERNAME parameter given to dacs_authenticate. It can be configured for systems
with or without shadow passwords. On some Unix systems, when the yp(8)[167] password
database is enabled, the getpwnam(3)[166] function will use the YP map "passwd.byname"
if the requested password entry is not found in the local database. If the account
information is obtained, the PASSWORD parameter is validated.

In the PAM-based algorithm, the USERNAME and PASSWORD parameters given to
dacs_authenticate are passed to the PAM module (e.g., pam_unix(8)[152]) that has been
configured by an administrator. This method is separate and much simpler than what is
provided by local_pam_authenticate[39]. To help protect against misconfiguration, any
unexpected behaviour by PAM will cause authentication to fail. For example, the
password prompt string produced by PAM must match "Password:", ignoring trailing
spaces; currently, this default can only be changed at compile time.

The STYLE should be configured as password for this module.

The following OPTION directive values are understood:

PAM_SERVICE (Optional1)
This is the name of the PAM service policy to use. If unspecified, a compile-time
default (DEFAULT_PAM_SERVICE, set to "dacs-unix-auth") is used. The name of the
service policy will usually identify a file (for instance,
/etc/pam.d/dacs-unix-auth) that might simply contain something like:

auth required pam_unix.so no_warn

An existing policy file may be available or it may be necessary to create one. On
macOS, for example, /etc/pam.d/chkpasswd contains the following entry, which is
sufficient for password validation:

auth required pam_opendirectory.so

To use that file with this module, the following DACS configuration directive
would be placed in the appropriate Auth clause:

OPTION "PAM_SERVICE=chkpasswd"

See pam_start(3)[148] and pam.conf(5)[168].

Depending on the operating system, PAM modules might be found in /usr/lib,
/usr/lib/pam, or /lib/security.

It is possible to configure the PAM service policy to use a password-based "auth"
facility other than the Unix password module, but do so with care.

USE_PAM (Optional1)
If "yes" or "on", only use the PAM-based algorithm, if "no" or "off", do not use
the PAM-based algorithm, and if "both", "try", or unspecified, use the PAM-based
method only if the password comparison algorithm is unavailable. These string
values are case insensitive.

Tip
A built-in version of this module can be selected by using the URL
local_unix_authenticate or just unix. If the built-in version is used,
dacs_authenticate must be setuid root, and if the web-based version is used,
local_unix_authenticate must be setuid root, so that the shadow password file can
be read and/or the PAM module used. Authentication using this module will fail if
it does not execute with sufficient priviledges.

Note
On platforms where encrypted passwords are unavailable, such as macOS,
authentication will always fail unless the PAM-based algorithm is available and
enabled.

Roles
Each user authenticated by DACS may be associated with one or more roles. The syntax of
roles and role descriptors[14] is described elsewhere. Role-based group membership is
discussed in dacs.groups(5)[169]. Configuration of a Roles clause is optional and if none
are specified, an empty role descriptor string will be used. If more than one Roles clause
is configured, their role strings are concatenated (duplicates are not removed). If a
roles service fails, it is treated as if it returned no roles and processing continues
normally.

Like authentication, a modular mechanism is used to find the roles with which a user is
associated. A roles module, analogous to an authentication module, can be called by
dacs_authenticate to return roles. A roles service returns a roles_reply element (see
roles_reply.dtd[170]).

Each Roles element must have 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 id attribute values must be unique (case-sensitively) within the
clause's Jurisdiction section.

Note
A maximum limit is imposed on the length of a role descriptor string. Please refer to
the ROLE_STRING_MAX_LENGTH[171] directive.

Roles Clause Directives
The roles directives are largely analogous to the authentication directives.

When evaluation of the Roles clauses begins, several variables are available in the Auth
namespace to reflect the outcome of authentication. These variables may be useful when
determining the user's roles: DACS_USERNAME, DACS_IDENTITY, DACS_JURISDICTION, and
DACS_VERSION.

Roles Clause Directives Index:

1. EXIT* (Optional1)

2. EXPR (Optional1)

3. INIT* (Optional1)

4. OPTION (Optional)

5. OPTION* (Optional)

6. PREDICATE (Optional1)

7. URL (Optional1)

8. URL* (Optional1)

URL (Optional1)
URL* (Optional1)
Exactly one of these two directives must be specified, unless EXPR is specified, in
which case neither URL nor URL* may be specified. These directives specify the URL to
be used to invoke the roles module (or is the name of a built-in module). The
difference between the two directives is that the value of URL* is an expression that
is evaluated to determine the URL to be used; this evaluation occurs immediately
before the module is invoked.

INIT* (Optional1)
An expression can be specified that is to be evaluated immediately prior to the URL*
and EXPR expressions, all of which are evaluated before a module is invoked.

EXIT* (Optional1)
If authentication is successful, this expression is evaluated immediately after the
module is executed or EXPR evaluated.

EXPR (Optional1)
This directive gives an expression that is evaluated to obtain roles instead of
invoking a roles module. Please refer to Advanced Techniques.

OPTION (Optional)
Similar to the Auth clause's OPTION[50] directive, this is used to pass an argument to
the roles module. A given name may not be specified more than once within a particular
Roles clause. The Options namespace is initialized with DACS_USERNAME,
DACS_JURISDICTION, and DACS_VERSION variables. If these are specified by an OPTION,
the argument ordinarily used will be overridden.

For example:

OPTION "PASSWORD=bobo"

causes PASSWORD=bobo to be passed as a POST method parameter.

PREDICATE (Optional1)
If provided, this expression is evaluated before any other roles module processing is
done. If there is an evaluation error or it returns False (zero or the empty string),
processing of the clause terminates and the next Roles clause, if any, is processed.
Otherwise, processing of the clause continues normally.

Roles Clause Control Flow
If authentication succeeds, Roles clauses are processed in which they appear, but only if
set_roles[70] has not been specified for some authentication module's STYLE.

A Roles clause is processed in a sequence of steps, and with various hooks to provide
fine-grained control. Before the first clause is examined, the variables
${Auth::CURRENT_ROLES} and ${Auth::LAST_ROLES} are initialized to the role string, if any,
obtained during authentication module processing. Processing of each Roles clause proceeds
as follows:

1. If the clause has a PREDICATE directive, it is evaluated in the current context. If
the value is not True the clause is not evaluated further. No variables are updated.
If the expression was invalid, processing of roles is terminated.

2. If the clause has an INIT* directive, it is evaluated; if an error occurs, processing
of roles is terminated.

3. If the clause has a URL* directive, it is evaluated to obtain the URL of the DACS
roles service to be invoked; if an error occurs, processing of roles is terminated. If
the clause has an EXPR* directive, it is evaluated to obtain the role string; if an
error occurs during evaluation it is treated as if the expression returned the empty
string.

4. If a roles service has been specified, it is invoked. If an error occurs, roles
processing continues as if the module returned the empty string for the role string.

5. The variable ${Auth::LAST_ROLES} is set to the roles string returned by the module or
expression.

6. If the clause has an EXIT* directive, it is evaluated; if an error occurs, processing
of roles is terminated. The value of ${Auth::LAST_ROLES} becomes the role string
returned by the clause.

7. The role string returned by the clause is appended to the variable
${Auth::CURRENT_ROLES}.

The value of ${Auth::CURRENT_ROLES} when the last module has been processed is the roles
string that will be used in the generated credentials.

Tip
Some roles modules are available as built-in components of dacs_authenticate. These
modules are identified by specific relative URLs; a module's description will provide
its built-in name when this capability is available. The built-in capability will
automatically be provided if the module has been enabled at build-time. The same
applies for dacsauth.

Although it will be more efficient (and possibly more secure) to use a built-in
module, they are executed on the same host as dacs_authenticate (thereby giving up
some flexibility), access control rules are not applied to them (other than the one
for dacs_authenticate), and dacs_authenticate may need to be executed setuid (probably
as root) or setgid (as www, for example) so that it can access password files.

Roles Modules
If and only if authentication succeeds, DACS can request the user's role descriptor from
the jurisdiction. Roles modules are always invoked using the POST method and are passed
the following arguments:

DACS_USERNAME
The username component of the user's DACS identity.

DACS_JURISDICTION
The name of the jurisdiction that authenticated DACS_USERNAME.

DACS_VERSION
The DACS_VERSION_NUMBER for this version of dacs_authenticate.

OPTION directives
For each OPTION directive[172] or OPTION* directive[173] in the Roles section being
processed, the variable name and its value are passed.
Any of the standard web service arguments will also be accepted; anything else will be
ignored.

Roles modules return an roles_reply.dtd[170] document to dacs_authenticate.

Note
Although there is a roles module for obtaining LDAP or ADS roles, you may also get
them by authenticating through local_ldap_authenticate[49] or by using a Roles clause
with an appropriate EXPR directive.

Roles Module Index:

1. local_roles: Private DACS roles

2. local_ldap_roles: Roles imported from an LDAP/ADS directory

3. local_unix_roles: Roles imported from Unix group membership

local_roles
This roles service consults a private list to obtain a username-to-roles mapping using
DACS virtual storage (the item type is "roles"). The following example configuration,
which reflects typical usage, maintains mappings in a plain text file named
/usr/local/dacs/federations/roles.

VFS "[roles]dacs-kwv-fs:/usr/local/dacs/federations/roles"

The file /usr/local/dacs/federations/roles might look something like this:

admin:dacs,admin
rick:metalogic,guests
bobo:staff,users
auggie:staff,users

Here, user auggie is associated with the roles staff and users.

Tip
A built-in version of this module can be selected by using the URL local_roles or
just roles.

local_ldap_roles
This roles service returns roles derived from the attributes of a user's LDAP/ADS
directory entry. This module is based on local_ldap_authenticate[49]; please consult
the description and examples presented with that authentication module for additional
information.

Note
The user need not have been authenticated by LDAP/ADS for this module to be used.
For example, the user can be authenticated on a Unix system but his roles can come
from LDAP/ADS.

The following configuration directives are recognized by this module. They function
identically to the directives of the same name used by local_ldap_authenticate[49], so
for the most part their descriptions will not be repeated here.

Note
These module directives must be passed using either OPTION[172] or OPTION*[173]
directives. Ensure that the option value is properly quoted.

LDAP_BIND_METHOD (Required1-C)
This tells the module how to find the user's entry in the directory.

LDAP_USERNAME_URL (Optional1)
LDAP_USERNAME_URL* (Optional1)
With the direct method, one of these options is used to name the user's entry as a
URI.

LDAP_ADMIN_URL (Required1-C)
If the indirect method is used, this option is required. This value is a URI like
LDAP_USERNAME_URL except that it identifies the LDAP administrator within the
directory.

LDAP_ADMIN_PASSWORD (Optional1)
This is the password for the LDAP administrator account that corresponds to
LDAP_ADMIN_URL.

LDAP_SEARCH_ROOT_DN (Required1-C)
This is the root DN at which the indirect method should begin searching for user
entries.

LDAP_SEARCH_FILTER (Required1-C)
LDAP_SEARCH_FILTER* (Required1-C)
If the indirect method is used, either this option or LDAP_SEARCH_FILTER* (but not
both) must be configured. This search filter is used to select the unique
directory entry that corresponds to this user. The LDAP_SEARCH_FILTER* option is
exactly like LDAP_SEARCH_FILTER except that it is evaluated just before it is
used, allowing various elements of the execution context to appear in the string.
The DACS username obtained from the preceding authentication phase can be
referenced as ${Args::DACS_USERNAME}.

LDAP_USERNAME_EXPR* (Optional1)
This option is evaluated to yield a username that can be referenced by the
LDAP_ROLES_SELECTOR* option as ${LDAP::USERNAME}.

LDAP_ROLES_SELECTOR* (Optional)
Each occurrence of this directive specifies an expression that is evaluated by
iterating through each attribute of the entry and making the attribute name
(${LDAP::attrname}) and its value (${LDAP::attrvalue}) available. All of the
entry's attribute names and values are made available within the LDAP namespace.
If the result of the expression is a valid role string (which excludes the empty
string, ""), it is added to the list of roles.

Here is an example that binds to the directory on x.example.com as the administrator,
searches for the entry for the account of the authenticated user, and assigns the user
a role from the attribute value of each memberOf attribute in the entry:

<Roles id="ldap_roles">
URL "http://example.com/cgi-bin/dacs/local_ldap_roles"
OPTION "LDAP_BIND_METHOD=indirect"
OPTION \
'LDAP_ADMIN_URL="ldap://x.example.com/CN=Administrator,CN=Users,DC=example,DC=com"'
OPTION 'LDAP_ADMIN_PASSWORD="secretpassword"'

OPTION 'LDAP_SEARCH_ROOT_DN="cn=Users,dc=example,dc=com"'
OPTION 'LDAP_SEARCH_FILTER*=\'"(sAMAccountName=${Args::DACS_USERNAME})"\''

OPTION 'LDAP_ROLES_SELECTOR*=\'"${LDAP::attrname}" eq "memberOf" \
? strtr(ldap(rdn_attrvalue, \
ldap(dn_index, "${LDAP::attrvalue}", 1)), " ", "_") \
: ""\''
</Roles>

For example, the resulting role string might look like:

DnsAdmins,Print_Operators,Domain_Admins,Administrators

local_unix_roles
This roles service returns the Unix group membership associated with an authenticated
username; that it, the resulting list of roles is the same as would be obtained if the
user ran the Unix groups(1)[174].

Note
The user need not have been authenticated as this username on the Unix system
where this service is run.

Tip
A built-in version of this module can be selected by using the URL
local_unix_roles or just unix.

Related Services
The dacs_current_credentials(8)[35] web service displays elements of each set of
credentials sent with the request. The dacs_signout(8)[175] service is typically called
from a browser to cause one or more cookies (each representing a DACS identity) to be
deleted. Cookies are automatically deleted when a browser terminates, but it is sometimes
useful to explicitly logoff.

DIAGNOSTICS

       The program exits 0 if everything was fine, 1 if an error occurred.

NOTES

       A separate but similar mechanism called "affiliated DACS federations" supports
       cross-federation single sign-on; see dacs_auth_transfer(8)[8].

       dacs_authenticate could be modified to temporarily disable an account after some number of
       unsuccessful login attempts over a certain time period. The flip side of such a feature is
       that it could be used in a denial of service attack. Rather than disabling an account, a
       designated administrator might receive an email notification or a console message might be
       logged.

       It might be worthwhile to include a rule-based mechanism, called after the user has been
       identified but before credentials are returned, to decide whether authentication should be
       permitted. This might be used, for example, to restrict a particular user to login from a
       specified IP address or range of addresses, or limit the time of day at which login is
       allowed.

BUGS

       It would be nice to provide assistance to programs that generate login pages. Composing
       modules should be easier, to make multi-factor authentication more accessible.

AUTHOR

       Distributed Systems Software (www.dss.ca[178])

COPYING

       Copyright2003-2016 Distributed Systems Software. See the LICENSE[179] file that
       accompanies the distribution for licensing information.

NOTES

        1. dacsoptions
           http://dacs.dss.ca/man/dacs.1.html#dacsoptions

        2. dacs.conf(5)
           http://dacs.dss.ca/man/dacs.conf.5.html

        3. dacs.exprs(5)
           http://dacs.dss.ca/man/dacs.exprs.5.html

        4. html/examples
           http://dacs.dss.ca/man//examples

        5. HTTP Authentication
           http://dacs.dss.ca/man/dacs_acs.8.html#http_authentication

        6. dacsauth(1)
           http://dacs.dss.ca/man/dacsauth.1.html

        7. dacs_auth_agent(8)
           http://dacs.dss.ca/man/dacs_auth_agent.8.html

        8. dacs_auth_transfer(8)
           http://dacs.dss.ca/man/dacs_auth_transfer.8.html

        9. dacscookie(1)
           http://dacs.dss.ca/man/dacscookie.1.html

       10. Auth clause
           http://dacs.dss.ca/man/#auth_clause

       11. CONTROL
           http://dacs.dss.ca/man/#CONTROL

       12. username
           http://dacs.dss.ca/man/dacs.1.html#dacs_identity

       13. dacs.acls(5)
           http://dacs.dss.ca/man/dacs.acls.5.html#revocation_list

       14. dacs(1)
           http://dacs.dss.ca/man/dacs.1.html#naming

       15. credentials.dtd
           http://dacs.dss.ca/man/../dtd-xsd/credentials.dtd

       16. VERIFY_IP
           http://dacs.dss.ca/man/dacs.conf.5.html#VERIFY_IP

       17. natd(8)
           http://www.freebsd.org/cgi/man.cgi?query=natd&apropos=0&sektion=8&manpath=FreeBSD+10.1-RELEASE&format=html

       18. VERIFY_UA
           http://dacs.dss.ca/man/dacs.conf.5.html#VERIFY_UA

       19. AUTH_CREDENTIALS_DEFAULT_LIFETIME_SECS
           http://dacs.dss.ca/man/dacs.conf.5.html#AUTH_CREDENTIALS_DEFAULT_LIFETIME_SECS

       20. Advanced Encryption Standard
           https://en.wikipedia.org/wiki/Advanced_Encryption_Standard

       21. Federal Information Processing Standard
           http://www.nist.gov/itl/fips.cfhttp://www.nist.gov/itl/fips.cfm

       22. FIPS 198
           http://csrc.nist.gov/publications/fips/fips198-1/FIPS-198-1_final.pdf

       23. RFC 2104
           http://www.rfc-editor.org/rfc/rfc2104.txt

       24. RFC 4635
           http://www.rfc-editor.org/rfc/rfc4635.txt

       25. RFC 4868
           http://www.rfc-editor.org/rfc/rfc4868.txt

       26. NIST
           http://www.nist.gov/

       27. FIPS 180-1
           http://www.itl.nist.gov/fipspubs/fip180-1.htm

       28. RFC 4634
           http://www.rfc-editor.org/rfc/rfc4634.txt

       29. RFC 6234
           http://www.rfc-editor.org/rfc/rfc6234.txt

       30. FIPS 180-4
           http://csrc.nist.gov/publications/fips/fips180-4/fips-180-4.pdf

       31. MD5 algorithm
           http://www.rfc-editor.org/rfc/rfc1321.txt

       32. Netscape HTTP Cookies Specification
           http://web.archive.org/web/20070805052634/http://wp.netscape.com/newsref/std/cookie_spec.html

       33. COOKIE_SYNTAX
           http://dacs.dss.ca/man/#COOKIE_SYNTAX

       34. COOKIE_NAME_TERMINATORS
           http://dacs.dss.ca/man/dacs.conf.5.html#COOKIE_NAME_TERMINATORS

       35. dacs_current_credentials(8)
           http://dacs.dss.ca/man/dacs_current_credentials.8.html

       36. COOKIE_PATH
           http://dacs.dss.ca/man/dacs.conf.5.html#COOKIE_PATH

       37. SECURE_MODE
           http://dacs.dss.ca/man/dacs.conf.5.html#SECURE_MODE

       38. standard CGI arguments
           http://dacs.dss.ca/man/dacs.services.8.html#standard_cgi_args

       39. local_pam_authenticate
           http://dacs.dss.ca/man/#local_pam_authenticate

       40. RFC 2109
           http://www.rfc-editor.org/rfc/rfc2109.txt

       41. RFC 2965
           http://www.rfc-editor.org/rfc/rfc2965.txt

       42. RFC 6265
           http://www.rfc-editor.org/rfc/rfc6265.txt

       43. RFC 2616
           http://www.rfc-editor.org/rfc/rfc2616.txt

       44. colons are used within cookie names
           http://dacs.dss.ca/man/#cookie-name-syntax

       45. dacs_acs(8)
           http://dacs.dss.ca/man/dacs_acs.8.html

       46. dacs_select_credentials(8)
           http://dacs.dss.ca/man/dacs_select_credentials.8.html

       47. strtr()
           http://dacs.dss.ca/man/dacs.exprs.5.html#strtr

       48. LDAP_USERNAME_URL
           http://dacs.dss.ca/man/#LDAP_USERNAME_URL

       49. local_ldap_authenticate
           http://dacs.dss.ca/man/#local_ldap_authenticate

       50. OPTION
           http://dacs.dss.ca/man/#OPTION

       51. dacs.conf(5)
           http://dacs.dss.ca/man/dacs.conf.5.html#auth_clause

       52. pam(3)
           http://www.freebsd.org/cgi/man.cgi?query=pam&apropos=0&sektion=0&manpath=FreeBSD+10.1-RELEASE&format=html

       53. X/Open Single Sign-On Service (XSSO) preliminary specification
           http://www.opengroup.org/pubs/catalog/p702.htm

       54. dacs.conf(5)
           http://dacs.dss.ca/man/dacs.conf.5.html#merging

       55. Authenticating Using an Expression
           http://dacs.dss.ca/man/#expr

       56. PASSWORD_CONSTRAINTS
           http://dacs.dss.ca/man/dacs.conf.5.html#PASSWORD_CONSTRAINTS

       57. LOG_FILTER
           http://dacs.dss.ca/man/dacs.conf.5.html#LOG_FILTER

       58. local_cas_authenticate
           http://dacs.dss.ca/man/#local_cas_authenticate

       59. Central Authentication Service (CAS)
           https://en.wikipedia.org/wiki/Central_Authentication_Service

       60. RFC 2617
           http://www.rfc-editor.org/rfc/rfc2617.txt

       61. local_apache_authenticate
           http://dacs.dss.ca/man/#local_apache_authenticate

       62. Information Card
           http://en.wikipedia.org/wiki/Information_Card

       63. dacsinfocard(1)
           http://dacs.dss.ca/man/dacsinfocard.1.html

       64. dacs_infocard(8)
           http://dacs.dss.ca/man/dacs_infocard.8.html

       65. dacs_managed_infocard(8)
           http://dacs.dss.ca/man/dacs_managed_infocard.8.html

       66. local_infocard_authenticate
           http://dacs.dss.ca/man/#local_infocard_authenticate

       67. local_simple_authenticate
           http://dacs.dss.ca/man/#local_simple_authenticate

       68. local_tgma_authenticate
           http://dacs.dss.ca/man/#local_tgma_authenticate

       69. add_roles
           http://dacs.dss.ca/man/#add_roles

       70. set_roles
           http://dacs.dss.ca/man/#set_roles

       71. dacs.exprs(5)
           http://dacs.dss.ca/man/dacs.exprs.5.html#variables

       72. AUTH_SUCCESS
           http://dacs.dss.ca/man/dacs.conf.5.html#AUTH_SUCCESS

       73. AUTH_SUCCESS_HANDLER
           http://dacs.dss.ca/man/dacs.conf.5.html#AUTH_SUCCESS_HANDLER

       74. AUTH_ERROR_HANDLER
           http://dacs.dss.ca/man/dacs.conf.5.html#AUTH_ERROR_HANDLER

       75. AUTH_FAIL_DELAY_SECS
           http://dacs.dss.ca/man/dacs.conf.5.html#AUTH_FAIL_DELAY_SECS

       76. DACS_AUTH_SUCCESS_HANDLER
           http://dacs.dss.ca/man/#DACS_AUTH_SUCCESS_HANDLER

       77. ENABLE_AUTH_HANDLERS
           http://dacs.dss.ca/man/#ENABLE_AUTH_HANDLERS

       78. dacs_prenv(8)
           http://dacs.dss.ca/man/dacs_prenv.8.html

       79. Environment variables
           http://httpd.apache.org/docs-2.2/mod/mod_ssl.html#envvars

       80. mod_ssl
           http://httpd.apache.org/docs-2.2/mod/mod_ssl.html

       81. dacs.services(8)
           http://dacs.dss.ca/man/dacs.services.8.html#FORMAT

       82. dacs_auth_reply.dtd
           http://dacs.dss.ca/man/../dtd-xsd/dacs_auth_reply.dtd

       83. dacs_current_credentials.dtd
           http://dacs.dss.ca/man/../dtd-xsd/dacs_current_credentials.dtd

       84. auth_reply.dtd
           http://dacs.dss.ca/man/../dtd-xsd/auth_reply.dtd

       85. dacs.install(7)
           http://dacs.dss.ca/man//man/dacs.install.7.html

       86. mod_auth
           http://httpd.apache.org/docs-2.2/mod/mod_auth.html

       87. mod_auth_digest
           http://httpd.apache.org/docs-2.2/mod/mod_auth_digest.html

       88. mod_auth_dbm
           http://httpd.apache.org/docs-2.2/mod/mod_auth_dbm.html

       89. htpasswd(1)
           http://httpd.apache.org/docs/2.2/programs/htpasswd.html

       90. htdigest(1)
           http://httpd.apache.org/docs/2.2/programs/htdigest.html

       91. htdbm(1)
           http://httpd.apache.org/docs/2.2/programs/htdbm.html

       92. local_native_authenticate
           http://dacs.dss.ca/man/#local_native_authenticate

       93. Central Authentication Service (CAS)
           http://www.jasig.org/cas

       94. CAS 2.0 Protocol
           http://www.jasig.org/cas/protocol

       95. OpenID
           http://openid.net/

       96. STYLE
           http://dacs.dss.ca/man/#STYLE

       97. SSLVerifyClient
           http://httpd.apache.org/docs-2.2/mod/mod_ssl.html#sslverifyclient

       98. SSLRequire
           http://httpd.apache.org/docs-2.2/mod/mod_ssl.html#sslrequire

       99. OpenSSL
           http://www.openssl.org

       00. SSLOptions
           http://httpd.apache.org/docs-2.2/mod/mod_ssl.html#ssloptions

       01. dacsgrid(1)
           http://dacs.dss.ca/man/dacsgrid.1.html

       02. Google
           http://www.google.com

       03. account authentication
           http://code.google.com/apis/accounts/AuthForInstalledApps.html

       04. eBay
           http://developer.ebay.com/developercenter/rest/

       05. Yahoo!
           http://developer.yahoo.com/auth/

       06. announced
           http://blogs.msdn.com/b/card/archive/2011/02/15/beyond-windows-cardspace.aspx

       07. CardSpace
           http://en.wikipedia.org/wiki/Windows_CardSpace

       08. Windows 8
           http://en.wikipedia.org/wiki/List_of_features_removed_in_Windows_8

       09. On the Demise of CardSpace
           http://upon2020.com/blog/2011/03/on-the-demise-of-cardspace/

       10. Open Cardspace opportunity
           http://blogs.law.harvard.edu/doc/2011/02/16/open-cardspace-opportunity/

       11. Personal Reflections on the CardSpace Journey
           http://self-issued.info/?p=458

       12. From CardSpace to Verified Claims
           http://www.identityblog.com/?p=1164

       13. Change will come: the present is untenable
           http://www.identityblog.com/?p=1165

       14. The Clay Feet of Giants?
           http://www.identityblog.com/?p=1167

       15. RIP, Windows CardSpace. Hello, U-Prove
           http://www.zdnet.com/blog/microsoft/rip-windows-cardspace-hello-u-prove/8717

       16. U-Prove
           http://research.microsoft.com/en-us/projects/u-prove/

       17. Identity Selector Interoperability Profile (ISIP) 1.5
           http://download.microsoft.com/download/1/1/a/11ac6505-e4c0-4e05-987c-6f1d31855cd2/Identity_Selector_Interoperability_Profile_V1.5.pdf

       18. role descriptor string
           http://dacs.dss.ca/man/dacs.1.html#roles

       19. dacs_infocard(8)
           http://dacs.dss.ca/man/dacs_infocard.8.html#about_claims

       20. expression-based authentication style
           http://dacs.dss.ca/man//man/dacs_authenticate.8.html#expr

       21. dacs_managed_infocard(8)
           http://dacs.dss.ca/man//man/dacs_managed_infocard.8.html

       22. dacs.conf(5)
           http://dacs.dss.ca/man//man/dacs.conf.5.html#INFOCARD_prefixed

       23. dacs_mex(8)
           http://dacs.dss.ca/man//man/dacs_mex.8.html

       24. dacs_sts(8)
           http://dacs.dss.ca/man//man/dacs_sts.8.html

       25. Using InfoCards With DACS
           http://dacs.dss.ca/man/using-infocards-with-dacs.html

       26. Identity Selector Interoperability Profile specification and companion guides
           http://www.microsoft.com/downloads/details.aspx?FamilyID=b94817fc-3991-4dd0-8e85-b73e626f6764&DisplayLang=en

       27. Introducing Windows CardSpace
           http://msdn.microsoft.com/en-us/library/aa480189.aspx

       28. RFC 2251
           http://www.faqs.org/rfcs/rfc2251.html

       29. RFC 2252
           http://www.faqs.org/rfcs/rfc2252.html

       30. RFC 2253
           http://www.faqs.org/rfcs/rfc2253.html

       31. RFC 3377
           http://www.faqs.org/rfcs/rfc3377.html

       32. Active Directory (ADS)
           http://www.microsoft.com/windows2000/technologies/directory/ad/default.asp

       33. OpenLDAP
           http://www.openldap.org

       34. ldap()
           http://dacs.dss.ca/man/dacs.exprs.5.html#ldap

       35. LDAP_USERNAME_URL*
           http://dacs.dss.ca/man/#LDAP_USERNAME_URL*

       36. RFC 2396
           http://www.faqs.org/rfcs/rfc2396.html

       37. RFC 3986
           http://www.rfc-editor.org/rfc/rfc3986.txt

       38. ldapsearch(1)
           http://www.openldap.org/software/man.cgi?query=ldapsearch&apropos=0&sektion=0&manpath=OpenLDAP+2.4-Release&format=html

       39. autologin(8)
           http://dacs.dss.ca/man/autologin.8.html

       40. 1
           http://curl.haxx.se/rfc/ntlm.html

       41. 2
           http://msdn.microsoft.com/en-us/library/cc236621%28PROT.10%29.aspx

       42. Samba
           http://www.samba.org

       43. NTLM authentication
           https://en.wikipedia.org/wiki/NTLM

       44. have been identified
           http://support.microsoft.com/kb/2793313

       45. smbclient(1)
           http://www.samba.org/samba/docs/man/manpages-3/smbclient.1.html

       46. dacs(1)
           http://dacs.dss.ca/man/dacs.1.html

       47. dacscheck(1)
           http://dacs.dss.ca/man/dacscheck.1.html

       48. pam_start(3)
           http://www.freebsd.org/cgi/man.cgi?query=pam_start&apropos=0&sektion=3&manpath=FreeBSD+10.1-RELEASE&format=html

       49. GNU/Linux
           http://www.kernel.org/pub/linux/libs/pam/modules.html

       50. FreeBSD
           http://www.freebsd.org/doc/en_US.ISO8859-1/articles/pam/pam-freebsd-modules.html

       51. macOS
           https://developer.apple.com/library/mac/documentation/Darwin/Reference/ManPages/man3/pam.3.html

       52. pam_unix(8)
           http://www.freebsd.org/cgi/man.cgi?query=pam_unix&apropos=0&sektion=8&manpath=FreeBSD+10.1-RELEASE&format=html

       53. local_unix_authenticate
           http://dacs.dss.ca/man/#local_unix_authenticate

       54. ATM
           https://en.wikipedia.org/wiki/Cash_machine

       55. pamd(8)
           http://dacs.dss.ca/man/pamd.8.html

       56. dacs_url
           http://dacs.dss.ca/man/dacs.groups.5.html#group_syntax

       57. local_pam_authenticate.css
           http://dacs.dss.ca/man//css/local_pam_authenticate.css

       58. PASSWORD_DIGEST
           http://dacs.dss.ca/man/dacs.conf.5.html#PASSWORD_DIGEST

       59. dacspasswd(1)
           http://dacs.dss.ca/man/dacspasswd.1.html

       60. RFC 2945
           http://www.rfc-editor.org/rfc/rfc2945.txt

       61. RFC 5054
           http://www.rfc-editor.org/rfc/rfc5054.txt

       62. dacstoken(1)
           http://dacs.dss.ca/man/dacstoken.1.html

       63. RFC 4226
           http://www.rfc-editor.org/rfc/rfc4226.txt

       64. OATH
           http://www.openauthentication.org

       65. pam(3)
           http://www.freebsd.org/cgi/man.cgi?query=pam&apropos=0&sekti
           on=0&manpath=FreeBSD+10.1-RELEASE&format=html

       66. getpwnam(3)
           http://www.freebsd.org/cgi/man.cgi?query=getpwnam&apropos=0&sektion=3&manpath=FreeBSD+10.1-RELEASE&format=html

       67. yp(8)
           http://www.freebsd.org/cgi/man.cgi?query=yp&apropos=0&sektion=8&manpath=FreeBSD+10.1-RELEASE&format=html

       68. pam.conf(5)
           http://www.freebsd.org/cgi/man.cgi?query=pam.conf&apropos=0&sektion=5&manpath=FreeBSD+10.1-RELEASE&format=html

       69. dacs.groups(5)
           http://dacs.dss.ca/man/dacs.groups.5.html

       70. roles_reply.dtd
           http://dacs.dss.ca/man/../dtd-xsd/roles_reply.dtd

       71. ROLE_STRING_MAX_LENGTH
           http://dacs.dss.ca/man/dacs.conf.5.html#ROLE_STRING_MAX_LENGTH

       72. OPTION directive
           http://dacs.dss.ca/man/#r_OPTION

       73. OPTION* directive
           http://dacs.dss.ca/man/#r_OPTION*

       74. groups(1)
           http://www.freebsd.org/cgi/man.cgi?query=groups&apropos=0&sektion=1&manpath=FreeBSD+10.1-RELEASE&format=html

       75. dacs_signout(8)
           http://dacs.dss.ca/man/dacs_signout.8.html

       76. dacscred(1)
           http://dacs.dss.ca/man/dacscred.1.html

       77. dacs_autologin_ssl(8)
           http://dacs.dss.ca/man/dacs_autologin_ssl.8.html

       78. www.dss.ca
           http://www.dss.ca

       79. LICENSE
           http://dacs.dss.ca/man/../misc/LICENSE

NAME

SYNOPSIS

DESCRIPTION

DIAGNOSTICS

NOTES

BUGS

SEE ALSO

AUTHOR

COPYING

NOTES