.\" Copyright (c) 2003-2012
.\" Distributed Systems Software. All rights reserved.
.\" See the file LICENSE for redistribution information.
.\" $Id: copyright-nr 2564 2012-03-02 00:17:08Z brachman $
'\" t
.\" Title: dacs_authenticate
.\" Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.79.1
.\" Date: 02/19/2019
.\" Manual: DACS Web Services Manual
.\" Source: DACS 1.4.40
.\" Language: English
.\"
.TH "DACS_AUTHENTICATE" "8" "02/19/2019" "DACS 1.4.40" "DACS Web Services Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
dacs_authenticate \- \fBDACS\fR authentication service
.SH "SYNOPSIS"
.HP \w'\fBdacs_authenticate\fR\ 'u
\fBdacs_authenticate\fR [\fI\m[blue]\fBdacsoptions\fR\m[]\&\s-2\u[1]\d\s+2\fR]
.SH "DESCRIPTION"
.PP
This web service is part of the
\fBDACS\fR
suite\&.
.PP
The
\fBdacs_authenticate\fR
web service is an authentication "driver" for
\fBDACS\fR\&. 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
\fBDACS\fR
user identity to the user and
roles modules
may be invoked to determine the roles with which the identity is associated;
\fBDACS\fR
credentials
are generated and returned to the user\&. The caller of
\fBdacs_authenticate\fR
can be redirected to a configured URL, called the
post\-authentication handler
(or just the
handler), depending on whether authentication fails or succeeds\&.
.PP
General
\fBDACS\fR
configuration directives are discussed in
\m[blue]\fBdacs\&.conf(5)\fR\m[]\&\s-2\u[2]\d\s+2\&. Configuration directives specific to authentication are described here\&.
.PP
\fBDACS\fR
expressions are described in
\m[blue]\fBdacs\&.exprs(5)\fR\m[]\&\s-2\u[3]\d\s+2\&.
.PP
\fBdacs_authenticate\fR
might be called from an HTML
form, directly through a link on a web page, indirectly by
\fBDACS\fR
\m[blue]\fBHTTP Authentication\fR\m[]\&\s-2\u[4]\d\s+2, or from middleware\&. See the distribution\*(Aqs
\m[blue]\fBhtml/examples\fR\m[]\&\s-2\u[5]\d\s+2
directory for examples of simple login pages\&.
.PP
Command line authentication functionality is provided by
\m[blue]\fBdacsauth(1)\fR\m[]\&\s-2\u[6]\d\s+2\&. Other authentication mechanisms are provided by
\m[blue]\fBdacs_auth_agent(8)\fR\m[]\&\s-2\u[7]\d\s+2,
\m[blue]\fBdacs_auth_transfer(8)\fR\m[]\&\s-2\u[8]\d\s+2, and
\m[blue]\fBdacscookie(1)\fR\m[]\&\s-2\u[9]\d\s+2\&.
.SS "Authentication"
.PP
Authentication is the procedure by which a claimed identity is confirmed\&. Following successful authentication,
\fBDACS\fR
credentials may be created that represent the identity\&. For maximum convenience and interoperability in a web environment,
\fBDACS\fR
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\&.
.PP
While
\fBdacs_authenticate\fR
provides powerful and flexible ways to combine and compose a variety of authentication methods, most
\fBDACS\fR
jurisdictions will configure only one method, or perhaps just a few methods, in simple ways\&.
.PP
To help integrate
\fBDACS\fR
seamlessly within a web site,
\fBdacs_authenticate\fR
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\&.
.PP
Authentication succeeds (and the user is
authenticated) if and only if:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
at least one
\m[blue]\fBAuth clause\fR\m[]\&\s-2\u[10]\d\s+2
has been configured,
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
the semantics of all
\m[blue]\fBCONTROL\fR\m[]\&\s-2\u[11]\d\s+2
directives satisfy the requirements for success,
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
the
\fBDACS\fR
\m[blue]\fBusername\fR\m[]\&\s-2\u[12]\d\s+2
arrived at is syntactically valid, and
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
the identity\*(Aqs access has not been revoked or denied (see
\m[blue]\fBdacs\&.acls(5)\fR\m[]\&\s-2\u[13]\d\s+2)\&.
.RE
.PP
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
\fBdacs_authenticate\fR
to terminate without issuing credentials and possibly without invoking a handler\&.
.PP
If a
\fBDACS\fR
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\&.
.PP
As an efficiency measure, the authentication architecture allows an authentication module to return roles\&.
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNames\fR
.RS 4
.PP
Please refer to
\m[blue]\fBdacs(1)\fR\m[]\&\s-2\u[14]\d\s+2
for details about naming, identities, and roles\&.
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBCredentials and Cookies\fR
.RS 4
.PP
\fBDACS\fR
credentials are cryptographically protected XML documents (\m[blue]\fBcredentials\&.dtd\fR\m[]\&\s-2\u[15]\d\s+2)\&. 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\&.
\fBDACS\fR
is careful to not produce log information or error messages that might benefit an attacker\&.
.PP
User agents and other software outside of
\fBDACS\fR
do not need to decrypt the credentials and do not possess the required encryption key\&.
.PP
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)\&.
.PP
\fBDACS\fR
does not verify that a user\*(Aqs browser is configured to accept cookies \- this is the responsibility of the
\fBDACS\fR
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
\fBDACS\fR
(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\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBSecurity\fR
.ps -1
.br
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
For
\fBDACS\fR
to operate securely, communication between a user (or middleware) and
\fBdacs_authenticate\fR, which may include information such as passwords,
\fImust only be transmitted over a secure connection (SSL/TLS)\fR\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Communication between
\fBdacs_authenticate\fR
(and
\fBdacsauth\fR) and an external (not built\-in) authentication module may include information such as passwords and therefore
\fIshould only be transmitted over a secure connection (SSL/TLS)\fR
or in a way that is not subject to eavesdropping or attack\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
For
\fBDACS\fR
to operate securely, regardless of how they are obtained,
\fBDACS\fR
credentials
\fImust only be transmitted over a secure connection (SSL/TLS) so that they cannot easily be captured and reused by an attacker\fR\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
It is unwise to configure both SSL/TLS and non\-SSL/TLS communication\&. Besides providing an avenue for attack, it may cause
\fBDACS\fR
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)\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
The apparent IP address of an authenticated user, as provided by the web server, is stored in credentials\&.
\fBDACS\fR
can be configured to consider credentials to be valid only for requests that come from that address (refer to the
\m[blue]\fBVERIFY_IP\fR\m[]\&\s-2\u[16]\d\s+2
configuration directive), making it more difficult for an attacker to replay captured credentials\&.
.sp
In some environments this constraint is a good idea, but in general it is of dubious value so enable it with care\&. For instance, 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 DHCP or dial\-up Internet access, a user might be issued credentials, reboot, and then be assigned a different IP address; 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
\m[blue]\fBnatd(8)\fR\m[]\&\s-2\u[17]\d\s+2
is used, so the check does not guarantee uniqueness\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Information associated with a user\*(Aqs 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
\m[blue]\fBVERIFY_UA\fR\m[]\&\s-2\u[18]\d\s+2
for details\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
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 honoured by
\fBDACS\fR\&. Refer to the
\m[blue]\fBAUTH_CREDENTIALS_DEFAULT_LIFETIME_SECS\fR\m[]\&\s-2\u[19]\d\s+2
configuration directive for details\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Passwords do not appear in any credentials and are not recorded by any
\fBDACS\fR
component once a user has been authenticated\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
It is forbidden to submit multiple credentials for the same identity to
\fBDACS\fR
and such a request will trigger an error\&.
.RE
.sp .5v
.RE
.PP
All
\fBDACS\fR
jurisdictions within the same federation share an algorithm and key to encrypt and decrypt credentials\&. The cryptographically secure, symmetric encryption function Rijndael (the
\m[blue]\fBAdvanced Encryption Standard\fR\m[]\&\s-2\u[20]\d\s+2
(AES) algorithm and
\m[blue]\fBFederal Information Processing Standard\fR\m[]\&\s-2\u[21]\d\s+2) is currently used\&. The same 128 bit key is used by all
\fBDACS\fR
jurisdictions\&.
AES
also supports 192 and 256 bit key lengths and either can be configured at build\-time\&.
.PP
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,
\m[blue]\fBFIPS 198\fR\m[]\&\s-2\u[22]\d\s+2,
\m[blue]\fBRFC 2104\fR\m[]\&\s-2\u[23]\d\s+2,
\m[blue]\fBRFC 4635\fR\m[]\&\s-2\u[24]\d\s+2,
\m[blue]\fBRFC 4868\fR\m[]\&\s-2\u[25]\d\s+2), is employed using the 160\-bit
\m[blue]\fBNIST\fR\m[]\&\s-2\u[26]\d\s+2
secure hash standard,
SHA\-1
(\m[blue]\fBFIPS 180\-1\fR\m[]\&\s-2\u[27]\d\s+2,
\m[blue]\fBRFC 4634\fR\m[]\&\s-2\u[28]\d\s+2,
\m[blue]\fBRFC 6234\fR\m[]\&\s-2\u[29]\d\s+2)\&. In addition to
SHA\-1,
SHA\-224,
SHA\-256,
SHA\-384, and
SHA\-512
(\m[blue]\fBFIPS 180\-4\fR\m[]\&\s-2\u[30]\d\s+2) can be used; they may be configured at build\-time\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBSecurity\fR
.ps -1
.br
.PP
\fBDACS\fR
can be configured to use the less secure but widely\-used and somewhat more efficient
\m[blue]\fBMD5 algorithm\fR\m[]\&\s-2\u[31]\d\s+2
instead, although it is deprecated and it will eventually be removed\&.
.sp .5v
.RE
.PP
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\&.
.PP
The
\m[blue]\fBNetscape HTTP Cookies Specification\fR\m[]\&\s-2\u[32]\d\s+2
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
\m[blue]\fB\fICOOKIE_SYNTAX\fR\fR\m[]\&\s-2\u[33]\d\s+2
argument can be used to request a different syntax\&. The Netscape format is as follows:
.sp
.if n \{\
.RS 4
.\}
.nf
Set\-Cookie: NAME=VALUE; expires=DATE; path=PATH; domain=DOMAIN_NAME; secure
.fi
.if n \{\
.RE
.\}
.PP
\fBDACS\fR
formulates these response headers as follows\&.
.PP
The
NAME
attribute of an authentication cookie returned to the user (e\&.g\&., by
\fBdacs_authenticate\fR) has the following default format:
.sp
.if n \{\
.RS 4
.\}
.nf
DACS:\fIfederation\-name\fR::[\fIjurisdiction\-name\fR]:[\fIusername\fR]
.fi
.if n \{\
.RE
.\}
.sp
where
\fIfederation\-name\fR
is the official name assigned to the federation for which the cookie is valid,
\fIjurisdiction\-name\fR
is the name of the authenticating jurisdiction, and
\fIusername\fR
is the authenticated name of the user\&. If the
\fIjurisdiction\-name\fR
is omitted, the
\fIusername\fR
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:
.sp
.if n \{\
.RS 4
.\}
.nf
DACS:EXAMPLE::METALOGIC:rick@example\&.com
.fi
.if n \{\
.RE
.\}
.PP
\fBDACS\fR
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\&.
.PP
The default format of the
NAME
attribute can be overridden through the
\m[blue]\fBCOOKIE_NAME_TERMINATORS\fR\m[]\&\s-2\u[34]\d\s+2
directive\&.
.PP
The
VALUE
attribute of a cookie is a printable text encoding of credentials\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBSecurity\fR
.ps -1
.br
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Although
\fBDACS\fR
performs validity tests on cookie names, middleware should not rely on cookie names for any purpose\&. An apparently valid
\fBDACS\fR
cookie can easily be crafted with any value\&. Also, an apparently legitimate cookie might convey expired or otherwise invalid credentials\&. Middleware should use
\m[blue]\fBdacs_current_credentials(8)\fR\m[]\&\s-2\u[35]\d\s+2
to validate an authentication cookie and not trust cookie names\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
No
expires
attribute is set; this will cause the cookie to be automatically deleted by a conforming browser when the user\*(Aqs 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\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
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
\fBDACS\fR\-wrapped service request or not\&. The
\m[blue]\fBCOOKIE_PATH\fR\m[]\&\s-2\u[36]\d\s+2
configuration directive can specify an alternative value\&. Using a more restricted path can potentially improve security\&. All of the jurisdiction\*(Aqs
\fBDACS\fR\-wrapped services must appear under that path, of course, or the cookie will not be sent; ideally, no non\-\fBDACS\fR
wrapped service would appear under that path\&.
.RE
.sp .5v
.RE
.PP
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\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBTip\fR
.ps -1
.br
.PP
The HTTP cookie specifications appear to say that a cookie having a
domain
attribute of
example\&.com
should
\fInot\fR
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
\fBDACS\fR
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\&.
.sp .5v
.RE
.PP
When operating securely (see the
\m[blue]\fBSECURE_MODE\fR\m[]\&\s-2\u[37]\d\s+2
directive in
\m[blue]\fBdacs\&.conf(5)\fR\m[]\&\s-2\u[2]\d\s+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\&.
.RE
.SS "Web Service Arguments"
.PP
In addition to the
\m[blue]\fBstandard CGI arguments\fR\m[]\&\s-2\u[38]\d\s+2,
\fBdacs_authenticate\fR
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\&.
.PP
\fIAUTH_ID\fR
.RS 4
This optional argument is used with the
user_sufficient
keyword (refer to the
\m[blue]\fBCONTROL\fR\m[]\&\s-2\u[11]\d\s+2
directive)\&.
.RE
.PP
\fIAUTH_PROMPT_VAR_PREFIX\fR
.RS 4
Reserved for use by
\m[blue]\fBlocal_pam_authenticate\fR\m[]\&\s-2\u[39]\d\s+2\&.
.RE
.PP
\fIAUTH_TRANSID\fR
.RS 4
Reserved for use by
\m[blue]\fBlocal_pam_authenticate\fR\m[]\&\s-2\u[39]\d\s+2\&.
.RE
.PP
\fIAUTHORIZATION\fR
.RS 4
Used internally with
\m[blue]\fBHTTP Authentication\fR\m[]\&\s-2\u[4]\d\s+2\&.
.RE
.PP
\fIAUXILIARY\fR
.RS 4
This argument can be used to pass additional authentication material to authentication modules\&. A compile\-time maximum length of
\fB128\fR
characters is imposed\&.
.RE
.PP
\fICOOKIE_SYNTAX\fR
.RS 4
By default, the
\fIde facto\fR
standard
\m[blue]\fBNetscape HTTP Cookies Specification\fR\m[]\&\s-2\u[32]\d\s+2
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
\m[blue]\fBRFC 2109\fR\m[]\&\s-2\u[40]\d\s+2,
\m[blue]\fBRFC 2965\fR\m[]\&\s-2\u[41]\d\s+2, and
\m[blue]\fBRFC 6265\fR\m[]\&\s-2\u[42]\d\s+2\&. 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\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
\m[blue]\fBRFC 2109\fR\m[]\&\s-2\u[40]\d\s+2,
\m[blue]\fBRFC 2965\fR\m[]\&\s-2\u[41]\d\s+2, and
\m[blue]\fBRFC 6265\fR\m[]\&\s-2\u[42]\d\s+2
forbid the following characters from appearing within an HTTP cookie\*(Aqs
NAME
attribute:
.sp
.if n \{\
.RS 4
.\}
.nf
( ) < > @ , ; : \e " / [ ] ? = { }
.fi
.if n \{\
.RE
.\}
.sp
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
\m[blue]\fBRFC 2616\fR\m[]\&\s-2\u[43]\d\s+2, S2\&.2)\&. By default,
\fBDACS\fR
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
\m[blue]\fBcolons are used within cookie names\fR\m[]\&\s-2\u[44]\d\s+2\&. 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
\m[blue]\fBCOOKIE_NAME_TERMINATORS\fR\m[]\&\s-2\u[34]\d\s+2
directive\&.
.sp .5v
.RE
.RE
.PP
\fIDACS_AUTH_SUCCESS_HANDLER\fR
.RS 4
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
\fIDACS_AUTH_SUCCESS_HANDLER\fR\&. The
\fIDACS_ERROR_URL\fR
is passed to this web service by
\m[blue]\fBdacs_acs(8)\fR\m[]\&\s-2\u[45]\d\s+2
as part of an authentication workflow initiated by a request that is denied because no credentials were supplied;
\fIDACS_ERROR_URL\fR
should not be generated by any non\-\fBDACS\fR
software\&.
.RE
.PP
\fIDACS_BROWSER\fR
.RS 4
If an argument named
\fIDACS_BROWSER\fR
is present and has the value
\fB1\fR, it signifies that the request is coming from a browser rather than middleware\&. If the request comes from a browser,
\fBDACS\fR
will return a cookie using the
Set\-Cookie
HTTP response header, otherwise it will not\&.
.RE
.PP
\fIDACS_DEBUG\fR
.RS 4
If this argument is present, the web service will produce more detailed log information\&.
.RE
.PP
\fIENABLE_AUTH_HANDLERS\fR
.RS 4
The jurisdiction\*(Aqs authentication handler directives are honoured if and only if this argument is present and has the value
\fB1\fR\&.
.RE
.PP
\fIOPERATION\fR
.RS 4
This is used with the identity selection mechanism described by
\m[blue]\fBdacs_select_credentials(8)\fR\m[]\&\s-2\u[46]\d\s+2\&. If the value of this parameter is
SELECT
and authentication is successful, any currently selected credentials are deselected and the new credentials are selected\&.
.RE
.PP
\fIPASSWORD\fR
.RS 4
This argument is the password that corresponds to
\fIUSERNAME\fR\&. A compile\-time maximum length of
\fB128\fR
characters is imposed\&.
.RE
.PP
\fIUSERNAME\fR
.RS 4
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
\fBDACS\fR
username\&. For example, if the value of
\fIUSERNAME\fR
is not a syntactically valid
\fBDACS\fR
username (see
\m[blue]\fBdacs(1)\fR\m[]\&\s-2\u[12]\d\s+2), the authentication procedure must transform it into something acceptable (using the
\m[blue]\fB\fBstrtr()\fR\fR\m[]\&\s-2\u[47]\d\s+2
function, for instance; see
\m[blue]\fBdacs\&.exprs(5)\fR\m[]\&\s-2\u[3]\d\s+2)\&. A compile\-time maximum length of
\fB64\fR
characters is imposed\&.
.RE
.PP
\fIWWW_AUTHENTICATE\fR
.RS 4
Reserved for internal use by
\m[blue]\fBHTTP Authentication\fR\m[]\&\s-2\u[4]\d\s+2\&.
.RE
.SS "Auth Clause Directives"
.PP
Each
Auth
clause in a
\fBDACS\fR
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,
\m[blue]\fBLDAP_USERNAME_URL\fR\m[]\&\s-2\u[48]\d\s+2
is only meaningful to the
\m[blue]\fBlocal_ldap_authenticate\fR\m[]\&\s-2\u[49]\d\s+2
module\&. The general\-purpose
\m[blue]\fBOPTION\fR\m[]\&\s-2\u[50]\d\s+2
directive may sometimes be used to specify an argument to an authentication module\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBImportant\fR
.ps -1
.br
.PP
The order in which the
Auth
clauses appear is significant\&. See the
\m[blue]\fBCONTROL\fR\m[]\&\s-2\u[11]\d\s+2
directive\&.
.sp .5v
.RE
.PP
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\&.
.PP
The following configuration directives are recognized by
\fBdacs_authenticate\fR
within any
Auth
clause (see
\m[blue]\fBdacs\&.conf(5)\fR\m[]\&\s-2\u[51]\d\s+2
for general information about directives)\&.
.PP
\fBAuth Clause Common Directives Index:\fR
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 1." 4.2
.\}
CONTROL (Required1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 2." 4.2
.\}
CREDENTIALS_LIFETIME_SECS (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 3." 4.2
.\}
EXIT* (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 4.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 4." 4.2
.\}
EXPR (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 5.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 5." 4.2
.\}
FLAGS (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 6.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 6." 4.2
.\}
INIT* (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 7.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 7." 4.2
.\}
OPTION (Optional)
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 8.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 8." 4.2
.\}
OPTION* (Optional)
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 9.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 9." 4.2
.\}
PASSWORD_AUDIT (Optional)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'10.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "10." 4.2
.\}
PREDICATE (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'11.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "11." 4.2
.\}
STYLE (Required1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'12.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "12." 4.2
.\}
URL (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'13.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "13." 4.2
.\}
URL* (Optional1)
.RE
.PP
CONTROL (Required1)
.RS 4
This directive specifies a PAM\-like control keyword that determines what will happen if the authentication module succeeds or fails; see
\m[blue]\fBpam(3)\fR\m[]\&\s-2\u[52]\d\s+2
and the
\m[blue]\fBX/Open Single Sign\-On Service (XSSO) preliminary specification\fR\m[]\&\s-2\u[53]\d\s+2
(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\&.
.sp
The first
Auth
clause that appears after configuration merging (see
\m[blue]\fBdacs\&.conf(5)\fR\m[]\&\s-2\u[54]\d\s+2) is the "top" or first module in the stack, the next one is the second module in the stack, and so on\&.
.sp
The value of this directive is a case\-insensitive keyword that can be abbreviated up to the indicated minimum:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
require[d]
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
requisite
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
opt[ional]
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
suff[icient]
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
user_suff[icient]
.RE
.sp
For example, the keywords
require
and
required
are equivalent\&.
.sp
The control flow of authentication module processing is as follows:
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 1." 4.2
.\}
If a
requisite
module fails, authentication fails and
\fBdacs_authenticate\fR
stops processing the module stack, returning the error reported by the
requisite
module;
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 2." 4.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);
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 3." 4.2
.\}
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;
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 4.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 4." 4.2
.\}
If none of the modules in the stack are designated as
required
or
requisite, then
\fBdacs_authenticate\fR
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;
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 5.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 5." 4.2
.\}
The first exception to the above is caused by the
sufficient
keyword\&. If a module that is designated as
sufficient
succeeds, then
\fBdacs_authenticate\fR
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;
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 6.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 6." 4.2
.\}
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
\fIand\fR
sufficient
Auth
clauses\&. This control simplifies configuring user\-selectable authentication methods\&. Note that this mechanism will necessarily reveal additional information about a jurisdiction\*(Aqs authentication configuration\&.
.sp
If the
\fIAUTH_ID\fR
argument is
\fInot\fR
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
\fIAUTH_ID\fR
is present, then only an
Auth
clause with a
user_sufficient
control
\fIand\fR
an exactly matching
id
attribute is used\&. There can be at most one such
Auth
clause; all other
Auth
clauses having a
user_sufficient
\fIor\fR
sufficient
control is disabled\&. In all other respects, an enabled
user_sufficient
Auth
clause is processed as for the
sufficient
control;
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 7.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 7." 4.2
.\}
If an error occurs while processing a directive, then
\fBdacs_authenticate\fR
fails immediately\&.
.RE
.sp
.RE
.PP
CREDENTIALS_LIFETIME_SECS (Optional1)
.RS 4
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
\fI${Auth::CREDENTIALS_LIFETIME_SECS}\fR\&. Authentication will fail if this value is invalid\&.
.RE
.PP
EXIT* (Optional1)
.RS 4
If authentication is successful, this expression is evaluated immediately after the module\*(Aqs authentication processing is executed (but refer to the
FLAGS
directive)\&.
.RE
.PP
EXPR (Optional1)
.RS 4
This directive, which is required when
STYLE
is
expr, gives an expression that is evaluated to decide whether to grant credentials and the
\fBDACS\fR
identity to use\&. See
\m[blue]\fBAuthenticating Using an Expression\fR\m[]\&\s-2\u[55]\d\s+2\&.
.RE
.PP
FLAGS (Optional1)
.RS 4
This directive gives control flags that are interpreted by
\fBdacs_authenticate\fR\&. Each directive consists of a whitespace\-separated list of values\&.
.sp
The only value currently recognized is the keyword
ident\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBImportant\fR
.ps -1
.br
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\&.
.sp
The
\fI${Auth::CURRENT_USERNAME}\fR
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\&.
.sp
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\&.
.sp .5v
.RE
.RE
.PP
INIT* (Optional1)
.RS 4
The given expression is evaluated immediately prior to the
URL*
and
EXPR
expressions, all of which are evaluated before a module\*(Aqs authentication processing is invoked\&.
.RE
.PP
OPTION (Optional)
.RS 4
The directive value is a
\fIname\fR=\fIvalue\fR
pair that may be interpreted by
\fBdacs_authenticate\fR
or the authentication module specified by the
Auth
clause\&. It causes a variable called
\fIname\fR
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 \*(Aq=\*(Aq and any quotes around the value are considered to be part of the value\&. A given
\fIname\fR
may not be specified more than once within a particular
Auth
clause\&. The
Options
namespace is initialized with
\fIUSERNAME\fR,
\fIPASSWORD\fR,
\fIAUXILIARY\fR,
\fIDACS_JURISDICTION\fR, and
\fIDACS_VERSION\fR
variables\&. If these variables are specified by an
OPTION, the argument ordinarily used will be overridden\&.
.sp
For example, this directive causes
SAMBA_PORT=139
to be passed as a
POST
method parameter:
.sp
.if n \{\
.RS 4
.\}
.nf
OPTION "SAMBA_PORT=139"
.fi
.if n \{\
.RE
.\}
.sp
.RE
.PP
OPTION* (Optional)
.RS 4
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
\fIname\fR=\fIvalue\fR
pair, as with the
OPTION
directive, and overrides any
\fIname\fR
in the
Options
namespace\&.
.RE
.PP
PASSWORD_AUDIT (Optional)
.RS 4
This directive is used to audit password\-type arguments passed to authentication modules by
\fBdacs_authenticate\fR, regardless of the authentication method, against the criteria selected by the specified constraint string, which is in the format used by
\m[blue]\fBPASSWORD_CONSTRAINTS\fR\m[]\&\s-2\u[56]\d\s+2\&. 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
\m[blue]\fBLOG_FILTER\fR\m[]\&\s-2\u[57]\d\s+2
directive\&. This feature can be used to notify the administrator about weak passwords\&.
.sp
The directive value can be a variable name, which is matched exactly against the
\fIPASSWORD\fR
or
\fIAUXILIARY\fR
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:
.sp
.if n \{\
.RS 4
.\}
.nf
PASSWORD_CONSTRAINTS "8L,1C,1P"
URL "https://foo\&.example\&.com/cgi\-bin/dacs/local_woof_authenticate"
STYLE "pass"
CONTROL "sufficient"
PASSWORD_AUDIT "PASSWORD 10L"
PASSWORD_AUDIT "AUXILIARY"
.fi
.if n \{\
.RE
.\}
.sp
Here, the
\fIPASSWORD\fR
argument must be at least ten characters long but
\fIAUXILIARY\fR
must only be eight characters long and include an upper case character and punctuation\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
Not all authentication modules require a
\fIPASSWORD\fR
argument, such as
\m[blue]\fBlocal_cas_authenticate\fR\m[]\&\s-2\u[58]\d\s+2
in its interactive mode\&. This directive is ignored if the argument is not passed to the module\&.
.sp .5v
.RE
.RE
.PP
PREDICATE (Optional1)
.RS 4
If provided, this expression is evaluated before any other authentication module processing is done\&. If there is an evaluation error or it returns
\fBFalse\fR
(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\&.
.sp
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
\fIUSERNAME\fR, current date and time, IP address from where the request originates, and so on\&.
.RE
.PP
STYLE (Required1)
.RS 4
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\&.
.PP
cas
.RS 4
This style selects username/password authentication using the
\m[blue]\fBCentral Authentication Service (CAS)\fR\m[]\&\s-2\u[59]\d\s+2
protocol through the
\m[blue]\fBlocal_cas_authenticate\fR\m[]\&\s-2\u[58]\d\s+2
authentication module\&.
.RE
.PP
cert[ificate]
.RS 4
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
\fBApache\fR
through the
\fBSSL_CLIENT_CERT\fR
environment variable\&.
.RE
.PP
digest
.RS 4
This selects the
\m[blue]\fBRFC 2617\fR\m[]\&\s-2\u[60]\d\s+2
Digest Access Authentication scheme as implemented by
\fBDACS\fR
in conjunction with the
\m[blue]\fBlocal_apache_authenticate\fR\m[]\&\s-2\u[61]\d\s+2
authentication module\&. See
\m[blue]\fBHTTP Authentication\fR\m[]\&\s-2\u[4]\d\s+2\&.
.RE
.PP
expr
.RS 4
No authentication module will be used;
\m[blue]\fBexpression evaluation\fR\m[]\&\s-2\u[55]\d\s+2
will be used instead\&.
.RE
.PP
infocard
.RS 4
A self\-issued or managed
\m[blue]\fBInformation Card\fR\m[]\&\s-2\u[62]\d\s+2
(InfoCard) must be provided for authentication\&. To be recognized, the InfoCard must have been previously registered at this jurisdiction using
\m[blue]\fBdacsinfocard(1)\fR\m[]\&\s-2\u[63]\d\s+2,
\m[blue]\fBdacs_infocard(8)\fR\m[]\&\s-2\u[64]\d\s+2, or
\m[blue]\fBdacs_managed_infocard(8)\fR\m[]\&\s-2\u[65]\d\s+2\&. This style is implemented by the
\m[blue]\fBlocal_infocard_authenticate\fR\m[]\&\s-2\u[66]\d\s+2
authentication module\&.
.RE
.PP
managed_infocard
.RS 4
A managed
\m[blue]\fBInformation Card\fR\m[]\&\s-2\u[62]\d\s+2
(InfoCard) must be provided for authentication\&. To be recognized, the InfoCard must have been previously registered at this jurisdiction using
\m[blue]\fBdacs_managed_infocard(8)\fR\m[]\&\s-2\u[65]\d\s+2\&. This style is implemented by the
\m[blue]\fBlocal_infocard_authenticate\fR\m[]\&\s-2\u[66]\d\s+2
authentication module\&.
.RE
.PP
nat[ive]
.RS 4
The user is expected to have already authenticated through the web server\*(Aqs native authentication mechanism (e\&.g\&., HTTP Basic or Digest authentication,
\m[blue]\fBRFC 2617\fR\m[]\&\s-2\u[60]\d\s+2);
\fBDACS\fR
will import this identity without any additional requirements\&. The
\fBAUTH_TYPE\fR
environment variable but be available and have the value
Basic
or
Digest
(case insensitive), and the
\fBREMOTE_USER\fR
environment variable must be set\&.
.RE
.PP
pass[word]
.br
passwd
.RS 4
The username must be provided through a
\fIUSERNAME\fR
argument and the password must accompany the authentication request through a
\fIPASSWORD\fR
argument\&.
.RE
.PP
prompt[ed]
.RS 4
A dialog\-based interaction will be conducted, such as one based on Pluggable Authentication Modules (PAM)\&. See
\m[blue]\fBlocal_pam_authenticate\fR\m[]\&\s-2\u[39]\d\s+2\&.
.RE
.PP
selfissued_infocard
.RS 4
A self\-issued
\m[blue]\fBInformation Card\fR\m[]\&\s-2\u[62]\d\s+2
(InfoCard) must be provided for authentication\&. To be recognized, the InfoCard must have been previously registered at this jurisdiction using
\m[blue]\fBdacsinfocard(1)\fR\m[]\&\s-2\u[63]\d\s+2
or
\m[blue]\fBdacs_infocard(8)\fR\m[]\&\s-2\u[64]\d\s+2\&. This style is implemented by the
\m[blue]\fBlocal_infocard_authenticate\fR\m[]\&\s-2\u[66]\d\s+2
authentication module\&.
.RE
.PP
simple
.RS 4
This style of authentication merely requires a recognized username, provided through a
\fIUSERNAME\fR
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
\fIPASSWORD\fR
argument is provided, it is logged as sensitive data, much as an anonymous FTP password might be logged\&. This style is implemented by the
\m[blue]\fBlocal_simple_authenticate\fR\m[]\&\s-2\u[67]\d\s+2
authentication module\&.
.RE
.PP
tgma
.RS 4
\fIExperimental\fR\&. This interactive style of authentication requires only
\fIUSERNAME\fR
and
\fIJURISDICTION\fR
arguments to be selected by the user\&. Refer to the TGMA authentication module for details\&.
.sp
This style is implemented by the
\m[blue]\fBlocal_tgma_authenticate\fR\m[]\&\s-2\u[68]\d\s+2
authentication module\&.
.RE
.PP
set_roles
.RS 4
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
\m[blue]\fBadd_roles\fR\m[]\&\s-2\u[69]\d\s+2
is not used\&.
.RE
.PP
add_roles
.RS 4
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
\m[blue]\fBset_roles\fR\m[]\&\s-2\u[70]\d\s+2
option also appears\&.
.RE
.RE
.PP
URL (Optional1)
.br
URL* (Optional1)
.RS 4
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\&.
.sp
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\&.
.sp
In the current implementation, the standard set of modules must run within the context of a
\fBDACS\fR
jurisdiction\&. This is not an architectural limitation, however\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBTip\fR
.ps -1
.br
Some authentication modules are available as built\-in components of
\fBdacs_authenticate\fR
and
\fBdacsauth\fR\&. These modules are identified by specific relative URLs\&. A module\*(Aqs 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\&.
.sp
Although it will be more efficient (and possibly more secure) to use a built\-in module, they are executed on the same host as
\fBdacs_authenticate\fR
thereby giving up some flexibility because access control rules are not applied to them (other than the one for
\fBdacs_authenticate\fR), and
\fBdacs_authenticate\fR
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
\fBDACS\fR
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
\fBdacsauth\fR\&.
.sp .5v
.RE
.RE
.PP
Here is an example of a configuration that will authenticate using
Unix
user names and passwords:
.sp
.if n \{\
.RS 4
.\}
.nf
URL "https://foo\&.example\&.com:8443/cgi\-bin/dacs/local_unix_authenticate"
STYLE "pass"
CONTROL "sufficient"
.fi
.if n \{\
.RE
.\}
.PP
In the following example,
\fBdacs_authenticate\fR
will first try to authenticate using a
Unix
login name and password; if that fails, it will then try a
\fBDACS\fR
account name and password\&.
.sp
.if n \{\
.RS 4
.\}
.nf
URL "https://foo\&.example\&.com:8443/cgi\-bin/dacs/local_unix_authenticate"
STYLE "pass"
CONTROL "sufficient"
URL "https://foo2\&.example\&.com/cgi\-bin/dacs/local_passwd_authenticate"
STYLE "pass"
CONTROL "sufficient"
.fi
.if n \{\
.RE
.\}
.PP
The preceding example can be changed to try authenticating using a
\fBDACS\fR
account name and password if and only if the
\fIAUXILIARY\fR
argument has the value "guest" (which might have been provided when the user selected a button on a login form):
.sp
.if n \{\
.RS 4
.\}
.nf
URL "https://foo\&.example\&.com:8443/cgi\-bin/dacs/local_unix_authenticate"
STYLE "pass"
CONTROL "sufficient"
PREDICATE \*(Aq${Args::AUXILIARY} ne "guest"\*(Aq
URL "https://foo2\&.example\&.com/cgi\-bin/dacs/local_passwd_authenticate"
STYLE "pass"
CONTROL "sufficient"
PREDICATE \*(Aq${Args::AUXILIARY} eq "guest"\*(Aq
.fi
.if n \{\
.RE
.\}
.PP
In this example, a jurisdiction offers users a choice from among three authentication methods: a Google(TM) account, a Windows NTLM account, or a
\fBDACS\fR
password\-based account\&. The jurisdiction\*(Aqs login form would be written to provide the appropriate
\fIAUTH_ID\fR
argument for the corresponding method;
.sp
.if n \{\
.RS 4
.\}
.nf
# For AUTH_ID=google
URL "local_http_authenticate"
STYLE "password"
CONTROL "user_sufficient"
OPTION \*(AqAUTH_URL="https://www\&.google\&.com/accounts/ClientLogin"\*(Aq
OPTION \*(AqAUTH_METHOD=POST\*(Aq
OPTION \*(AqUSERNAME_PARAMETER="Email"\*(Aq
OPTION \*(AqPASSWORD_PARAMETER="Passwd"\*(Aq
OPTION \*(Aqservice=xapi\*(Aq
OPTION "source=DSS\-DACS\-1\&.4"
# For AUTH_ID=ntlm
URL "local__ntlm_authenticate"
STYLE "password"
CONTROL "user_sufficient"
OPTION \*(AqSAMBA_SERVER="samba\&.example\&.com"\*(Aq
OPTION \*(AqSAMBA_PORT="139"\*(Aq
EXIT* \*(Aq${Auth::CURRENT_USERNAME}=strtr(${Auth::CURRENT_USERNAME}, "a\-z", "A\-Z")\*(Aq
# For AUTH_ID=passwd
URL "local_passwd_authenticate"
STYLE "password"
CONTROL "user_sufficient"
.fi
.if n \{\
.RE
.\}
.sp
.SS "Initialization and the Auth Namespace"
.PP
\fBdacs_authenticate\fR
uses a variable namespace called
Auth
to make authentication\-related context available to its configuration directives (see
\m[blue]\fBdacs\&.exprs(5)\fR\m[]\&\s-2\u[71]\d\s+2)\&. Aspects of
\fBdacs_authenticate\fR\*(Aqs behaviour can be controlled by modifying these variables\&. This namespace disappears when
\fBdacs_authenticate\fR
terminates\&. The next section describes how these variables are used\&.
.PP
Additionally, all environment variables are accessible through the
Env
namespace (e\&.g\&.,
\fI${Env::REMOTE_ADDR}\fR) during authentication processing\&.
.SS "Authentication Clause Control Flow"
.PP
Auth
clauses are processed in the order in which they appear in the configuration file, subject to the semantics of the
CONTROL
directives\&.
.PP
\fBdacs_authenticate\fR
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
\m[blue]\fBAUTH_SUCCESS\fR\m[]\&\s-2\u[72]\d\s+2
expression is evaluated and the
\m[blue]\fBAUTH_SUCCESS_HANDLER\fR\m[]\&\s-2\u[73]\d\s+2
directive is consulted; if authentication fails, the
\m[blue]\fBAUTH_ERROR_HANDLER\fR\m[]\&\s-2\u[74]\d\s+2
and
\m[blue]\fBAUTH_FAIL_DELAY_SECS\fR\m[]\&\s-2\u[75]\d\s+2
directives are used\&. This behaviour is partially under the control of the caller through the
\m[blue]\fB\fIDACS_AUTH_SUCCESS_HANDLER\fR\fR\m[]\&\s-2\u[76]\d\s+2
and
\m[blue]\fB\fIENABLE_AUTH_HANDLERS\fR\fR\m[]\&\s-2\u[77]\d\s+2
arguments, however\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBTip\fR
.ps -1
.br
.PP
To redirect the newly authenticated user to a web page based on the user\*(Aqs identity, jurisdiction, roles, or other contextual state, configure
AUTH_SUCCESS_HANDLER
to specify the URL of a
\fBDACS\fR\-wrapped CGI program\&. After examining environment variables automatically passed to it by
\fBDACS\fR
or its query arguments, this program can emit an appropriate redirect\&. To test this, configure:
.sp
.if n \{\
.RS 4
.\}
.nf
AUTH_SUCCESS_HANDLER "url /cgi\-bin/dacs/dacs_prenv"
.fi
.if n \{\
.RE
.\}
.sp
(making sure that
\m[blue]\fBdacs_prenv(8)\fR\m[]\&\s-2\u[78]\d\s+2
has been installed) and examine the information that is available\&.
.sp .5v
.RE
.PP
An
Auth
clause is processed in a sequence of steps, and with various hooks to provide fine\-grained control\&. Only advanced
\fBDACS\fR
administrators usually need to be concerned with this level of detail\&.
.PP
Before the first clause is examined, the variable
\fI${Auth::CURRENT_USERNAME}\fR
is set to the empty string; this variable is automatically updated by
\fBdacs_authenticate\fR\&. The contents of the
Args,
DACS,
Conf, and
Env
\m[blue]\fBnamespaces\fR\m[]\&\s-2\u[71]\d\s+2
are made available to all expressions evaluated during authentication module processing\&. Processing of each
Auth
clause is performed in the following sequence:
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 1." 4.2
.\}
If the clause has a
PREDICATE
directive, it is evaluated in the current context\&. If the value is not
\fBTrue\fR
(including cases where the expression was invalid), processing of the clause terminates immediately with the same result as if its authentication had been unsuccessful\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 2." 4.2
.\}
If a variable named
\fI${Auth::ABORT}\fR
has the value
yes
(case insensitive), authentication terminates\&. If the variable
\fI${Auth::MODULE_SKIP}\fR
has the value
yes
(case insensitive), processing of the clause terminates immediately with the same result as if its authentication had been unsuccessful\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 3." 4.2
.\}
If the clause has an
INIT*
directive, it is evaluated; if an error occurs, authentication terminates\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 4.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 4." 4.2
.\}
If the clause has a
URL
directive, it names the authentication module to be invoked (or is the name of a built\-in module)\&.
.sp
If the
URL*
directive is used instead, it is evaluated to obtain the URL to be invoked; if an error occurs, authentication terminates\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 5.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 5." 4.2
.\}
If a variable named
\fI${Auth::ABORT}\fR
has the value
yes
(case insensitive), authentication terminates\&. If the variable
\fI${Auth::MODULE_SKIP}\fR
has the value
yes
(case insensitive), processing of the clause terminates immediately with the same result as if its authentication had been unsuccessful\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 6.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 6." 4.2
.\}
If the clause\*(Aqs
STYLE
is
expr, the
EXPR
directive is evaluated and is expected to either return
\fBFalse\fR
or a valid
\fBDACS\fR
username\&. If the expression\*(Aqs value is
\fBFalse\fR, 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\&.
.sp
If the clause\*(Aqs
STYLE
is not
expr, the authentication module is invoked\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 7.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 7." 4.2
.\}
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\&.
.sp
The username passed to the module, or returned by the module, becomes the tentative
\fBDACS\fR
username and the variable
\fI${Auth::CURRENT_USERNAME}\fR
is set to it\&. If the variable
\fI${Auth::ROLES}\fR
is set to a valid role descriptor, it becomes the current tentative roles for the user\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 8.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 8." 4.2
.\}
The expression given by the
EXIT*
directive, if any, is evaluated\&. If an error occurs, authentication terminates\&. The expression may update
\fI${Auth::CURRENT_USERNAME}\fR\&. For instance, the directive:
.sp
.if n \{\
.RS 4
.\}
.nf
EXIT* \*(Aq${Auth::CURRENT_USERNAME}="bobo"\*(Aq
.fi
.if n \{\
.RE
.\}
.sp
completely ignores the username returned by the module and simply assigns one, while this directive:
.sp
.if n \{\
.RS 4
.\}
.nf
EXIT* \*(Aq${Auth::CURRENT_USERNAME} = \e
strtr(${Auth::CURRENT_USERNAME}, "A\-Z", "a\-z")\*(Aq
.fi
.if n \{\
.RE
.\}
.sp
converts all upper case characters in the username returned by the module to their lower case equivalents\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 9.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 9." 4.2
.\}
If a variable named
\fI${Auth::ABORT}\fR
has the value
yes
(case insensitive), authentication terminates despite success of the module\&. If the variable
\fI${Auth::MODULE_SKIP}\fR
has the value
yes
(case insensitive), processing of the clause terminates immediately with the same result as if its authentication had been unsuccessful\&.
.RE
.PP
The value of
\fI${Auth::CURRENT_USERNAME}\fR
when the last module has been processed is the username that will be assigned to a successfully authenticated user\&. If set, the value of
\fI${Auth::CREDENTIALS_LIFETIME_SECS}\fR
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\*(Aqs
CREDENTIALS_LIFETIME_SECS
directive), if available, or the jurisdiction\*(Aqs
CREDENTIALS_LIFETIME_SECS
directive\*(Aqs value\&.
.SS "Authenticating Using an Expression"
.PP
Rather than using an authentication module, the
expr
style of authentication involves evaluating an expression\&. The value of the expression is the
\fBDACS\fR
username to associate with the user\&. If no value is returned, an invalid value is returned, or an error occurs, the
Auth
clause fails\&.
.PP
Here is a simple example that is unlikely to be used in practice\&. If the
\fIPASSWORD\fR
argument is "xyzzy", then authentication will succeed and the user will be assigned the
\fBDACS\fR
username
bobo\&.
.sp
.if n \{\
.RS 4
.\}
.nf
STYLE "expr"
CONTROL "sufficient"
EXPR \*(Aq${Args::PASSWORD} eq "xyzzy" ? "bobo" : ""\*(Aq
.fi
.if n \{\
.RE
.\}
.PP
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\&.
.sp
.if n \{\
.RS 4
.\}
.nf
STYLE "expr"
EXPR \*(Aq${pwd} = get("/usr/local/dacs/pwd/pwd\&." \&. ${Args::USERNAME}); \e
digest(${Args::PASSWORD}, 0, sha256) eq decode(hex, ${pwd}) \e
? ${Args::USERNAME} : ""\*(Aq
CONTROL "sufficient"
.fi
.if n \{\
.RE
.\}
.PP
The expression can also assign a valid role string to
\fI${Auth::ROLES}\fR
to establish roles for the user (in conjunction with the
\m[blue]\fBadd_roles\fR\m[]\&\s-2\u[69]\d\s+2
or
\m[blue]\fBset_roles\fR\m[]\&\s-2\u[70]\d\s+2
style modifier):
.sp
.if n \{\
.RS 4
.\}
.nf
STYLE "expr,add_roles"
CONTROL "sufficient"
EXPR \*(Aq${Auth::ROLES}="foo,bar"; ${Args::PASSWORD} eq \e
"xyzzy" ? "bobo" : ""\*(Aq
.fi
.if n \{\
.RE
.\}
.PP
This style of authentication can be a useful alternative to the
cert
style with the
\fBlocal_cert_authenticate\fR
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\&.
\m[blue]\fBEnvironment variables\fR\m[]\&\s-2\u[79]\d\s+2
created by
\m[blue]\fBmod_ssl\fR\m[]\&\s-2\u[80]\d\s+2
can be referenced as
\fI${Auth::\fR\fI\fIssl_variable_name\fR\fR\fI}\fR\&. Something such as the following might be suitable:
.sp
.if n \{\
.RS 4
.\}
.nf
STYLE "expr"
CONTROL "sufficient"
EXPR \*(Aq${Auth::SSL_CLIENT_VERIFY} eq "SUCCESS" and
${Auth::SSL_CLIENT_S_DN_Email:ei} \e
? ${Auth::SSL_CLIENT_S_DN_Email:i} : ""\*(Aq
.fi
.if n \{\
.RE
.\}
.PP
Another application of this style of authentication is where it is the location of the user that is important rather than the user\*(Aqs identity
\fIper se\fR\&. 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:
.sp
.if n \{\
.RS 4
.\}
.nf
STYLE "expr"
CONTROL "sufficient"
EXPR \*(Aq${Auth::CURRENT_USERNAME} = "user\-${Env::REMOTE_ADDR}"\*(Aq
.fi
.if n \{\
.RE
.\}
.sp
A user would not provide a username or a password; by simply clicking on a link that invokes
\fBdacs_authenticate\fR, 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\&.
.SS "Middleware Support"
.PP
As with most
\fBDACS\fR
web services, the
\fIFORMAT\fR
argument can be used to request a particular type of output (see
\m[blue]\fBdacs\&.services(8)\fR\m[]\&\s-2\u[81]\d\s+2) from
\fBdacs_authenticate\fR\&. If any XML type is specified, the reply from
\fBdacs_authenticate\fR
will conform to the DTD
\m[blue]\fBdacs_auth_reply\&.dtd\fR\m[]\&\s-2\u[82]\d\s+2\&. 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
\m[blue]\fBdacs_current_credentials\&.dtd\fR\m[]\&\s-2\u[83]\d\s+2)\&. If authentication was unsuccessful because of a transient error condition, a reason may optionally be provided\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBSecurity\fR
.ps -1
.br
.PP
This reason is solely used to inform the user; it should not reveal any details that might compromise security\&.
.sp .5v
.RE
.PP
Authentication modules return an
\m[blue]\fBauth_reply\&.dtd\fR\m[]\&\s-2\u[84]\d\s+2
document to
\fBdacs_authenticate\fR\&.
.SS "Authentication Modules"
.PP
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBImportant\fR
.ps -1
.br
.PP
\fBDACS\fR
provides a set of authentication modules\&. At the time
\fBDACS\fR
is compiled, some standard modules are enabled by default while others needed must be specifically enabled (see
\m[blue]\fBdacs\&.install(7)\fR\m[]\&\s-2\u[85]\d\s+2)\&. You should not enable authentication modules that you do not plan to use\&.
.sp .5v
.RE
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBSecurity\fR
.ps -1
.br
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
As a security measure, these modules should be executable only by
\fBdacs_authenticate\fR, which is the default\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
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\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
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\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
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\*(Aqs functionality (e\&.g\&., by attaching to the running module with a debugger)\&.
.RE
.sp .5v
.RE
.PP
Each authentication module is called with the following arguments\&. Authentication modules are always invoked using the
POST
method\&.
.PP
\fIAUXILIARY\fR
.RS 4
The value of the
\fIAUXILIARY\fR
argument to
\fBdacs_authenticate\fR
if one was given, otherwise the empty string\&.
.RE
.PP
\fIDACS_JURISDICTION\fR
.RS 4
The value of the
\fIDACS_JURISDICTION\fR
argument to
\fBdacs_authenticate\fR\&.
.RE
.PP
\fIDACS_VERSION\fR
.RS 4
The
DACS_VERSION_NUMBER
for this version of
\fBdacs_authenticate\fR\&.
.RE
.PP
\fIPASSWORD\fR
.RS 4
The value of the
\fIPASSWORD\fR
argument to
\fBdacs_authenticate\fR
if one was given, otherwise the empty string\&.
.RE
.PP
\fIUSERNAME\fR
.RS 4
The value of the
\fIUSERNAME\fR
argument to
\fBdacs_authenticate\fR\&.
.RE
.PP
Directives
.RS 4
Each directive in the
Auth
section being processed and its value is passed\&.
.RE
.PP
SSL/TLS environment variables
.RS 4
Each SSL/TLS environment variable passed to
\fBdacs_authenticate\fR
is passed\&.
.RE
.PP
Transaction state data
.RS 4
With respect to the
prompted
style of authentication, transaction state variables are passed\&.
.RE
Ordinarily, a particular argument may not appear more than once\&.
.PP
\fBAuthentication Module Index:\fR
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 1." 4.2
.\}
local_apache_authenticate: Password\-protected accounts maintained by
\fBApache\fR
utilities
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 2." 4.2
.\}
local_cas_authenticate: Central Authentication Service (CAS)
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 3." 4.2
.\}
local_cert_authenticate: SSL\-based X\&.509 client certificates
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 4.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 4." 4.2
.\}
local_grid_authenticate: Grid\-based one\-time passwords
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 5.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 5." 4.2
.\}
local_http_authenticate: Generic authentication via HTTP
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 6.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 6." 4.2
.\}
local_infocard_authenticate: Information Card\-based accounts and identities
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 7.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 7." 4.2
.\}
local_ldap_authenticate: Lightweight Directory Access Protocol (LDAP) / Microsoft Active Directory
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 8.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 8." 4.2
.\}
local_native_authenticate: Importing an identity established by
\fBApache\fR
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 9.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 9." 4.2
.\}
local_ntlm_authenticate: Microsoft Windows NT LAN Manager usernames and passwords
.RE
.sp
.RS 4
.ie n \{\
\h'-04'10.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "10." 4.2
.\}
local_pam_authenticate: Pluggable Authentication Modules (PAM)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'11.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "11." 4.2
.\}
local_passwd_authenticate: Password\-protected
\fBDACS\fR
accounts
.RE
.sp
.RS 4
.ie n \{\
\h'-04'12.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "12." 4.2
.\}
local_radius_authenticate: RADIUS\-based
\fBDACS\fR
accounts
.RE
.sp
.RS 4
.ie n \{\
\h'-04'13.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "13." 4.2
.\}
local_simple_authenticate: Account name without a password
.RE
.sp
.RS 4
.ie n \{\
\h'-04'14.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "14." 4.2
.\}
local_tgma_authenticate: Time\-Gated Mutual Authentication (\fIexperimental\fR)
.RE
.sp
.RS 4
.ie n \{\
\h'-04'15.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "15." 4.2
.\}
local_token_authenticate: One\-time passwords, two\-factor authentication
.RE
.sp
.RS 4
.ie n \{\
\h'-04'16.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "16." 4.2
.\}
local_unix_authenticate:
Unix
usernames and passwords
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBlocal_apache_authenticate\fR
.RS 4
.PP
The
\fBlocal_apache_authenticate\fR
module is used to authenticate against password files used by the
\fBApache\fR
\m[blue]\fB\fBmod_authn_file\fR\fR\m[]\&\s-2\u[86]\d\s+2,
\m[blue]\fB\fBmod_auth_digest\fR\fR\m[]\&\s-2\u[87]\d\s+2, or
\m[blue]\fB\fBmod_authn_dbm\fR\fR\m[]\&\s-2\u[88]\d\s+2
modules\&. These password files are managed by
\fBApache\*(Aqs\fR
\m[blue]\fBhtpasswd(1)\fR\m[]\&\s-2\u[89]\d\s+2,
\m[blue]\fBhtdigest(1)\fR\m[]\&\s-2\u[90]\d\s+2, and
\m[blue]\fBhtdbm(1)\fR\m[]\&\s-2\u[91]\d\s+2
utilities, respectively\&. An administrator can configure
\fBDACS\fR
to use an existing
htpasswd
file, for instance, and so avoid dealing with creating and managing a duplicate set of usernames and passwords\&.
.PP
If HTTP Basic authentication (\m[blue]\fBRFC 2617\fR\m[]\&\s-2\u[60]\d\s+2) is used, the
STYLE
should be
password\&. If Digest authentication is used, because no password is passed to
\fBDACS\fR, the
STYLE
for this module should be configured as
digest\&.
.PP
The following configuration options are recognized by this module\&. They should be provided using the
OPTION
directive\&.
.PP
AUTH_MODULE
.RS 4
This must be "mod_auth" (or "htpasswd"), "mod_auth_digest" (or "htdigest"), or "mod_auth_dbm" (or "htdbm"), depending on which module\*(Aqs authentication method is to be used\&. This value is case\-insensitive\&.
.RE
.PP
AUTH_FILE
.RS 4
This is the absolute pathname of the flat\-file or database file to use\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
This pathname is resolved on the host that runs this module\&. This should eventually be extended to accept a
\fBDACS\fR
virtual filestore URI\&.
.sp .5v
.RE
.RE
.PP
DBM_TYPE
.RS 4
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\&.
.RE
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNotes\fR
.ps -1
.br
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
This module does not rely on any
\fBApache\fR
module (other than
\fBmod_auth_dacs\fR)\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
This module does not require any
\fBApache\fR
configuration with respect to authentication; only
\fBDACS\fR
needs to be configured\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
It is not necessary to use
\fBDACS\*(Aqs\fR
\m[blue]\fBHTTP Authentication\fR\m[]\&\s-2\u[4]\d\s+2
feature in order to use this module\&. For example, using HTTP Basic authentication (\m[blue]\fBRFC 2617\fR\m[]\&\s-2\u[60]\d\s+2), the
\fIUSERNAME\fR
and
\fIPASSWORD\fR
arguments can be submitted from a site\*(Aqs login page and verified by this module against an
\fBhtpasswd\fR
file\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBhtpasswd\fR
allows plaintext passwords to be stored in a password file, although
\fBhttpd\fR
apparently restricts the use of these passwords\&. This module imposes no such restrictions\&. Under normal circumstances passwords should not be stored in plaintext form\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
The major difference between this module and
\m[blue]\fBlocal_native_authenticate\fR\m[]\&\s-2\u[92]\d\s+2
is that the latter "imports" an identity already established by an
\fBApache\fR
authentication module, whereas this module authenticates using information that can also be used by
\fBApache\fR
and which is administered using
\fBApache\fR
utiltities\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBDACS\fR
will access
\fBApache\fR
password files in read\-only mode only;
\fBDACS\fR
never modifies those files\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Some platforms may not support all possible DBM\-type databases and some types of database may not have been configured at build\-time\&.
.RE
.sp .5v
.RE
.PP
Here is an example configuration that uses an
\fBhtpasswd\fR\-managed file for authentication:
.sp
.if n \{\
.RS 4
.\}
.nf
HTTP_AUTH_ENABLE "yes"
HTTP_AUTH "Basic \e"DACS Basic Auth Area\e" /restricted/*"
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"
.fi
.if n \{\
.RE
.\}
.PP
If the passwords were kept in a Berkeley DB database instead, the configuration might look like:
.sp
.if n \{\
.RS 4
.\}
.nf
HTTP_AUTH_ENABLE "yes"
HTTP_AUTH "Basic \e"DACS Basic Auth Area\e" /restricted/*"
URL "https://example\&.com/cgi\-bin/dacs/local_apache_authenticate"
STYLE "pass"
CONTROL "sufficient"
OPTION "AUTH_FILE=/usr/local/apache2/conf/passwords\&.db"
OPTION "AUTH_MODULE=mod_auth_dbm"
OPTION "DBM_TYPE=db"
.fi
.if n \{\
.RE
.\}
.PP
This example configuration is similar; the difference is that the username and password obtained through HTTP Basic authentication are verified against a
Unix
account:
.sp
.if n \{\
.RS 4
.\}
.nf
HTTP_AUTH_ENABLE "yes"
HTTP_AUTH "Basic \e"DACS Basic Auth Area\e" /private/*"
URL "https://example\&.com/cgi\-bin/dacs/local_unix_authenticate"
STYLE "pass"
CONTROL "sufficient"
.fi
.if n \{\
.RE
.\}
.PP
This example configures HTTP Digest authentication and references an
\fBhtdigest\fR\-managed file:
.sp
.if n \{\
.RS 4
.\}
.nf
HTTP_AUTH_ENABLE "yes"
HTTP_AUTH "Digest \e"DACS Digest Auth Area\e" /digest/*"
URL "apache"
STYLE "digest"
CONTROL "sufficient"
OPTION "AUTH_FILE=/usr/local/apache2/conf/passwords\&.digest"
OPTION "AUTH_MODULE=mod_auth_digest"
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBTip\fR
.ps -1
.br
.PP
A built\-in version of this module can be selected by using the URL
local_apache_authenticate
or just
apache\&.
.sp .5v
.RE
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBlocal_cas_authenticate\fR
.RS 4
.PP
This module coordinates with a specified
\m[blue]\fBCentral Authentication Service (CAS)\fR\m[]\&\s-2\u[93]\d\s+2
server to authenticate a user that is purportedly known to that server\&. The module implements the client side of the
\m[blue]\fBCAS 2\&.0 Protocol\fR\m[]\&\s-2\u[94]\d\s+2
and can be used in two different modes: interactive and non\-interactive\&.
.PP
Interactive mode is employed if neither a
\fIUSERNAME\fR
nor a
\fIPASSWORD\fR
argument is given to
\fBdacs_authenticate\fR\&. When
\fBdacs_authenticate\fR
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\*(Aqs browser),
CAS
redirects the user to
\fBdacs_authenticate\fR, passing it the
CAS
session ticket as an argument called
\fIticket\fR\&. After successfully validating the session ticket at the
CAS
server,
\fBDACS\fR
authentication succeeds\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBSecurity\fR
.ps -1
.br
.PP
When interactive mode is used,
\fBDACS\fR
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
\m[blue]\fBOpenID\fR\m[]\&\s-2\u[95]\d\s+2
Authentication protocol\&.
.sp .5v
.RE
.PP
A variant of this flow of control can occur if the user has authenticated against the
CAS
server outside of
\fBDACS\fR
and therefore holds a ticket granting cookie\&. This cookie will automatically be sent by the user\*(Aqs browser when it is redirected to the
CAS
server; as a result, the
CAS
server may not prompt the user to authenticate\&.
.PP
In non\-interactive mode, both a
\fIUSERNAME\fR
\fIand\fR
a
\fIPASSWORD\fR
argument are passed to
\fBdacs_authenticate\fR\&. 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
\fBDACS\fR
\m[blue]\fBHTTP authentication\fR\m[]\&\s-2\u[4]\d\s+2
feature\&.
.PP
The
STYLE
should be configured as
cas
for this module\&.
.PP
The following module\-specific
OPTION
directive value is understood:
.PP
CAS_SERVER_URI (Required1)
.RS 4
This is the URI of the
CAS
server to authenticate against\&. For example,
dacs\&.conf
might contain authentication configuration similar to the following:
.sp
.if n \{\
.RS 4
.\}
.nf
URL "cas"
STYLE "cas"
CONTROL "sufficient"
OPTION "CAS_SERVER_URI=https://cas\&.example\&.com/castest"
.fi
.if n \{\
.RE
.\}
.sp
.RE
.PP
The module recognizes the following arguments (which are automatically passed to it as necessary by
\fBdacs_authenticate\fR):
.PP
CAS_TICKET (Required1\-C)
.RS 4
This is the session ticket returned by
CAS
via a callback to
\fBdacs_authenticate\fR
(i\&.e\&., the
\fIticket\fR
argument)\&.
.RE
.PP
CAS_REDIRECT_ARGS (Optional1)
.RS 4
These are additional arguments to
\fBdacs_authenticate\fR
that must be provided when
CAS
performs its callback to
\fBdacs_authenticate\fR
to preserve user preferences\&. The
\fIDACS_BROWSER\fR,
\fIFORMAT\fR,
\fIDACS_ERROR_URL\fR, and
\fIENABLE_AUTH_HANDLERS\fR
arguments may be forwarded in this way\&.
.RE
.PP
CAS_SERVER_URI (Required1\-C)
.RS 4
This argument has the value specified in the
Auth
clause\*(Aqs
OPTION
directive\&. Note that HTTP redirects are not handled in this context, so invoking
GET
on
CAS_SERVER_URI
must return a valid document\&.
.RE
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.PP
The
\fBlocal_cas_authenticate\fR
module extends the response of the
\fBvalidate\fR
service of the
CAS
protocol to allow a role descriptor string (\fIrole_string\fR) to be returned\&. If authentication succeeds, the standard service returns the following text:
yes\en\fIusername\fR\en
.PP This module understands a third line, which is optional: yes\en\fIusername\fR\en\fIrole_string\fR\en
An invalid role string is discarded\&. If these roles should be used, it will be necessary to use either the
\m[blue]\fBset_roles\fR\m[]\&\s-2\u[70]\d\s+2
or
\m[blue]\fBadd_roles\fR\m[]\&\s-2\u[69]\d\s+2
style modifier with the
\m[blue]\fBSTYLE\fR\m[]\&\s-2\u[96]\d\s+2
directive\&.
.sp .5v
.RE
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBTip\fR
.ps -1
.br
.PP
The authentication procedure described by the
CAS
protocol is notable because the authentication material provided by the user in interactive mode
\fIdoes not flow through \fR\fI\fBDACS\fR\fR; in particular,
\fBDACS\fR
does not see a user\*(Aqs password when this module is used\&. This may be an important consideration in some environments\&.
.PP
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
\fBDACS\fR
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
\fBlocal_cas_authenticate\fR
to perform the
/login
service; then it would prompt and authenticate the user, and redirect the user to a URL provided to it by
\fBlocal_cas_authenticate\fR; then
\fBlocal_cas_authenticate\fR
would call the middleware component directly, this time to perform the
/validate
service\&. The usual flow of control within
\fBDACS\fR
would follow\&.
.PP
A simple script for testing and working with
\fBlocal_cas_authenticate\fR
is available in
src/cas_middleware_test\&.
.sp .5v
.RE
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBTip\fR
.ps -1
.br
.PP
A built\-in version of this module can be selected by using the URL
local_cas_authenticate
or just
cas\&.
.sp .5v
.RE
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBlocal_cert_authenticate\fR
.RS 4
.PP
The
\fBlocal_cert_authenticate\fR
module authenticates a user that supplies an acceptable X\&.509 client certificate via SSL/TLS\&.
\fBApache\fR
must be appropriately configured to request and verify client certificates, check for revocation, and so on (see
\m[blue]\fBSSLVerifyClient\fR\m[]\&\s-2\u[97]\d\s+2
and related directives)\&. As part of the SSL/TLS protocol,
\fBApache\fR\*(Aqs
\m[blue]\fBmod_ssl\fR\m[]\&\s-2\u[80]\d\s+2
module verifies that the client possesses the private key that corresponds to the client certificate\&.
\fBApache\fR
will usually be configured to verify the correctness and suitability of the client certificate\&.
\fBApache\fR
directives such as
\m[blue]\fBSSLRequire\fR\m[]\&\s-2\u[98]\d\s+2
might be used, for example\&.
.PP
The
STYLE
should be configured as
certificate
for this module\&.
.PP
The verification of the client certificate done by
\fBApache\fR
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
\m[blue]\fBmod_ssl\fR\m[]\&\s-2\u[80]\d\s+2
is required, or if it needs to be performed on a system other than where the web server is running,
\fBlocal_cert_authenticate\fR
can execute an external program to decide whether the client certificate is suitable for authentication\&. This program is currently limited to
\m[blue]\fBOpenSSL\fR\m[]\&\s-2\u[99]\d\s+2
but this may be generalized in future versions\&.
.PP
To ensure that
\fBlocal_cert_authenticate\fR
is able to obtain information contained within the client certificate,
\fBApache\fR
must be configured so that
\fBStdEnvVars\fR
and
\fBExportCertData\fR
are enabled in an appropriate
\m[blue]\fBSSLOptions\fR\m[]\&\s-2\u[100]\d\s+2
directive, such as the following:
.sp
.if n \{\
.RS 4
.\}
.nf
SSLOptions +StdEnvVars +ExportCertData
.fi
.if n \{\
.RE
.\}
.PP
The following configuration directives are specific to this module:
.PP
CERT_CA_PATH (Required1)
.RS 4
This is the absolute pathname of a directory that contains trusted certificates\&. Refer to the
\fB\-CApath\fR
argument to
\fBOpenSSL\fR\*(Aqs
verify
command\&.
.RE
.PP
CERT_DUMP_CLIENT (Optional1)
.RS 4
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\&.
.RE
.PP
CERT_NAME_ATTR (Optional1)
.RS 4
If this directive is configured, it gives the name of an
\m[blue]\fBSSL/TLS environment variable\fR\m[]\&\s-2\u[79]\d\s+2\&. The value of that variable is used as a key for the
certnamemap
item type (which must also be configured); the key\*(Aqs 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
\fIUSERNAME\fR
is returned by the module\&.
.sp
To illustrate this, consider the following configuration:
.sp
.if n \{\
.RS 4
.\}
.nf
VFS "[certmap]dacs\-kwv\-fs:/usr/local/dacs/federations/certnamemap"
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"
.fi
.if n \{\
.RE
.\}
.sp
with the file
/usr/local/dacs/federations/certnamemap
containing the two lines:
.sp
.if n \{\
.RS 4
.\}
.nf
Clark Kent:superman
Bruce Wayne:batman
.fi
.if n \{\
.RE
.\}
.sp
Given the configuration above, if the value of the
\fBSSL_CLIENT_S_DN_CN\fR
environment variable is "Clark Kent", the username returned by the module will be "superman"\&.
.sp
As with any module, an expression can be used within an
Auth
clause to modify or override the value returned by a module\&.
.RE
.PP
CERT_OPENSSL_PATH (Optional1)
.RS 4
This is the absolute pathname of the
\fBopenssl\fR
program\&. If not provided, a build\-time value is used (\fIOPENSSL_PATH\fR)\&.
.RE
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBSecurity\fR
.ps -1
.br
.PP
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
\fBDACS\fR
credentials\&. The local authentication service might take this into consideration before granting access and when computing a lifetime for the resulting
\fBDACS\fR
credentials\&.
.sp .5v
.RE
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBlocal_grid_authenticate\fR
.RS 4
.PP
This module works in concert with the
\m[blue]\fBdacsgrid(1)\fR\m[]\&\s-2\u[101]\d\s+2
utility to provide users with one\-time passwords\&. It is also an approximation of the "something you have" factor of two\-factor authentication\&.
.PP
The
STYLE
should be configured as
password
for this module\&.
.PP
Please refer to
\m[blue]\fBdacsgrid(1)\fR\m[]\&\s-2\u[101]\d\s+2
for a complete description\&.
.PP
In addition to the usual
\fIUSERNAME\fR
argument, the module requires the
\fIPASSWORD\fR
argument to be the user\*(Aqs response to the challenge and the
\fIAUXILIARY\fR
argument to be the encoded challenge\&. The latter two arguments must be produced by
\m[blue]\fBdacsgrid(1)\fR\m[]\&\s-2\u[101]\d\s+2\&.
.PP
The following
OPTION
directive values are understood:
.PP
AUTH_GRID_CHALLENGE_SECS (Optional1)
.RS 4
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
\fBdacs_authenticate\fR, the two system clocks must be suitably synchronized\&.
.RE
.PP
AUTH_GRID_LIFETIME_SECS (Optional1)
.RS 4
The length of time, in seconds, for which a grid is valid\&. After this period, all authentication against a grid will fail\&.
.RE
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBTip\fR
.ps -1
.br
.PP
A built\-in version of this module can be selected by using the URL
local_grid_authenticate
or just
grid\&.
.sp .5v
.RE
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBlocal_http_authenticate\fR
.RS 4
.PP
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
\fB200\fR
(see
\m[blue]\fBRFC 2616\fR\m[]\&\s-2\u[43]\d\s+2, 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\&.
.PP
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\&.
.PP
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
\fBDACS\fR\&.
.PP
The
STYLE
should be configured as
password
for this module\&.
.PP
The following
OPTION
directive values are understood:
.PP
AUTH_URL (Required1)
.RS 4
The URL of the web service to invoke, which need not be
\fBDACS\fR\-wrapped\&. It may use either the
http
or
https
scheme\&. No
\fBDACS\fR
credentials will be sent with the request\&.
.RE
.PP
AUTH_METHOD (Optional1)
.RS 4
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\&.
.RE
.PP
PASSWORD_PARAMETER (Optional1)
.RS 4
The name of the argument by which
\fIPASSWORD\fR
is passed to the web service\&. The default is
\fIPASSWORD\fR\&.
.RE
.PP
USERNAME_PARAMETER (Optional1)
.RS 4
The name of the argument by which
\fIUSERNAME\fR
is passed to the web service\&. The default is
\fIUSERNAME\fR\&.
.RE
.PP
USE_AUTH_REPLY (Optional1)
.RS 4
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
\m[blue]\fBauth_reply\&.dtd\fR\m[]\&\s-2\u[84]\d\s+2
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
\m[blue]\fBadd_roles\fR\m[]\&\s-2\u[69]\d\s+2
or
\m[blue]\fBset_roles\fR\m[]\&\s-2\u[70]\d\s+2
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\&.
.RE
.PP
Any other
OPTION
directive values are simply passed to the invoked web service, including any duplicate argument names\&.
.PP
For
\m[blue]\fBGoogle\fR\m[]\&\s-2\u[102]\d\s+2(TM)
\m[blue]\fBaccount authentication\fR\m[]\&\s-2\u[103]\d\s+2, for instance, the following configuration might be used:
.sp
.if n \{\
.RS 4
.\}
.nf
URL "local_http_authenticate"
STYLE "password"
CONTROL "required"
OPTION \*(AqAUTH_URL="https://www\&.google\&.com/accounts/ClientLogin"\*(Aq
OPTION \*(AqUSERNAME_PARAMETER=Email\*(Aq
OPTION \*(AqPASSWORD_PARAMETER=Passwd\*(Aq
OPTION \*(Aqservice=xapi\*(Aq
OPTION "source=DSS\-DACS\-1\&.4"
.fi
.if n \{\
.RE
.\}
.sp
This web service returns an HTTP status code of
\fB200\fR
if the correct username and password are given (i\&.e\&., login succeeded), and
\fB403\fR
if login fails\&. If
\fBClientLogin\fR
fails and requests a CAPTCHA challenge the request will not be passed back to the user\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.PP
One of the reasons for inclusion of this module is to support reuse of accounts widely used by the public\&. Google(TM) provides exactly the right interface needed by systems such as
\fBDACS\fR\&. As of 20\-April\-2012, Google has officially deprecated
\fBClientLogin\fR\&. Accounts provided by
\m[blue]\fBeBay\fR\m[]\&\s-2\u[104]\d\s+2(TM)and
\m[blue]\fBYahoo!\fR\m[]\&\s-2\u[105]\d\s+2\(rg, for instance, do not appear to be directly usable in this way\&. In some cases,
\m[blue]\fBdacs_auth_transfer(8)\fR\m[]\&\s-2\u[8]\d\s+2
may be a better approach than this module\&.
.sp .5v
.RE
.PP
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:
.sp
.if n \{\
.RS 4
.\}
.nf
#! /bin/sh
/bin/cat <
HERE
exit 0
.fi
.if n \{\
.RE
.\}
.sp
Also assume the following
Auth
clause has been configured:
.sp
.if n \{\
.RS 4
.\}
.nf
URL "local_http_authenticate"
STYLE "password,set_roles"
CONTROL "required"
OPTION \*(AqAUTH_URL="http://example\&.com/cgi\-bin/myauth"\*(Aq
OPTION \*(AqAUTH_METHOD=GET\*(Aq
OPTION \*(AqUSE_AUTH_REPLY="YES"\*(Aq
.fi
.if n \{\
.RE
.\}
.sp
Invoking this URL will always successfully authenticate any user and issue credentials for the identity
JUR1:guest
with roles
bigwheel,mediumwheel,littlewheel:
.sp
.if n \{\
.RS 4
.\}
.nf
https://example\&.com/cgi\-bin/dacs/dacs_authenticate?USERNAME=alice&PASSWORD=test&DACS_JURISDICTION=JUR1
.fi
.if n \{\
.RE
.\}
.PP
This
\m[blue]\fBexpression\fR\m[]\&\s-2\u[3]\d\s+2
is equivalent:
.sp
.if n \{\
.RS 4
.\}
.nf
% dacsexpr \-e \*(Aqdacsauth("\-m http passwd,set_roles suff \-OAUTH_URL=http://bsd9\&.dss\&.ca/cgi\-bin/dacs/http_auth \e
\-OAUTH_METHOD=GET \-OUSE_AUTH_REPLY=yes \-u test \-p test")\*(Aq
{"result",1,"identity","DSS::BSD9:guest","roles","bigwheel,mediumwheel,littlewheel"}
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBTip\fR
.ps -1
.br
.PP
A built\-in version of this module can be selected by using the URL
local_http_authenticate
or just
http\&.
.sp .5v
.RE
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBlocal_infocard_authenticate\fR
.RS 4
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBDeprecated\fR
.ps -1
.br
.PP
In early 2011, Microsoft
\m[blue]\fBannounced\fR\m[]\&\s-2\u[106]\d\s+2
that it would not support
\m[blue]\fBCardSpace\fR\m[]\&\s-2\u[107]\d\s+2
(aka, Infocards and Information Cards) starting with
\m[blue]\fBWindows 8\fR\m[]\&\s-2\u[108]\d\s+2\&. CardSpace has been the most widely available identity selector for using Information Cards\&.
.PP
The implementation of Infocards support within
\fBDACS\fR
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
\fBDACS\fR
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\&.
.PP
References:
\m[blue]\fBOn the Demise of CardSpace\fR\m[]\&\s-2\u[109]\d\s+2;
\m[blue]\fBOpen Cardspace opportunity\fR\m[]\&\s-2\u[110]\d\s+2;
\m[blue]\fBPersonal Reflections on the CardSpace Journey\fR\m[]\&\s-2\u[111]\d\s+2;
\m[blue]\fBFrom CardSpace to Verified Claims\fR\m[]\&\s-2\u[112]\d\s+2;
\m[blue]\fBChange will come: the present is untenable\fR\m[]\&\s-2\u[113]\d\s+2;
\m[blue]\fBThe Clay Feet of Giants?\fR\m[]\&\s-2\u[114]\d\s+2;
\m[blue]\fBRIP, Windows CardSpace\&. Hello, U\-Prove\fR\m[]\&\s-2\u[115]\d\s+2; and
\m[blue]\fBU\-Prove\fR\m[]\&\s-2\u[116]\d\s+2\&.
.sp .5v
.RE
.PP
The
\fBlocal_infocard_authenticate\fR
module performs
\fBDACS\fR
authentication using an
\m[blue]\fBInformation Card\fR\m[]\&\s-2\u[62]\d\s+2
(InfoCard) previously registered at the jurisdiction\&. Self\-issued InfoCards are registered using
\m[blue]\fBdacs_infocard(8)\fR\m[]\&\s-2\u[64]\d\s+2
or
\m[blue]\fBdacsinfocard(1)\fR\m[]\&\s-2\u[63]\d\s+2\&. Managed InfoCards are also supported, provided they have been registered using
\m[blue]\fBdacs_managed_infocard(8)\fR\m[]\&\s-2\u[65]\d\s+2
and include a
dacs_identity
claim in the
\fBDACS\fR
namespace\&.
\fBDACS\fR
aims to conform to
\m[blue]\fBIdentity Selector Interoperability Profile (ISIP) 1\&.5\fR\m[]\&\s-2\u[117]\d\s+2\&.
.PP
A
\fBDACS\fR
\m[blue]\fBrole descriptor string\fR\m[]\&\s-2\u[118]\d\s+2
can be associated with a managed InfoCard through the
dacs_roles
claim name in the
\fBDACS\fR
namespace (see
\m[blue]\fBdacs_infocard(8)\fR\m[]\&\s-2\u[119]\d\s+2\&. These roles can be associated with new credentials via the
\m[blue]\fBadd_roles\fR\m[]\&\s-2\u[69]\d\s+2
and
\m[blue]\fBset_roles\fR\m[]\&\s-2\u[70]\d\s+2
modifiers\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBSecurity\fR
.ps -1
.br
.PP
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\&.
.sp .5v
.RE
.PP
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,
\fBlocal_infocard_authenticate\fR
understands an optional argument,
\fITYPE\fR, that may have the value "selfissued" or "managed" to restrict authentication to the corresponding InfoCard type; the default behaviour accepts either type of InfoCard\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBTip\fR
.ps -1
.br
.PP
The
\m[blue]\fBexpression\-based authentication style\fR\m[]\&\s-2\u[120]\d\s+2, 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\&.
.sp .5v
.RE
.PP
For additional information about InfoCards, please refer to:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\m[blue]\fBdacs_managed_infocard(8)\fR\m[]\&\s-2\u[121]\d\s+2,
\m[blue]\fBdacs\&.conf(5)\fR\m[]\&\s-2\u[122]\d\s+2
(the
INFOCARD_
prefixed directives),
\m[blue]\fBdacs_mex(8)\fR\m[]\&\s-2\u[123]\d\s+2, and
\m[blue]\fBdacs_sts(8)\fR\m[]\&\s-2\u[124]\d\s+2\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\m[blue]\fBUsing InfoCards With DACS\fR\m[]\&\s-2\u[125]\d\s+2, Distributed Systems Software (July, 2009)\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\m[blue]\fB\fIIdentity Selector Interoperability Profile specification and companion guides\fR\fR\m[]\&\s-2\u[126]\d\s+2
(August, 2008)\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\m[blue]\fB\fIIntroducing Windows CardSpace\fR\fR\m[]\&\s-2\u[127]\d\s+2
(April, 2006)\&.
.RE
.sp
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBTip\fR
.ps -1
.br
.PP
A built\-in version of this module can be selected by using the URL
local_infocard_authenticate
or just
infocard\&.
.sp .5v
.RE
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBlocal_ldap_authenticate\fR
.RS 4
.PP
The
\fBlocal_ldap_authenticate\fR
module performs
\fBDACS\fR
authentication using the Lightweight Directory Access Protocol, also known as
LDAP, (see
\m[blue]\fBRFC 2251\fR\m[]\&\s-2\u[128]\d\s+2,
\m[blue]\fBRFC 2252\fR\m[]\&\s-2\u[129]\d\s+2,
\m[blue]\fBRFC 2253\fR\m[]\&\s-2\u[130]\d\s+2,
\m[blue]\fBRFC 3377\fR\m[]\&\s-2\u[131]\d\s+2, and many others)\&. This form of authentication can be used with Microsoft\*(Aqs
\m[blue]\fBActive Directory (ADS)\fR\m[]\&\s-2\u[132]\d\s+2\&.
\m[blue]\fBOpenLDAP\fR\m[]\&\s-2\u[133]\d\s+2
is used to supply
LDAP
client support\&.
.PP
The
STYLE
should be configured as
password
for this module\&.
.PP
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
\fBDACS\fR
authentication modules\&. At least a basic familiarity with
LDAP
will be required to configure this module\&.
.PP
The module implements two different approaches to authentication:
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 1." 4.2
.\}
In the
direct
method, which is the simpler and more efficient approach, the
\fIUSERNAME\fR
argument is directly mapped to the corresponding
DN\&. The module binds to that
DN
using the given
\fIPASSWORD\fR\&. If the bind operation succeeds, the user has been authenticated\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 2." 4.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
\fIUSERNAME\fR
argument\&. If the search returns exactly one entry, it binds to that entry\*(Aqs
DN
using the
\fIPASSWORD\fR
argument; if the bind operation succeeds, the user has been authenticated\&.
.RE
.sp
Regardless of the approach, after successful authentication it may be necessary to map the
\fIUSERNAME\fR
or the
DN
into a valid
\fBDACS\fR
username\&.
.PP
The following configuration directives are specific to this module:
.PP
LDAP_ADMIN_PASSWORD (Optional1)
.RS 4
This is the password for the
LDAP
administrator account that corresponds to
LDAP_ADMIN_URL\&.
.RE
.PP
LDAP_ADMIN_URL (Required1\-C)
.RS 4
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\*(Aqs administrator\&. Example:
.sp
.if n \{\
.RS 4
.\}
.nf
LDAP_ADMIN_URL
"ldap://example\&.com/cn=Administrator, cn=Users, dc=example, dc=com"
.fi
.if n \{\
.RE
.\}
.sp
.RE
.PP
LDAP_BIND_METHOD (Required1\-C)
.RS 4
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\&.
.RE
.PP
LDAP_ROLES_SELECTOR* (Optional)
.RS 4
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\*(Aqs 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 (\fI${LDAP::attrname}\fR) and its value (\fI${LDAP::attrvalue}\fR) available\&. All of the entry\*(Aqs 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\&.
.sp
An example:
.sp
.if n \{\
.RS 4
.\}
.nf
LDAP_ROLES_SELECTOR* \*(Aq"${LDAP::attrname}" eq "memberOf" \e
? strtr(ldap(rdn_attrvalue, \e
ldap(dn_index, "${LDAP::attrvalue}", 1)), " ", "_") \e
: ""\*(Aq
.fi
.if n \{\
.RE
.\}
.sp
For each instance of the entry\*(Aqs
memberOf
attribute, this expression selects the least significant (left\-most) component of the attribute value (a
DN) using
\m[blue]\fBldap()\fR\m[]\&\s-2\u[134]\d\s+2
and converts spaces to underscores\&. If the user\*(Aqs entry contains:
.sp
.if n \{\
.RS 4
.\}
.nf
memberOf: CN=Domain Guests,CN=Users,DC=example,DC=com
memberOf: CN=Guests,CN=Builtin,DC=example,DC=com
.fi
.if n \{\
.RE
.\}
.sp
the resulting roles would be
Domain_Guests
and
Guests\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
These roles are discarded unless the
\m[blue]\fBSTYLE\fR\m[]\&\s-2\u[96]\d\s+2
directive for this module allows the roles to be incorporated into the user\*(Aqs credentials\&.
.sp .5v
.RE
.RE
.PP
LDAP_SEARCH_FILTER (Required1\-C)
.RS 4
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\&.
.RE
.PP
LDAP_SEARCH_FILTER* (Required1\-C)
.RS 4
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:
.sp
.if n \{\
.RS 4
.\}
.nf
LDAP_SEARCH_FILTER* \*(Aq"(sAMAccountName=${Args::USERNAME})"\*(Aq
.fi
.if n \{\
.RE
.\}
.sp
.RE
.PP
LDAP_SEARCH_ROOT_DN (Required1\-C)
.RS 4
This is the root
DN
at which the indirect method should begin searching for user entries\&.
.RE
.PP
LDAP_TIMEOUT_SECS (Optional1)
.RS 4
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\&.
.RE
.PP
LDAP_USERNAME_EXPR* (Optional1)
.RS 4
If authentication succeeds, this directive is evaluated to yield the
\fBDACS\fR
username returned to
\fBdacs_authenticate\fR\&. All of the entry\*(Aqs attribute names and values are made available within the
LDAP
namespace\&. If unspecified, the value of the
\fIUSERNAME\fR
parameter is returned\&. Example:
.sp
.if n \{\
.RS 4
.\}
.nf
LDAP_USERNAME_EXPR* \*(Aq"${LDAP::sAMAccountName}"\*(Aq
.fi
.if n \{\
.RE
.\}
.sp
.RE
.PP
LDAP_USERNAME_URL (Optional1)
.RS 4
If the
direct
method is used, either this directive or
\m[blue]\fBLDAP_USERNAME_URL*\fR\m[]\&\s-2\u[135]\d\s+2
(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
\m[blue]\fBRFC 2396\fR\m[]\&\s-2\u[136]\d\s+2
and
\m[blue]\fBRFC 3986\fR\m[]\&\s-2\u[137]\d\s+2) 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\&.
.sp
.if n \{\
.RS 4
.\}
.nf
LDAP_USERNAME_URL
\*(Aq"ldap://example\&.com/cn=Auggie%20Doggie, cn=Users, dc=example, dc=com"\*(Aq
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBSecurity\fR
.ps -1
.br
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\&.
.sp .5v
.RE
.RE
.PP
LDAP_USERNAME_URL* (Optional1)
.RS 4
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:
.sp
.if n \{\
.RS 4
.\}
.nf
LDAP_USERNAME_URL*
\*(Aq"ldap://example\&.com/cn=${Args::USERNAME}, cn=Users, dc=example, dc=com"\*(Aq
.fi
.if n \{\
.RE
.\}
.sp
.RE
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBTip\fR
.ps -1
.br
.PP
Before using
LDAP
authentication with
\fBDACS\fR, you should first make sure that your
LDAP
server is functioning as you expect and that the host that will run the
\fBlocal_ldap_authenticate\fR
module can communicate with the
LDAP
server\&.
.PP
One way to do this is to use the
\m[blue]\fBldapsearch(1)\fR\m[]\&\s-2\u[138]\d\s+2
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
\fBDACS\fR\*(Aqs
LDAP
authentication module (\fBlocal_ldap_authenticate\fR)\&. Some of the information that you obtain from this exercise may be helpful when you configure
\fBDACS\fR
to use this form of authentication\&.
.PP
Here are some examples to try \- you must adapt the names for your environment:
.sp
.if n \{\
.RS 4
.\}
.nf
% \&./ldapsearch \-h win2k\&.example\&.com \-x \-b "dc=example,dc=com" \e
\-D "CN=Administrator,CN=Users,DC=example,DC=com" \-W \-LLL
% \&./ldapsearch \-h win2k\&.example\&.com \-x \-b "dc=example,dc=com" \e
\-D "CN=Auggie Doggie,CN=Users,DC=example,DC=com" \-W \-LLL
% \&./ldapsearch \-h win2k\&.example\&.com \-x \-b "dc=example,dc=com" \e
\-D "CN=Administrator,CN=Users,DC=example,DC=com" \-W \-LLL \e
"(cn=Administrator)" memberOf
% \&./ldapsearch \-h win2k\&.example\&.com \-x \-b "dc=example,dc=com" \e
\-D "CN=Administrator,CN=Users,DC=example,DC=com" \-W \-LLL \e
"(sAMAccountName=auggie)"
.fi
.if n \{\
.RE
.\}
.sp
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
\fB\-D\fR
flag\&.
.sp .5v
.RE
.PP
The following configuration illustrates authentication using this module:
.sp
.if n \{\
.RS 4
.\}
.nf
URL "https://example\&.com/cgi\-bin/dacs/local_ldap_authenticate"
STYLE "password,add_roles"
CONTROL "required"
LDAP_BIND_METHOD "direct"
LDAP_USERNAME_URL* \*(Aq"ldap://windows\&.example\&.com/cn=" \e
\&. encode(url, ${Args::USERNAME}) \&. ",cn=Users,dc=example,dc=com"\*(Aq
LDAP_USERNAME_EXPR* \*(Aq"${LDAP::sAMAccountName}"\*(Aq
LDAP_ROLES_SELECTOR* \*(Aq"${LDAP::attrname}" eq "memberOf" \e
? strtr(ldap(rdn_attrvalue, \e
ldap(dn_index, "${LDAP::attrvalue}", 1)), " ", "_") \e
: 0\*(Aq
.fi
.if n \{\
.RE
.\}
.PP
Here, the
LDAP
authentication module will construct a
DN
by plugging the user\-provided
\fIUSERNAME\fR
argument into the template and binding to that
DN
with the
\fIPASSWORD\fR
argument\&. If successful, the
\fBDACS\fR
username will be the value of the user\*(Aqs entry\*(Aqs
sAMAccountName
attribute, and roles will extracted from the entry\*(Aqs
memberOf
attribute values, as described above\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.PP
In Windows, the
SAM\-Account\-Name
Active Directory attribute value (sAMAccountName) need not be the same as the entry\*(Aqs
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:
.sp
.if n \{\
.RS 4
.\}
.nf
\e / [ ] : ; | = , + * ? < > @ "
.fi
.if n \{\
.RE
.\}
.sp
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\&.
.sp .5v
.RE
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBlocal_native_authenticate\fR
.RS 4
.PP
The
\fBlocal_native_authenticate\fR
module transfers a user\*(Aqs current, context\-dependent web server identity to a
\fBDACS\fR
identity\&. The web server will most likely have used HTTP Basic or Digest authentication (\m[blue]\fBRFC 2617\fR\m[]\&\s-2\u[60]\d\s+2)\&. The user, having already been authenticated by the web server at a particular jurisdiction, will automatically be given
\fBDACS\fR
credentials associated with that jurisdiction and typically having the same username\&.
.PP
The
STYLE
should be configured as
native
for this module\&.
.PP
This method of authentication also depends on a CGI helper program (\m[blue]\fBautologin(8)\fR\m[]\&\s-2\u[139]\d\s+2) and appropriate configuration of
\fBApache\fR
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
\fBApache\fR
method and using any
\fBApache\fR
authentication module)\&. The helper program then invokes
\fBdacs_authenticate\fR
with appropriate arguments; if this module has been enabled and accepts its arguments, the user will be given
\fBDACS\fR
credentials\&.
.PP
There are no directives or options specific to this module\&.
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBlocal_ntlm_authenticate\fR
.RS 4
.PP
The
\fBlocal_ntlm_authenticate\fR
module authenticates users through Windows NT LAN Manager using the NTLM protocol [\m[blue]\fB1\fR\m[]\&\s-2\u[140]\d\s+2,
\m[blue]\fB2\fR\m[]\&\s-2\u[141]\d\s+2]\&. This module, which makes use of
\m[blue]\fBSamba\fR\m[]\&\s-2\u[142]\d\s+2
libraries, provides Windows
\m[blue]\fBNTLM authentication\fR\m[]\&\s-2\u[143]\d\s+2
based on a username and password\&. The module does not need to be (and will not usually be) executed on the host running Windows\&.
.PP
For details, please refer to
\m[blue]\fBNTLM user authentication in Windows\fR\m[]\&\s-2\u[144]\d\s+2\&.
.PP
The
STYLE
should be configured as
password
for this module\&.
.PP
The following
OPTION
directive values are understood:
.PP
SAMBA_SERVER (Required1)
.RS 4
The domain name or IP address in standard dot notation of the Windows system providing NTLM authentication\&.
.RE
.PP
SAMBA_PORT (Optional1)
.RS 4
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\&.
.RE
.PP
SAMBA_DOMAIN (Optional1)
.RS 4
The domain name to use on
SAMBA_SERVER\&. The default is ""\&.
.RE
.PP
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\&.
.PP
The following illustrates how this module might be configured:
.sp
.if n \{\
.RS 4
.\}
.nf
URL "https://example\&.com/cgi\-bin/dacs/local_ntlm_authenticate"
STYLE "pass"
CONTROL "sufficient"
OPTION \*(AqSAMBA_SERVER="10\&.0\&.0\&.123"\*(Aq
OPTION \*(AqSAMBA_PORT="139"\*(Aq
.fi
.if n \{\
.RE
.\}
.PP
Here,
\fBdacs_authenticate\fR
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\&.
.PP
There are no directives specific to this module\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBSecurity\fR
.ps -1
.br
.PP
Attacks against some versions of NTLM
\m[blue]\fBhave been identified\fR\m[]\&\s-2\u[145]\d\s+2\&. Communication between this module and the NTLM service should use a secure channel or at least not be snoopable\&.
.sp .5v
.RE
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBTip\fR
.ps -1
.br
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
A built\-in version of this module can be selected by using the URL
local_ntlm_authenticate
or just
ntlm\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
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,
\fIfrom the machine on which you intend to run this module\fR, 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
\fBDACS\fR
module\&.
.sp
To test whether it is possible to authenticate using a particular username and password, you may be able to use
\m[blue]\fBsmbclient(1)\fR\m[]\&\s-2\u[146]\d\s+2\&. For example, if
C:\eShared
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:
.sp
.if n \{\
.RS 4
.\}
.nf
% smbclient //mywinhost/shared \-U Administrator
.fi
.if n \{\
.RE
.\}
.sp
or to authenticate as the user
bob, try:
.sp
.if n \{\
.RS 4
.\}
.nf
% smbclient //mywinhost/HPLaserJ\-PS \-U bob
.fi
.if n \{\
.RE
.\}
.sp
or to try a more generic "Sharename", try:
.sp
.if n \{\
.RS 4
.\}
.nf
% smbclient //mywinhost/NETLOGON \-U bob
.fi
.if n \{\
.RE
.\}
.sp
or to list available services ("Sharenames"), try:
.sp
.if n \{\
.RS 4
.\}
.nf
% smbclient \-L mywinhost \-U bob
.fi
.if n \{\
.RE
.\}
.sp
In each of these examples, replace
\fImywinhost\fR
with the domain name of your Windows server\&. You should be prompted for the account\*(Aqs password\&. If
\fBsmbclient\fR
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 (type
exit
to leave
\fBsmbclient\fR)\&.
.sp
If
\fBsmbutil\fR
with the
\fBidentity\fR
option happens to be available, try a non\-interactive command like:
.sp
.if n \{\
.RS 4
.\}
.nf
% smbutil identity //bob:bobspassword@mywinhost
.fi
.if n \{\
.RE
.\}
.sp
Before you have configured
\fBDACS\fR, you can test NTLM authentication from the command line using
\m[blue]\fBdacsauth(1)\fR\m[]\&\s-2\u[6]\d\s+2\&. For example, try something like:
.sp
.if n \{\
.RS 4
.\}
.nf
% dacsauth \-m ntlm passwd suff \-OSAMBA_SERVER="windows\&.example\&.com" \-prompt \-u bob
.fi
.if n \{\
.RE
.\}
.sp
Change "bob" to the username you want to authenticate and "windows\&.example\&.com" to the domain name of the Windows machine where the user\*(Aqs account is\&. You may also need to specify
\fISAMBA_PORT\fR
if a non\-standard port is being used\&. You will be prompted for the password for the user\*(Aqs account The program\*(Aqs 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\&.
.sp
After you have configured
\fBDACS\fR, there is another method of testing
\fBlocal_ntlm_authenticate\fR
from the command line\&. Set the environment variable
\fBQUERY_STRING\fR
(using your preferred shell\*(Aqs syntax) to something like this:
.sp
.if n \{\
.RS 4
.\}
.nf
% export QUERY_STRING="USERNAME=bob&PASSWORD=test&DACS_JURISDICTION=Test\e
&SAMBA_SERVER=windows\&.example\&.com"
.fi
.if n \{\
.RE
.\}
.sp
Change "bob" to the username you want to authenticate, "test" to the password for that username, "Test" to the name of the
\fBDACS\fR
jurisdiction that will perform the authentication, and "windows\&.example\&.com" to the domain name of the Windows machine where the user\*(Aqs account is\&. You may also need to specify
\fISAMBA_PORT\fR\&. Then from the distribution\*(Aqs
src
directory:
.sp
.if n \{\
.RS 4
.\}
.nf
% \&./local_ntlm_auth \-uj Test
.fi
.if n \{\
.RE
.\}
.sp
Use the
\fB\-u\fR,
\fB\-uj\fR, or
\fB\-us\fR
flag to specify a jurisdiction that you have configured (see
\m[blue]\fBdacs(1)\fR\m[]\&\s-2\u[147]\d\s+2)\&. 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
\fBQUERY_STRING\fR
environment variable\&.
.RE
.sp .5v
.RE
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBlocal_pam_authenticate\fR
.RS 4
.PP
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
\fBDACS\fR\&. Please refer to
\m[blue]\fBX/Open Single Sign\-On Service (XSSO) \-\- Pluggable Authentication\fR\m[]\&\s-2\u[53]\d\s+2
for additional information about PAM\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNotes\fR
.ps -1
.br
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
The PAM\-based infrastructure described here was mainly developed to allow a system\*(Aqs PAM authentication services to be used for
\fBDACS\fR
web\-based authentication\&. See
src/pamd\&.c
for architectural details\&.
.sp
Although a prototype has been developed, no "native" PAM authentication module for
\fBDACS\fR
is distributed\&. Such a module might be used to provide Unix services with
\fBDACS\fR
authentication and access control functionality, conceptually allowing
\m[blue]\fBdacsauth(1)\fR\m[]\&\s-2\u[6]\d\s+2
or
\m[blue]\fBdacscheck(1)\fR\m[]\&\s-2\u[148]\d\s+2
to be used by them\&. For instance, configuration for
\fBftp\fR
authentication that normally uses
\fBpam_unix\&.so\fR
might be replaced by a reference to the module, leveraging any
password
style of
\fBDACS\fR
authentication, such as
\m[blue]\fBlocal_ldap_authenticate\fR\m[]\&\s-2\u[49]\d\s+2\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
By default, the
\fBpamd\fR
server uses "dacs" as the name of the PAM service policy (see
\m[blue]\fBpam_start(3)\fR\m[]\&\s-2\u[149]\d\s+2)\&. 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
\fBpamd\fR
argument\&.
.RE
.sp .5v
.RE
.PP
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
\fBDACS\fR
authentication modules [\m[blue]\fBGNU/Linux\fR\m[]\&\s-2\u[150]\d\s+2,
\m[blue]\fBFreeBSD\fR\m[]\&\s-2\u[151]\d\s+2,
\m[blue]\fBmacOS\fR\m[]\&\s-2\u[152]\d\s+2]\&. For example,
\m[blue]\fBpam_unix(8)\fR\m[]\&\s-2\u[153]\d\s+2
performs essentially the same authentication function as
\m[blue]\fBlocal_unix_authenticate\fR\m[]\&\s-2\u[154]\d\s+2, except that the latter is not interactive (it does not prompt)\&.
.PP
The
STYLE
should be configured as
prompted
for this module\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.PP
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 "\m[blue]\fBATM\fR\m[]\&\s-2\u[155]\d\s+2
machine" is)\&.
.sp .5v
.RE
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBImportant\fR
.ps -1
.br
.PP
The
\fBlocal_pam_authenticate\fR
module depends on functionality provided by
\m[blue]\fBpamd(8)\fR\m[]\&\s-2\u[156]\d\s+2
running on a PAM\-capable system, which does not need to be the same host where
\fBlocal_pam_authenticate\fR
is run\&. The
\fBlocal_pam_authenticate\fR
module establishes connections with
\fBpamd\fR, which interacts with the
\m[blue]\fBpam(3)\fR\m[]\&\s-2\u[52]\d\s+2
library\&. Unlike the other
\fBDACS\fR
authentication styles, authentication using the
prompted
style may involve more than one request to
\fBdacs_authenticate\fR, each of which supplies additional authentication material\&.
.PP
The
prompted
authentication style implements a
\fIsession\fR
between the user and the PAM library that consists of a sequence of operations that comprise a PAM
\fItransaction\fR\&. For each operation,
\fBdacs_authenticate\fR
(via
\fBlocal_pam_authenticate\fR
and
\fBpamd\fR) 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
\fBdacs_authenticate\fR
in the transaction\*(Aqs next operation\&.
.sp .5v
.RE
.PP
If PAM requires information from the user,
\fBlocal_pam_authenticate\fR
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
\fIFORMAT\fR
argument (see
\m[blue]\fBdacs\&.services(8)\fR\m[]\&\s-2\u[81]\d\s+2)\&. If any XML type is specified, the reply from
\fBdacs_authenticate\fR
will conform to the DTD
\m[blue]\fBdacs_auth_reply\&.dtd\fR\m[]\&\s-2\u[82]\d\s+2\&. If HTML is specified and PAM authentication requires additional information from the user,
\fBdacs_authenticate\fR
will return a rudimentary HTML form that must be completed and submitted by the user\&. For example, if
\fBpam_unix\fR
is configured,
\fBdacs_authenticate\fR
may emit a web page that prompts for a username (if none was provided with the initial invocation of
\fBdacs_authenticate\fR), and after that form has been submitted by the user emit a web page that prompts for a password\&.
.PP
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
\fIservice\fR
argument (see below)\&. The handler is required to obtain values for a set of requested variables and submit them to a given URL (\fBdacs_authenticate\fR)\&. 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 \*(Aq/\*(Aq, that is interpreted relative to the current jurisdiction (i\&.e\&., the
\m[blue]\fBdacs_url\fR\m[]\&\s-2\u[157]\d\s+2
is prepended)\&. Query arguments may be included, provided none of the argument names used by
\fBdacs_authenticate\fR, described below, are duplicated\&.
.PP
The
\fBpamd\fR
server requires the handler to respond within
\fB60\fR
seconds (configured at compile time)\&. The
\fBlocal_pam_authenticate\fR
module requires
\fBpamd\fR
to respond to the initial request with the first prompt within
\fB20\fR
seconds (configured at compile time)\&. Should the handler encounter a serious error, it can simply terminate; this will cause
\fBpamd\fR
to eventually time out, which will abort the PAM transaction\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBSecurity\fR
.ps -1
.br
.PP
The handler does not have to be
\fBDACS\fR\-wrapped, but ideally it should be\&. If it is, don\*(Aqt forget to add an access control rule to grant access to any user that might authenticate through
\fBlocal_pam_authenticate\fR\&.
.sp .5v
.RE
.PP
This "prompter" service might be configured as follows:
.sp
.if n \{\
.RS 4
.\}
.nf
OPTION "PAM_HANDLER_URL=/dacs_pam_handler"
.fi
.if n \{\
.RE
.\}
.sp
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,
\fBdacs_authenticate\fR
adds the following query arguments:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fIservice\fR: This is the URL of the
\fBdacs_authenticate\fR
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
\fIservice\fR\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fICSS_PATH\fR: This is the path configured for HTML stylesheets\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fIAUTH_TRANSID\fR: 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
\fIAUTH_TRANSID\fR\&. The handler is not required to retain state between these calls, but it may do so\&. The handler must pass this argument when calling
\fIservice\fR\&. Although the lifetime of this identifier is relatively brief, it should be kept private by the handler\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fIauth_prompt_var_prefix\fR: Each requested value will be identified by an argument to
\fIservice\fR
having this prefix, with a positive integer (\fIint\fR, which is assigned consecutive integers starting with
\fB1\fR) appended\&. For instance, if
\fIauth_prompt_var_prefix\fR
is "AUTH_PROMPT_VAR", then the handler must submit the requested values as
\fIAUTH_PROMPT_VAR1\fR,
\fIAUTH_PROMPT_VAR2\fR, and so on\&. The first absent
\fIint\fR
value signals the end of the variable argument list\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fITYPE\fR\fI\fIint\fR\fR: This is the type ("text", "password", or "error") of the variable numbered
\fIint\fR\&. The
password
type indicates the value should not be displayed during user input\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fILABEL\fR\fI\fIint\fR\fR: This argument, which is optional, indicates a label that might be displayed beside the user prompt (e\&.g\&., "Username?") for variable
\fIint\fR\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fINAME\fR\fI\fIint\fR\fR: If this argument is not present for a given
\fIint\fR, then no value is required for this variable \- presumably
\fILABEL\fR\fI\fIint\fR\fR
is informational\&. If
\fINAME\fR\fI\fIint\fR\fR
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
\fITYPE2\fR
as "text",
\fILABEL2\fR
as "Login:", and
\fINAME2\fR
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
\fIservice\fR
there should be a variable named
\fIAUTH_PROMPT_VAR2\fR
with the value "Auggie"\&.
.RE
.sp
Any other arguments to the handler should be forwarded to
\fIservice\fR
verbatim\&. Such arguments include
\fIDACS_VERSION\fR,
\fIDACS_JURISDICTION\fR,
\fIDACS_BROWSER\fR, and
\fIENABLE_AUTH_HANDLERS\fR\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.PP
For testing purposes, it may be helpful to set
PAM_HANDLER_URL
to
\fBdacs_prenv\fR, which will display the arguments passed to the handler and other context\&. The
\fBDACS\fR
distribution includes an example handler,
html/handlers/dacs_pam_handler\&.
.sp .5v
.RE
.PP
If an HTML form is emitted, its appearance can be customized somewhat through the default stylesheet
\m[blue]\fBlocal_pam_authenticate\&.css\fR\m[]\&\s-2\u[158]\d\s+2\&. 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:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
header: Initial HTML to emit instead of the default\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
prologue: HTML to emit immediately after the header\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
instructions: HTML to emit immediately after the prologue and before the form\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
form: Additional HTML to emit within the form\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
epilogue: HTML to emit immediately after the form\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
trailer: Final HTML to emit instead of the default\&.
.RE
.sp
For example, consider the configuration directive:
.sp
.if n \{\
.RS 4
.\}
.nf
VFS "[local_pam_authenticate]dacs\-fs:${Conf::DACS_HOME}/pam_auth"
.fi
.if n \{\
.RE
.\}
.sp
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\&.
.PP
Customization of the HTML form is possible using configuration variables:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fIprompt_submit_label\fR: the text label to put in the form\*(Aqs submit button\&.
.RE
.sp
For example, the submit button\*(Aqs text can be specified using the directive:
.sp
.if n \{\
.RS 4
.\}
.nf
EVAL ${Conf::prompt_submit_label} = " Continue "
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBTip\fR
.ps -1
.br
.PP
A built\-in version of this module can be selected by using the URL
local_pam_authenticate
or just
pam\&.
.sp .5v
.RE
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBlocal_passwd_authenticate\fR
.RS 4
.PP
The
\fBlocal_passwd_authenticate\fR
module provides support for
\fBDACS\fR
identities, strictly private to
\fBDACS\fR, through password\-protected accounts (similar to what
\fBApache\fR\*(Aqs
\m[blue]\fB\fBmod_authn_file\fR\fR\m[]\&\s-2\u[86]\d\s+2
and
\m[blue]\fB\fBmod_authn_dbm\fR\fR\m[]\&\s-2\u[88]\d\s+2
modules do, along with the
\m[blue]\fBhtpasswd(1)\fR\m[]\&\s-2\u[89]\d\s+2
utility)\&. A secure hash of a password is stored rather than the plaintext password itself\&. Several hashing methods are available (see
\m[blue]\fBPASSWORD_DIGEST\fR\m[]\&\s-2\u[159]\d\s+2)\&.
.PP
The
\fBlocal_passwd_authenticate\fR
module performs authentication by consulting the
\fIUSERNAME\fR
and
\fIPASSWORD\fR
parameters and comparing them to the information previously stored by the administrator\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBSecurity\fR
.ps -1
.br
.PP
This module always requires the
\fIPASSWORD\fR
argument and will not accept the empty string as a password value (even if that actually is the password)\&. Use
\m[blue]\fBlocal_simple_authenticate\fR\m[]\&\s-2\u[67]\d\s+2
for password\-less accounts\&.
.sp .5v
.RE
.PP
The
STYLE
should be configured as
password
for this module\&.
.PP
The
\m[blue]\fBdacspasswd(1)\fR\m[]\&\s-2\u[160]\d\s+2
utility is used to manage these accounts\&. The item type is "passwds"\&.
.PP
The following example configuration, which reflects typical usage, maintains user and password information in a plain text file named
/usr/local/dacs/federations/passwd\&.
.sp
.if n \{\
.RS 4
.\}
.nf
VFS "[passwds]dacs\-kwv\-fs:/usr/local/dacs/federations/passwd"
.fi
.if n \{\
.RE
.\}
.PP
There are no directives or options specific to this module\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.PP
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"\&.
.sp .5v
.RE
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBTip\fR
.ps -1
.br
.PP
A built\-in version of this module can be selected by using the URL
local_passwd_authenticate
or just
passwd\&.
.sp .5v
.RE
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBlocal_radius_authenticate\fR
.RS 4
.PP
The
\fBlocal_radius_authenticate\fR
module supports authentication using RADIUS (Remote Authentication Dial In User Service)\&. The module, acting as a RADIUS client, contacts a RADIUS server to validate the
\fIUSERNAME\fR
and
\fIPASSWORD\fR
parameters it is given\&. For details, refer to
\m[blue]\fBRFC 2865\fR\m[]\&\s-2\u[161]\d\s+2
(also
\m[blue]\fBRFC 2866\fR\m[]\&\s-2\u[162]\d\s+2,
\m[blue]\fBRFC 3162\fR\m[]\&\s-2\u[163]\d\s+2,
\m[blue]\fBRFC 3579\fR\m[]\&\s-2\u[164]\d\s+2,
\m[blue]\fBRFC 6929\fR\m[]\&\s-2\u[165]\d\s+2, and others)\&.
.PP
The
STYLE
should be configured as
password
for this module\&.
.PP
The following
OPTION
directive values are understood:
.PP
RADIUS_SERVER (Required1)
.RS 4
The fully qualified domain name or IP address in standard dot notation of the RADIUS server to use to validate a username/password pair\&.
.RE
.PP
RADIUS_PORT (Optional1)
.RS 4
The port number to use on
RADIUS_SERVER\&. The default is
0, which tells the RADIUS client library to use the network service
radius/udp, which should be defined as port
1812\&.
.RE
.PP
RADIUS_SECRET (Required1)
.RS 4
This string is a password that is shared between the RADIUS server and the module\&. It is used to create a keyed message digest of a user\*(Aqs password, which is transmitted from the module to the RADIUS server, and must therefore be kept private\&. A string length of at least 16 bytes is recommended; the RADIUS protocol uses up to the first 128 bytes\&.
.RE
.PP
RADIUS_OK_MSG (Optional1)
.RS 4
If authentication is successful, a RADIUS server may be configured to include an arbitrary text string (Reply\-Message) in its reply to the module\&. If this option is configured, the RADIUS server must return a message that matches this string case\-insensitively, otherwise authentication will fail\&.
.RE
.PP
RADIUS_TIMEOUT (Optional1)
.RS 4
The module may wait up to this many seconds (as an integer greater than zero) to receive a reply from the RADIUS server\&. The default is
\fB3\fR
seconds\&.
.RE
.PP
RADIUS_DEAD_TIME (Optional1)
.RS 4
A non\-negative integer number of seconds for the module to delay following each unsuccessful authentication attempt\&. This is separate from any other similar delay that might be configured, such as
\m[blue]\fBAUTH_FAIL_DELAY_SECS\fR\m[]\&\s-2\u[75]\d\s+2\&. The default is
\fB2\fR
seconds\&.
.RE
.PP
RADIUS_MAX_TRIES (Optional1)
.RS 4
The number of times, as an integer greater than zero, that the module should attempt to perform authentication with the RADIUS server before reporting failure\&. The default value is
\fB3\fR\&.
.RE
.PP
The following illustrates how this module might be configured:
.sp
.if n \{\
.RS 4
.\}
.nf
URL "https://example\&.com/cgi\-bin/dacs/local_radius_authenticate"
STYLE "passwd"
CONTROL "sufficient"
OPTION \*(AqRADIUS_SERVER=10\&.0\&.0\&.123\*(Aq
OPTION \*(AqRADIUS_PORT=0\*(Aq
OPTION \*(AqRADIUS_SECRET=ASecretRadiusPassweird\*(Aq
OPTION \*(AqRADIUS_OK_MSG="OK DACS\&."\*(Aq
OPTION \*(AqRADIUS_TIMEOUT=2\*(Aq
OPTION \*(AqRADIUS_DEAD_TIME=4\*(Aq
OPTION \*(AqRADIUS_MAX_TRIES=3\*(Aq
.fi
.if n \{\
.RE
.\}
.PP
With this configuration,
\fBdacs_authenticate\fR
will invoke the RADIUS authentication module at the given URL, which will try to authenticate the username and password given to it by asking the RADIUS server at the default port (1812) on the host at
10\&.0\&.0\&.123\&. The module authenticates itself to the RADIUS server using the password "ASecretRadiusPassweird"\&. If authentication is successful, the module expects the RADIUS server to include the message "OK DACS\&." in its reply\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNotes\fR
.ps -1
.br
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
This authentication module is currently tested against authentication services provided by
\m[blue]\fBFreeRADIUS\fR\m[]\&\s-2\u[166]\d\s+2
Version 3\&.0\&.13, which includes the
\m[blue]\fBradiusd(8)\fR\m[]\&\s-2\u[167]\d\s+2
daemon\&. Consult your RADIUS server documentation for information about configuring your server and testing it with this module or
\m[blue]\fBdacsauth(1)\fR\m[]\&\s-2\u[6]\d\s+2
(the latter being a better way to begin)\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
RADIUS message traffic is not encrypted, but plaintext passwords are not transmitted: a weak degree of security is provided by employing one\-way MD5 hashes\&. As when deploying a Network Access Server as a RADIUS client, network communication between this module and a RADIUS server should be configured carefully\&. Consult the RFCs for details regarding security vulnerabilities in RADIUS\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
The RADIUS protocol uses UDP, not TCP and not SSL/TLS\&. See
\m[blue]\fBRFC 6614\fR\m[]\&\s-2\u[168]\d\s+2\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Note that firewall rules may need to be modified to allow RADIUS communication\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
The module is implemented using the BSD\-style
\m[blue]\fBlibradius(3)\fR\m[]\&\s-2\u[169]\d\s+2
client API\&. At build time, the system
libradius
library can be requested, if available, otherwise a portable implementation of that library that is supplied with
\fBDACS\fR
is used\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
The module implements simple account validation but does not fully support RADIUS client functionality, such as the ability to contact multiple RADIUS servers, attach specific attributes to client messages, or perform an interactive dialog during authentication (e\&.g\&., prompting)\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Some systems may have a PAM module for RADIUS authentication (pam_radius), which might be available through
\m[blue]\fBlocal_pam_authenticate\fR\m[]\&\s-2\u[39]\d\s+2\&.
.RE
.sp .5v
.RE
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBTip\fR
.ps -1
.br
.PP
A built\-in version of this module can be selected by using the URL
local_radius_authenticate
or just
radius\&.
.sp .5v
.RE
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBlocal_simple_authenticate\fR
.RS 4
.PP
The
\fBlocal_simple_authenticate\fR
module supports
\fBDACS\fR
identities, strictly private to
\fBDACS\fR, through accounts that are
\fInot\fR
password\-protected\&. The
\fBlocal_simple_authenticate\fR
module performs authentication by looking up an account named by the
\fIUSERNAME\fR
argument\&. In typical use, the username will be an email address, account or membership number, or random character string\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBSecurity\fR
.ps -1
.br
.PP
This form of authentication is
\fIinherently insecure\fR
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\&.
.sp .5v
.RE
.PP
The
STYLE
should be configured as
simple
for this module\&.
.PP
The
\m[blue]\fBdacspasswd(1)\fR\m[]\&\s-2\u[160]\d\s+2
utility is used to manage these accounts\&. The item type is "simple"\&.
.PP
The following example configuration, which reflects typical usage, maintains user account information in a plain text file named
/usr/local/dacs/federations/simple_accounts\&.
.sp
.if n \{\
.RS 4
.\}
.nf
VFS "[simple]dacs\-kwv\-fs:/usr/local/dacs/federations/simple_accounts"
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.PP
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\&.
.sp .5v
.RE
.PP
There are no directives or options specific to this module\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBTip\fR
.ps -1
.br
.PP
A built\-in version of this module can be selected by using the URL
local_simple_authenticate
or just
simple\&.
.sp .5v
.RE
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBlocal_tgma_authenticate\fR
.RS 4
.PP
\fIExperimental\fR\&. The
\fBlocal_tgma_authenticate\fR
module, together with a TGMA server and client
\fIvalidator\fR
software, implements strong, interactive mutual authentication without the user having to input a password\&. The
\fBlocal_tgma_authenticate\fR
module supports
\fBDACS\fR
identities that are strictly private to
\fBDACS\fR\&.
.PP
The user begins the authentication procedure by using a simple sign\-on page to submit an identity (\fIUSERNAME\fR
and
\fIJURISDICTION\fR)\&. 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\*(Aqs identity at the jurisdiction\&.
.PP
This authentication module sends an authentication request message to a TGMA server\&. The TGMA server executes an authentication protocol with a user\*(Aqs
\fIvalidator\fR
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 (\m[blue]\fBRFC 2945\fR\m[]\&\s-2\u[170]\d\s+2,
\m[blue]\fBRFC 5054\fR\m[]\&\s-2\u[171]\d\s+2), verifies the user\*(Aqs identity using account information available to the module, TGMA server, and the validator\&. The user\*(Aqs 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\*(Aq validator devices and instances of this authentication module\&. In a larger organization it will likely run on a firewall or DMZ\-located server\&.
.PP
The
STYLE
should be configured as
tgma
for this module\&.
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBlocal_token_authenticate\fR
.RS 4
.PP
This module works in concert with the
\m[blue]\fBdacstoken(1)\fR\m[]\&\s-2\u[172]\d\s+2
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
\m[blue]\fBRFC 4226\fR\m[]\&\s-2\u[173]\d\s+2, which has been adopted by
\m[blue]\fBOATH\fR\m[]\&\s-2\u[174]\d\s+2, and other standards\&. Please refer to
\m[blue]\fBdacstoken(1)\fR\m[]\&\s-2\u[172]\d\s+2
for complete details\&.
.PP
The
STYLE
should be configured as
password
for this module\&.
.PP
In addition to the usual
\fIUSERNAME\fR
argument, the module requires the
\fIPASSWORD\fR
argument to be the next one\-time password (e\&.g\&., the value produced by the user\*(Aqs hardware token)\&. If the user\*(Aqs
\fBDACS\fR
account has a
PIN
associated with it, the
PIN
must be passed as the
\fIAUXILIARY\fR
argument\&. The
PIN
referred to here is the one managed by
\fBdacstoken\fR, not a
PIN
that may be entered into the token device to unlock it\&.
.PP
One\-time password generation depends on a secret that is shared between the client and
\fBDACS\fR, and a non\-repeating value that may be based on synchronized counters or clocks\&. The client\*(Aqs token can become unsynchronized with the server\*(Aqs 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\*(Aqs token from the server\*(Aqs state; that is, provided the client\*(Aqs password falls within a window of
\fIN\fR
from the one expected by
\fBDACS\fR,
\fBDACS\fR
will accept the client\*(Aqs token\&. For counter\-based tokens, only the "forward" side of the window is examined, so
\fBDACS\fR
can "catch up" to the client\&.
.PP
If the user\*(Aqs password does not fall within the window, it is deemed to have become unsynchronized with
\fBlocal_token_authenticate\fR
and authentication will fail\&. The user can attempt to resynchronize by entering a sequence of passwords as
\fIPASSWORD\fR, 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\*(Aqs account information is corrected and the module also reports successful authentication\&. If synchronization fails, the module also fails and a
\fBDACS\fR
administrator must be contacted to resynchronize the token\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.PP
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\&.
.sp .5v
.RE
.PP
The following
OPTION
directive value is understood:
.PP
ACCEPT_WINDOW (Optional1)
.RS 4
The (non\-negative) size of the acceptance window for one\-time passwords, overriding the default\&. If the size is zero,
\fBDACS\fR
will only consider a match with the expected password and will not try to match the user\*(Aqs password against "nearby" passwords\&. With some modes of operation, only forward matches are allowed\&.
.RE
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBTip\fR
.ps -1
.br
.PP
A built\-in version of this module can be selected by using the URL
local_token_authenticate
or just
token\&.
.sp .5v
.RE
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBlocal_unix_authenticate\fR
.RS 4
.PP
The
\fBlocal_unix_authenticate\fR
module implements native
Unix
username/password authentication, allowing a user having a pre\-existing
Unix
account to be authenticated by
\fBDACS\fR
using the username and password for that account\&. Normally, the user\*(Aqs hashed password is compared to the string obtained by hashing the
\fIPASSWORD\fR
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
\m[blue]\fBpam(3)\fR\m[]\&\s-2\u[175]\d\s+2
library is available, a simple PAM policy is used to validate the plaintext password provided\&.
.PP
In the password comparison algorithm, the
\m[blue]\fBgetpwnam(3)\fR\m[]\&\s-2\u[176]\d\s+2
library function is passed the
\fIUSERNAME\fR
parameter given to
\fBdacs_authenticate\fR\&. It can be configured for systems with or without shadow passwords\&. On some
Unix
systems, when the
\m[blue]\fByp(8)\fR\m[]\&\s-2\u[177]\d\s+2
password database is enabled, the
\m[blue]\fBgetpwnam(3)\fR\m[]\&\s-2\u[176]\d\s+2
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
\fIPASSWORD\fR
parameter is validated\&.
.PP
In the PAM\-based algorithm, the
\fIUSERNAME\fR
and
\fIPASSWORD\fR
parameters given to
\fBdacs_authenticate\fR
are passed to the PAM module (e\&.g\&.,
\m[blue]\fBpam_unix(8)\fR\m[]\&\s-2\u[153]\d\s+2) that has been configured by an administrator\&. This method is separate and much simpler than what is provided by
\m[blue]\fBlocal_pam_authenticate\fR\m[]\&\s-2\u[39]\d\s+2\&. 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\&.
.PP
The
STYLE
should be configured as
password
for this module\&.
.PP
The following
OPTION
directive values are understood:
.PP
PAM_SERVICE (Optional1)
.RS 4
This is the name of the PAM
\fIservice policy\fR
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:
.sp
.if n \{\
.RS 4
.\}
.nf
auth required pam_unix\&.so no_warn
.fi
.if n \{\
.RE
.\}
.sp
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:
.sp
.if n \{\
.RS 4
.\}
.nf
auth required pam_opendirectory\&.so
.fi
.if n \{\
.RE
.\}
.sp
To use that file with this module, the following
\fBDACS\fR
configuration directive would be placed in the appropriate
Auth
clause:
.sp
.if n \{\
.RS 4
.\}
.nf
OPTION "PAM_SERVICE=chkpasswd"
.fi
.if n \{\
.RE
.\}
.sp
See
\m[blue]\fBpam_start(3)\fR\m[]\&\s-2\u[149]\d\s+2
and
\m[blue]\fBpam\&.conf(5)\fR\m[]\&\s-2\u[178]\d\s+2\&.
.sp
Depending on the operating system, PAM modules might be found in
/usr/lib,
/usr/lib/pam, or
/lib/security\&.
.sp
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\&.
.RE
.PP
USE_PAM (Optional1)
.RS 4
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\&.
.RE
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBTip\fR
.ps -1
.br
.PP
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,
\fBdacs_authenticate\fR
must be setuid
root, and if the web\-based version is used,
\fBlocal_unix_authenticate\fR
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\&.
.sp .5v
.RE
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.PP
On platforms where encrypted passwords are unavailable, such as
macOS, authentication will always fail unless the PAM\-based algorithm is available and enabled\&.
.sp .5v
.RE
.RE
.SS "Roles"
.PP
Each user authenticated by
\fBDACS\fR
may be associated with one or more
roles\&. The
\m[blue]\fBsyntax of roles and role descriptors\fR\m[]\&\s-2\u[14]\d\s+2
is described elsewhere\&. Role\-based group membership is discussed in
\m[blue]\fBdacs\&.groups(5)\fR\m[]\&\s-2\u[179]\d\s+2\&. 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\&.
.PP
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
\fBdacs_authenticate\fR
to return roles\&. A roles service returns a
roles_reply
element (see
\m[blue]\fBroles_reply\&.dtd\fR\m[]\&\s-2\u[180]\d\s+2)\&.
.PP
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\*(Aqs
Jurisdiction
section\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.PP
A maximum limit is imposed on the length of a role descriptor string\&. Please refer to the
\m[blue]\fBROLE_STRING_MAX_LENGTH\fR\m[]\&\s-2\u[181]\d\s+2
directive\&.
.sp .5v
.RE
.SS "Roles Clause Directives"
.PP
The roles directives are largely analogous to the authentication directives\&.
.PP
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\*(Aqs roles:
\fIDACS_USERNAME\fR,
\fIDACS_IDENTITY\fR,
\fIDACS_JURISDICTION\fR, and
\fIDACS_VERSION\fR\&.
.PP
\fBRoles Clause Directives Index:\fR
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 1." 4.2
.\}
EXIT* (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 2." 4.2
.\}
EXPR (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 3." 4.2
.\}
INIT* (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 4.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 4." 4.2
.\}
OPTION (Optional)
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 5.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 5." 4.2
.\}
OPTION* (Optional)
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 6.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 6." 4.2
.\}
PREDICATE (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 7.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 7." 4.2
.\}
URL (Optional1)
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 8.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 8." 4.2
.\}
URL* (Optional1)
.RE
.PP
URL (Optional1)
.br
URL* (Optional1)
.RS 4
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\&.
.RE
.PP
INIT* (Optional1)
.RS 4
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\&.
.RE
.PP
EXIT* (Optional1)
.RS 4
If authentication is successful, this expression is evaluated immediately after the module is executed or
EXPR
evaluated\&.
.RE
.PP
EXPR (Optional1)
.RS 4
This directive gives an expression that is evaluated to obtain roles instead of invoking a roles module\&. Please refer to Advanced Techniques\&.
.RE
.PP
OPTION (Optional)
.RS 4
Similar to the
Auth
clause\*(Aqs
\m[blue]\fBOPTION\fR\m[]\&\s-2\u[50]\d\s+2
directive, this is used to pass an argument to the roles module\&. A given
\fIname\fR
may not be specified more than once within a particular
Roles
clause\&. The
Options
namespace is initialized with
\fIDACS_USERNAME\fR,
\fIDACS_JURISDICTION\fR, and
\fIDACS_VERSION\fR
variables\&. If these are specified by an
OPTION, the argument ordinarily used will be overridden\&.
.sp
For example:
.sp
.if n \{\
.RS 4
.\}
.nf
OPTION "PASSWORD=bobo"
.fi
.if n \{\
.RE
.\}
.sp
causes
PASSWORD=bobo
to be passed as a
POST
method parameter\&.
.RE
.PP
OPTION* (Optional)
.RS 4
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
\fIname\fR=\fIvalue\fR
pair, as with the
OPTION
directive, and overrides any
\fIname\fR
in the
Options
namespace\&.
.RE
.PP
PREDICATE (Optional1)
.RS 4
If provided, this expression is evaluated before any other roles module processing is done\&. If there is an evaluation error or it returns
\fBFalse\fR
(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\&.
.RE
.SS "Roles Clause Control Flow"
.PP
If authentication succeeds,
Roles
clauses are processed in which they appear, but only if
\m[blue]\fBset_roles\fR\m[]\&\s-2\u[70]\d\s+2
has not been specified for some authentication module\*(Aqs
STYLE\&.
.PP
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
\fI${Auth::CURRENT_ROLES}\fR
and
\fI${Auth::LAST_ROLES}\fR
are initialized to the role string, if any, obtained during authentication module processing\&. Processing of each
Roles
clause proceeds as follows:
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 1." 4.2
.\}
If the clause has a
PREDICATE
directive, it is evaluated in the current context\&. If the value is not
\fBTrue\fR
the clause is not evaluated further\&. No variables are updated\&. If the expression was invalid, processing of roles is terminated\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 2." 4.2
.\}
If the clause has an
INIT*
directive, it is evaluated; if an error occurs, processing of roles is terminated\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 3." 4.2
.\}
If the clause has a
URL*
directive, it is evaluated to obtain the URL of the
\fBDACS\fR
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\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 4.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 4." 4.2
.\}
If a roles service has been specified, it is invoked\&. If an error occurs, roles processing
\fIcontinues as if the module returned the empty string for the role string\fR\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 5.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 5." 4.2
.\}
The variable
\fI${Auth::LAST_ROLES}\fR
is set to the roles string returned by the module or expression\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 6.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 6." 4.2
.\}
If the clause has an
EXIT*
directive, it is evaluated; if an error occurs, processing of roles is terminated\&. The value of
\fI${Auth::LAST_ROLES}\fR
becomes the role string returned by the clause\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 7.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 7." 4.2
.\}
The role string returned by the clause is appended to the variable
\fI${Auth::CURRENT_ROLES}\fR\&.
.RE
.PP
The value of
\fI${Auth::CURRENT_ROLES}\fR
when the last module has been processed is the roles string that will be used in the generated credentials\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBTip\fR
.ps -1
.br
.PP
Some roles modules are available as built\-in components of
\fBdacs_authenticate\fR\&. These modules are identified by specific relative URLs; a module\*(Aqs 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
\fBdacsauth\fR\&.
.PP
Although it will be more efficient (and possibly more secure) to use a built\-in module, they are executed on the same host as
\fBdacs_authenticate\fR
(thereby giving up some flexibility), access control rules are not applied to them (other than the one for
\fBdacs_authenticate\fR), and
\fBdacs_authenticate\fR
may need to be executed setuid (probably as
root) or setgid (as
www, for example) so that it can access password files\&.
.sp .5v
.RE
.SS "Roles Modules"
.PP
If and only if authentication succeeds,
\fBDACS\fR
can request the user\*(Aqs role descriptor from the jurisdiction\&. Roles modules are always invoked using the
POST
method and are passed the following arguments:
.PP
\fIDACS_USERNAME\fR
.RS 4
The
\fIusername\fR
component of the user\*(Aqs
\fBDACS\fR
identity\&.
.RE
.PP
\fIDACS_JURISDICTION\fR
.RS 4
The name of the jurisdiction that authenticated
\fIDACS_USERNAME\fR\&.
.RE
.PP
\fIDACS_VERSION\fR
.RS 4
The
DACS_VERSION_NUMBER
for this version of
\fBdacs_authenticate\fR\&.
.RE
.PP
OPTION directives
.RS 4
For each
\m[blue]\fBOPTION directive\fR\m[]\&\s-2\u[182]\d\s+2
or
\m[blue]\fBOPTION* directive\fR\m[]\&\s-2\u[183]\d\s+2
in the
Roles
section being processed, the variable name and its value are passed\&.
.RE
Any of the standard web service arguments will also be accepted; anything else will be ignored\&.
.PP
Roles modules return an
\m[blue]\fBroles_reply\&.dtd\fR\m[]\&\s-2\u[180]\d\s+2
document to
\fBdacs_authenticate\fR\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.PP
Although there is a roles module for obtaining
LDAP
or
ADS
roles, you may also get them by authenticating through
\m[blue]\fBlocal_ldap_authenticate\fR\m[]\&\s-2\u[49]\d\s+2
or by using a
Roles
clause with an appropriate
EXPR
directive\&.
.sp .5v
.RE
.PP
\fBRoles Module Index:\fR
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 1." 4.2
.\}
local_roles: Private
\fBDACS\fR
roles
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 2." 4.2
.\}
local_ldap_roles: Roles imported from an
LDAP/ADS directory
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 3." 4.2
.\}
local_unix_roles: Roles imported from
Unix
group membership
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBlocal_roles\fR
.RS 4
.PP
This roles service consults a private list to obtain a username\-to\-roles mapping using
\fBDACS\fR
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\&.
.sp
.if n \{\
.RS 4
.\}
.nf
VFS "[roles]dacs\-kwv\-fs:/usr/local/dacs/federations/roles"
.fi
.if n \{\
.RE
.\}
.sp
The file
/usr/local/dacs/federations/roles
might look something like this:
.sp
.if n \{\
.RS 4
.\}
.nf
admin:dacs,admin
rick:metalogic,guests
bobo:staff,users
auggie:staff,users
.fi
.if n \{\
.RE
.\}
.PP
Here, user
auggie
is associated with the roles
staff
and
users\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBTip\fR
.ps -1
.br
.PP
A built\-in version of this module can be selected by using the URL
local_roles
or just
roles\&.
.sp .5v
.RE
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBlocal_ldap_roles\fR
.RS 4
.PP
This roles service returns roles derived from the attributes of a user\*(Aqs
LDAP/ADS directory entry\&. This module is based on
\m[blue]\fBlocal_ldap_authenticate\fR\m[]\&\s-2\u[49]\d\s+2; please consult the description and examples presented with that authentication module for additional information\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.PP
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\&.
.sp .5v
.RE
.PP
The following configuration directives are recognized by this module\&. They function identically to the directives of the same name used by
\m[blue]\fBlocal_ldap_authenticate\fR\m[]\&\s-2\u[49]\d\s+2, so for the most part their descriptions will not be repeated here\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.PP
These module directives must be passed using either
\m[blue]\fBOPTION\fR\m[]\&\s-2\u[182]\d\s+2
or
\m[blue]\fBOPTION*\fR\m[]\&\s-2\u[183]\d\s+2
directives\&. Ensure that the option value is properly quoted\&.
.sp .5v
.RE
.PP
LDAP_BIND_METHOD (Required1\-C)
.RS 4
This tells the module how to find the user\*(Aqs entry in the directory\&.
.RE
.PP
LDAP_USERNAME_URL (Optional1)
.br
LDAP_USERNAME_URL* (Optional1)
.RS 4
With the
direct
method, one of these options is used to name the user\*(Aqs entry as a URI\&.
.RE
.PP
LDAP_ADMIN_URL (Required1\-C)
.RS 4
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\&.
.RE
.PP
LDAP_ADMIN_PASSWORD (Optional1)
.RS 4
This is the password for the
LDAP
administrator account that corresponds to
LDAP_ADMIN_URL\&.
.RE
.PP
LDAP_SEARCH_ROOT_DN (Required1\-C)
.RS 4
This is the root
DN
at which the
indirect
method should begin searching for user entries\&.
.RE
.PP
LDAP_SEARCH_FILTER (Required1\-C)
.br
LDAP_SEARCH_FILTER* (Required1\-C)
.RS 4
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
\fBDACS\fR
username obtained from the preceding authentication phase can be referenced as
\fI${Args::DACS_USERNAME}\fR\&.
.RE
.PP
LDAP_USERNAME_EXPR* (Optional1)
.RS 4
This option is evaluated to yield a username that can be referenced by the
LDAP_ROLES_SELECTOR*
option as
\fI${LDAP::USERNAME}\fR\&.
.RE
.PP
LDAP_ROLES_SELECTOR* (Optional)
.RS 4
Each occurrence of this directive specifies an expression that is evaluated by iterating through each attribute of the entry and making the attribute name (\fI${LDAP::attrname}\fR) and its value (\fI${LDAP::attrvalue}\fR) available\&. All of the entry\*(Aqs 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\&.
.RE
.PP
LDAP_TIMEOUT_SECS (Optional1)
.RS 4
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\&.
.RE
.PP
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:
.sp
.if n \{\
.RS 4
.\}
.nf
URL "http://example\&.com/cgi\-bin/dacs/local_ldap_roles"
OPTION "LDAP_BIND_METHOD=indirect"
OPTION \e
\*(AqLDAP_ADMIN_URL="ldap://x\&.example\&.com/CN=Administrator,CN=Users,DC=example,DC=com"\*(Aq
OPTION \*(AqLDAP_ADMIN_PASSWORD="secretpassword"\*(Aq
OPTION \*(AqLDAP_SEARCH_ROOT_DN="cn=Users,dc=example,dc=com"\*(Aq
OPTION \*(AqLDAP_SEARCH_FILTER*=\e\*(Aq"(sAMAccountName=${Args::DACS_USERNAME})"\e\*(Aq\*(Aq
OPTION \*(AqLDAP_ROLES_SELECTOR*=\e\*(Aq"${LDAP::attrname}" eq "memberOf" \e
? strtr(ldap(rdn_attrvalue, \e
ldap(dn_index, "${LDAP::attrvalue}", 1)), " ", "_") \e
: ""\e\*(Aq\*(Aq
.fi
.if n \{\
.RE
.\}
.sp
For example, the resulting role string might look like:
.sp
.if n \{\
.RS 4
.\}
.nf
DnsAdmins,Print_Operators,Domain_Admins,Administrators
.fi
.if n \{\
.RE
.\}
.sp
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBlocal_unix_roles\fR
.RS 4
.PP
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
\m[blue]\fBgroups(1)\fR\m[]\&\s-2\u[184]\d\s+2\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.PP
The user need not have been authenticated as this username on the
Unix
system where this service is run\&.
.sp .5v
.RE
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBTip\fR
.ps -1
.br
.PP
A built\-in version of this module can be selected by using the URL
local_unix_roles
or just
unix\&.
.sp .5v
.RE
.RE
.SS "Related Services"
.PP
The
\m[blue]\fBdacs_current_credentials(8)\fR\m[]\&\s-2\u[35]\d\s+2
web service displays elements of each set of credentials sent with the request\&. The
\m[blue]\fBdacs_signout(8)\fR\m[]\&\s-2\u[185]\d\s+2
service is typically called from a browser to cause one or more cookies (each representing a
\fBDACS\fR
identity) to be deleted\&. Cookies are automatically deleted when a browser terminates, but it is sometimes useful to explicitly logoff\&.
.SH "DIAGNOSTICS"
.PP
The program exits
0
if everything was fine,
1
if an error occurred\&.
.SH "NOTES"
.PP
A separate but similar mechanism called "affiliated
\fBDACS\fR
federations" supports cross\-federation single sign\-on; see
\m[blue]\fBdacs_auth_transfer(8)\fR\m[]\&\s-2\u[8]\d\s+2\&.
.PP
\fBdacs_authenticate\fR
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\&.
.PP
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\&.
.SH "BUGS"
.PP
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\&.
.SH "SEE ALSO"
.PP
\m[blue]\fBdacsauth(1)\fR\m[]\&\s-2\u[6]\d\s+2,
\m[blue]\fBdacscred(1)\fR\m[]\&\s-2\u[186]\d\s+2,
\m[blue]\fBdacscookie(1)\fR\m[]\&\s-2\u[9]\d\s+2,
\m[blue]\fBdacs\&.exprs(5)\fR\m[]\&\s-2\u[3]\d\s+2,
\m[blue]\fBdacs_autologin_ssl(8)\fR\m[]\&\s-2\u[187]\d\s+2,
\m[blue]\fBautologin(8)\fR\m[]\&\s-2\u[139]\d\s+2,
\m[blue]\fBdacs_auth_agent(8)\fR\m[]\&\s-2\u[7]\d\s+2,
\m[blue]\fBdacs_auth_transfer(8)\fR\m[]\&\s-2\u[8]\d\s+2,
\m[blue]\fBdacs_current_credentials(8)\fR\m[]\&\s-2\u[35]\d\s+2,
\m[blue]\fBdacs_select_credentials(8)\fR\m[]\&\s-2\u[46]\d\s+2,
\m[blue]\fBdacs_signout(8)\fR\m[]\&\s-2\u[185]\d\s+2,
\m[blue]\fBpamd(8)\fR\m[]\&\s-2\u[156]\d\s+2
.SH "AUTHOR"
.PP
Distributed Systems Software (\m[blue]\fBwww\&.dss\&.ca\fR\m[]\&\s-2\u[188]\d\s+2)
.SH "COPYING"
.PP
Copyright \(co 2003\-2018 Distributed Systems Software\&. See the
\m[blue]\fBLICENSE\fR\m[]\&\s-2\u[189]\d\s+2
file that accompanies the distribution for licensing information\&.
.SH "NOTES"
.IP " 1." 4
dacsoptions
.RS 4
\%http://dacs.dss.ca/man/dacs.1.html#dacsoptions
.RE
.IP " 2." 4
dacs.conf(5)
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html
.RE
.IP " 3." 4
dacs.exprs(5)
.RS 4
\%http://dacs.dss.ca/man/dacs.exprs.5.html
.RE
.IP " 4." 4
HTTP Authentication
.RS 4
\%http://dacs.dss.ca/man/dacs_acs.8.html#http_authentication
.RE
.IP " 5." 4
html/examples
.RS 4
\%http://dacs.dss.ca/man//examples
.RE
.IP " 6." 4
dacsauth(1)
.RS 4
\%http://dacs.dss.ca/man/dacsauth.1.html
.RE
.IP " 7." 4
dacs_auth_agent(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_auth_agent.8.html
.RE
.IP " 8." 4
dacs_auth_transfer(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_auth_transfer.8.html
.RE
.IP " 9." 4
dacscookie(1)
.RS 4
\%http://dacs.dss.ca/man/dacscookie.1.html
.RE
.IP "10." 4
Auth clause
.RS 4
\%http://dacs.dss.ca/man/#auth_clause
.RE
.IP "11." 4
CONTROL
.RS 4
\%http://dacs.dss.ca/man/#CONTROL
.RE
.IP "12." 4
username
.RS 4
\%http://dacs.dss.ca/man/dacs.1.html#dacs_identity
.RE
.IP "13." 4
dacs.acls(5)
.RS 4
\%http://dacs.dss.ca/man/dacs.acls.5.html#revocation_list
.RE
.IP "14." 4
dacs(1)
.RS 4
\%http://dacs.dss.ca/man/dacs.1.html#naming
.RE
.IP "15." 4
credentials.dtd
.RS 4
\%http://dacs.dss.ca/man/../dtd-xsd/credentials.dtd
.RE
.IP "16." 4
VERIFY_IP
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html#VERIFY_IP
.RE
.IP "17." 4
natd(8)
.RS 4
\%https://www.freebsd.org/cgi/man.cgi?query=natd&apropos=0&sektion=8&manpath=FreeBSD+10.3-RELEASE&format=html
.RE
.IP "18." 4
VERIFY_UA
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html#VERIFY_UA
.RE
.IP "19." 4
AUTH_CREDENTIALS_DEFAULT_LIFETIME_SECS
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html#AUTH_CREDENTIALS_DEFAULT_LIFETIME_SECS
.RE
.IP "20." 4
Advanced Encryption Standard
.RS 4
\%https://en.wikipedia.org/wiki/Advanced_Encryption_Standard
.RE
.IP "21." 4
Federal Information Processing Standard
.RS 4
\%https://www.nist.gov/itl/fips.cfm
.RE
.IP "22." 4
FIPS 198
.RS 4
\%https://csrc.nist.gov/publications/fips/fips198-1/FIPS-198-1_final.pdf
.RE
.IP "23." 4
RFC 2104
.RS 4
\%https://www.rfc-editor.org/rfc/rfc2104.txt
.RE
.IP "24." 4
RFC 4635
.RS 4
\%https://www.rfc-editor.org/rfc/rfc4635.txt
.RE
.IP "25." 4
RFC 4868
.RS 4
\%https://www.rfc-editor.org/rfc/rfc4868.txt
.RE
.IP "26." 4
NIST
.RS 4
\%https://www.nist.gov/
.RE
.IP "27." 4
FIPS 180-1
.RS 4
\%https://csrc.nist.gov/publications/PubsFIPSArch.html
.RE
.IP "28." 4
RFC 4634
.RS 4
\%https://www.rfc-editor.org/rfc/rfc4634.txt
.RE
.IP "29." 4
RFC 6234
.RS 4
\%https://www.rfc-editor.org/rfc/rfc6234.txt
.RE
.IP "30." 4
FIPS 180-4
.RS 4
\%https://csrc.nist.gov/publications/fips/fips180-4/fips-180-4.pdf
.RE
.IP "31." 4
MD5 algorithm
.RS 4
\%https://www.rfc-editor.org/rfc/rfc1321.txt
.RE
.IP "32." 4
Netscape HTTP Cookies Specification
.RS 4
\%http://web.archive.org/web/20070805052634/http://wp.netscape.com/newsref/std/cookie_spec.html
.RE
.IP "33." 4
\fICOOKIE_SYNTAX\fR
.RS 4
\%http://dacs.dss.ca/man/#COOKIE_SYNTAX
.RE
.IP "34." 4
COOKIE_NAME_TERMINATORS
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html#COOKIE_NAME_TERMINATORS
.RE
.IP "35." 4
dacs_current_credentials(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_current_credentials.8.html
.RE
.IP "36." 4
COOKIE_PATH
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html#COOKIE_PATH
.RE
.IP "37." 4
SECURE_MODE
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html#SECURE_MODE
.RE
.IP "38." 4
standard CGI arguments
.RS 4
\%http://dacs.dss.ca/man/dacs.services.8.html#standard_cgi_args
.RE
.IP "39." 4
local_pam_authenticate
.RS 4
\%http://dacs.dss.ca/man/#local_pam_authenticate
.RE
.IP "40." 4
RFC 2109
.RS 4
\%https://www.rfc-editor.org/rfc/rfc2109.txt
.RE
.IP "41." 4
RFC 2965
.RS 4
\%https://www.rfc-editor.org/rfc/rfc2965.txt
.RE
.IP "42." 4
RFC 6265
.RS 4
\%https://www.rfc-editor.org/rfc/rfc6265.txt
.RE
.IP "43." 4
RFC 2616
.RS 4
\%https://www.rfc-editor.org/rfc/rfc2616.txt
.RE
.IP "44." 4
colons are used within cookie names
.RS 4
\%http://dacs.dss.ca/man/#cookie-name-syntax
.RE
.IP "45." 4
dacs_acs(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_acs.8.html
.RE
.IP "46." 4
dacs_select_credentials(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_select_credentials.8.html
.RE
.IP "47." 4
\fBstrtr()\fR
.RS 4
\%http://dacs.dss.ca/man/dacs.exprs.5.html#strtr
.RE
.IP "48." 4
LDAP_USERNAME_URL
.RS 4
\%http://dacs.dss.ca/man/#LDAP_USERNAME_URL
.RE
.IP "49." 4
local_ldap_authenticate
.RS 4
\%http://dacs.dss.ca/man/#local_ldap_authenticate
.RE
.IP "50." 4
OPTION
.RS 4
\%http://dacs.dss.ca/man/#OPTION
.RE
.IP "51." 4
dacs.conf(5)
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html#auth_clause
.RE
.IP "52." 4
pam(3)
.RS 4
\%https://www.freebsd.org/cgi/man.cgi?query=pam&apropos=0&sektion=0&manpath=FreeBSD+10.3-RELEASE&format=html
.RE
.IP "53." 4
X/Open Single Sign-On Service (XSSO) preliminary specification
.RS 4
\%http://www.opengroup.org/pubs/catalog/p702.htm
.RE
.IP "54." 4
dacs.conf(5)
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html#merging
.RE
.IP "55." 4
Authenticating Using an Expression
.RS 4
\%http://dacs.dss.ca/man/#expr
.RE
.IP "56." 4
PASSWORD_CONSTRAINTS
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html#PASSWORD_CONSTRAINTS
.RE
.IP "57." 4
LOG_FILTER
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html#LOG_FILTER
.RE
.IP "58." 4
local_cas_authenticate
.RS 4
\%http://dacs.dss.ca/man/#local_cas_authenticate
.RE
.IP "59." 4
Central Authentication Service (CAS)
.RS 4
\%https://en.wikipedia.org/wiki/Central_Authentication_Service
.RE
.IP "60." 4
RFC 2617
.RS 4
\%https://www.rfc-editor.org/rfc/rfc2617.txt
.RE
.IP "61." 4
local_apache_authenticate
.RS 4
\%http://dacs.dss.ca/man/#local_apache_authenticate
.RE
.IP "62." 4
Information Card
.RS 4
\%http://en.wikipedia.org/wiki/Information_Card
.RE
.IP "63." 4
dacsinfocard(1)
.RS 4
\%http://dacs.dss.ca/man/dacsinfocard.1.html
.RE
.IP "64." 4
dacs_infocard(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_infocard.8.html
.RE
.IP "65." 4
dacs_managed_infocard(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_managed_infocard.8.html
.RE
.IP "66." 4
local_infocard_authenticate
.RS 4
\%http://dacs.dss.ca/man/#local_infocard_authenticate
.RE
.IP "67." 4
local_simple_authenticate
.RS 4
\%http://dacs.dss.ca/man/#local_simple_authenticate
.RE
.IP "68." 4
local_tgma_authenticate
.RS 4
\%http://dacs.dss.ca/man/#local_tgma_authenticate
.RE
.IP "69." 4
add_roles
.RS 4
\%http://dacs.dss.ca/man/#add_roles
.RE
.IP "70." 4
set_roles
.RS 4
\%http://dacs.dss.ca/man/#set_roles
.RE
.IP "71." 4
dacs.exprs(5)
.RS 4
\%http://dacs.dss.ca/man/dacs.exprs.5.html#variables
.RE
.IP "72." 4
AUTH_SUCCESS
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html#AUTH_SUCCESS
.RE
.IP "73." 4
AUTH_SUCCESS_HANDLER
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html#AUTH_SUCCESS_HANDLER
.RE
.IP "74." 4
AUTH_ERROR_HANDLER
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html#AUTH_ERROR_HANDLER
.RE
.IP "75." 4
AUTH_FAIL_DELAY_SECS
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html#AUTH_FAIL_DELAY_SECS
.RE
.IP "76." 4
\fIDACS_AUTH_SUCCESS_HANDLER\fR
.RS 4
\%http://dacs.dss.ca/man/#DACS_AUTH_SUCCESS_HANDLER
.RE
.IP "77." 4
\fIENABLE_AUTH_HANDLERS\fR
.RS 4
\%http://dacs.dss.ca/man/#ENABLE_AUTH_HANDLERS
.RE
.IP "78." 4
dacs_prenv(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_prenv.8.html
.RE
.IP "79." 4
Environment variables
.RS 4
\%http://httpd.apache.org/docs/2.4/mod/mod_ssl.html#envvars
.RE
.IP "80." 4
mod_ssl
.RS 4
\%http://httpd.apache.org/docs/2.4/mod/mod_ssl.html
.RE
.IP "81." 4
dacs.services(8)
.RS 4
\%http://dacs.dss.ca/man/dacs.services.8.html#FORMAT
.RE
.IP "82." 4
dacs_auth_reply.dtd
.RS 4
\%http://dacs.dss.ca/man/../dtd-xsd/dacs_auth_reply.dtd
.RE
.IP "83." 4
dacs_current_credentials.dtd
.RS 4
\%http://dacs.dss.ca/man/../dtd-xsd/dacs_current_credentials.dtd
.RE
.IP "84." 4
auth_reply.dtd
.RS 4
\%http://dacs.dss.ca/man/../dtd-xsd/auth_reply.dtd
.RE
.IP "85." 4
dacs.install(7)
.RS 4
\%http://dacs.dss.ca/man//man/dacs.install.7.html
.RE
.IP "86." 4
\fBmod_authn_file\fR
.RS 4
\%http://httpd.apache.org/docs/2.4/mod/mod_authn_file.html
.RE
.IP "87." 4
\fBmod_auth_digest\fR
.RS 4
\%http://httpd.apache.org/docs/2.4/mod/mod_auth_digest.html
.RE
.IP "88." 4
\fBmod_authn_dbm\fR
.RS 4
\%http://httpd.apache.org/docs/2.4/mod/mod_authn_dbm.html
.RE
.IP "89." 4
htpasswd(1)
.RS 4
\%http://httpd.apache.org/docs/2.4/programs/htpasswd.html
.RE
.IP "90." 4
htdigest(1)
.RS 4
\%http://httpd.apache.org/docs/2.4/programs/htdigest.html
.RE
.IP "91." 4
htdbm(1)
.RS 4
\%http://httpd.apache.org/docs/2.4/programs/htdbm.html
.RE
.IP "92." 4
local_native_authenticate
.RS 4
\%http://dacs.dss.ca/man/#local_native_authenticate
.RE
.IP "93." 4
Central Authentication Service (CAS)
.RS 4
\%http://www.jasig.org/cas
.RE
.IP "94." 4
CAS 2.0 Protocol
.RS 4
\%http://www.jasig.org/cas/protocol
.RE
.IP "95." 4
OpenID
.RS 4
\%http://openid.net/
.RE
.IP "96." 4
STYLE
.RS 4
\%http://dacs.dss.ca/man/#STYLE
.RE
.IP "97." 4
SSLVerifyClient
.RS 4
\%http://httpd.apache.org/docs/2.4/mod/mod_ssl.html#sslverifyclient
.RE
.IP "98." 4
SSLRequire
.RS 4
\%http://httpd.apache.org/docs/2.4/mod/mod_ssl.html#sslrequire
.RE
.IP "99." 4
OpenSSL
.RS 4
\%http://www.openssl.org
.RE
.IP "00." 4
SSLOptions
.RS 4
\%http://httpd.apache.org/docs/2.4/mod/mod_ssl.html#ssloptions
.RE
.IP "01." 4
dacsgrid(1)
.RS 4
\%http://dacs.dss.ca/man/dacsgrid.1.html
.RE
.IP "02." 4
Google
.RS 4
\%https://www.google.com
.RE
.IP "03." 4
account authentication
.RS 4
\%https://code.google.com/apis/accounts/AuthForInstalledApps.html
.RE
.IP "04." 4
eBay
.RS 4
\%http://developer.ebay.com/developercenter/rest/
.RE
.IP "05." 4
Yahoo!
.RS 4
\%http://developer.yahoo.com/auth/
.RE
.IP "06." 4
announced
.RS 4
\%http://blogs.msdn.com/b/card/archive/2011/02/15/beyond-windows-cardspace.aspx
.RE
.IP "07." 4
CardSpace
.RS 4
\%http://en.wikipedia.org/wiki/Windows_CardSpace
.RE
.IP "08." 4
Windows 8
.RS 4
\%http://en.wikipedia.org/wiki/List_of_features_removed_in_Windows_8
.RE
.IP "09." 4
On the Demise of CardSpace
.RS 4
\%http://upon2020.com/blog/2011/03/on-the-demise-of-cardspace/
.RE
.IP "10." 4
Open Cardspace opportunity
.RS 4
\%http://blogs.law.harvard.edu/doc/2011/02/16/open-cardspace-opportunity/
.RE
.IP "11." 4
Personal Reflections on the CardSpace Journey
.RS 4
\%http://self-issued.info/?p=458
.RE
.IP "12." 4
From CardSpace to Verified Claims
.RS 4
\%http://www.identityblog.com/?p=1164
.RE
.IP "13." 4
Change will come: the present is untenable
.RS 4
\%http://www.identityblog.com/?p=1165
.RE
.IP "14." 4
The Clay Feet of Giants?
.RS 4
\%http://www.identityblog.com/?p=1167
.RE
.IP "15." 4
RIP, Windows CardSpace. Hello, U-Prove
.RS 4
\%http://www.zdnet.com/blog/microsoft/rip-windows-cardspace-hello-u-prove/8717
.RE
.IP "16." 4
U-Prove
.RS 4
\%http://research.microsoft.com/en-us/projects/u-prove/
.RE
.IP "17." 4
Identity Selector Interoperability Profile (ISIP) 1.5
.RS 4
\%http://download.microsoft.com/download/1/1/a/11ac6505-e4c0-4e05-987c-6f1d31855cd2/Identity_Selector_Interoperability_Profile_V1.5.pdf
.RE
.IP "18." 4
role descriptor string
.RS 4
\%http://dacs.dss.ca/man/dacs.1.html#roles
.RE
.IP "19." 4
dacs_infocard(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_infocard.8.html#about_claims
.RE
.IP "20." 4
expression-based authentication style
.RS 4
\%http://dacs.dss.ca/man//man/dacs_authenticate.8.html#expr
.RE
.IP "21." 4
dacs_managed_infocard(8)
.RS 4
\%http://dacs.dss.ca/man//man/dacs_managed_infocard.8.html
.RE
.IP "22." 4
dacs.conf(5)
.RS 4
\%http://dacs.dss.ca/man//man/dacs.conf.5.html#INFOCARD_prefixed
.RE
.IP "23." 4
dacs_mex(8)
.RS 4
\%http://dacs.dss.ca/man//man/dacs_mex.8.html
.RE
.IP "24." 4
dacs_sts(8)
.RS 4
\%http://dacs.dss.ca/man//man/dacs_sts.8.html
.RE
.IP "25." 4
Using InfoCards With DACS
.RS 4
\%http://dacs.dss.ca/man/using-infocards-with-dacs.html
.RE
.IP "26." 4
\fIIdentity Selector Interoperability Profile specification and companion guides\fR
.RS 4
\%http://www.microsoft.com/downloads/details.aspx?FamilyID=b94817fc-3991-4dd0-8e85-b73e626f6764&DisplayLang=en
.RE
.IP "27." 4
\fIIntroducing Windows CardSpace\fR
.RS 4
\%http://msdn.microsoft.com/en-us/library/aa480189.aspx
.RE
.IP "28." 4
RFC 2251
.RS 4
\%https://www.rfc-editor.org/rfc/rfc2251.txt
.RE
.IP "29." 4
RFC 2252
.RS 4
\%https://www.rfc-editor.org/rfc/rfc2252.txt
.RE
.IP "30." 4
RFC 2253
.RS 4
\%https://www.rfc-editor.org/rfc/rfc2253.txt
.RE
.IP "31." 4
RFC 3377
.RS 4
\%https://www.rfc-editor.org/rfc/rfc3377.txt
.RE
.IP "32." 4
Active Directory (ADS)
.RS 4
\%http://www.microsoft.com/windows2000/technologies/directory/ad/default.asp
.RE
.IP "33." 4
OpenLDAP
.RS 4
\%http://www.openldap.org
.RE
.IP "34." 4
ldap()
.RS 4
\%http://dacs.dss.ca/man/dacs.exprs.5.html#ldap
.RE
.IP "35." 4
LDAP_USERNAME_URL*
.RS 4
\%http://dacs.dss.ca/man/#LDAP_USERNAME_URL*
.RE
.IP "36." 4
RFC 2396
.RS 4
\%https://www.rfc-editor.org/rfc/rfc2396.txt
.RE
.IP "37." 4
RFC 3986
.RS 4
\%https://www.rfc-editor.org/rfc/rfc3986.txt
.RE
.IP "38." 4
ldapsearch(1)
.RS 4
\%http://www.openldap.org/software/man.cgi?query=ldapsearch&apropos=0&sektion=0&manpath=OpenLDAP+2.4-Release&format=html
.RE
.IP "39." 4
autologin(8)
.RS 4
\%http://dacs.dss.ca/man/autologin.8.html
.RE
.IP "40." 4
1
.RS 4
\%http://curl.haxx.se/rfc/ntlm.html
.RE
.IP "41." 4
2
.RS 4
\%http://msdn.microsoft.com/en-us/library/cc236621%28PROT.10%29.aspx
.RE
.IP "42." 4
Samba
.RS 4
\%http://www.samba.org
.RE
.IP "43." 4
NTLM authentication
.RS 4
\%https://en.wikipedia.org/wiki/NTLM
.RE
.IP "44." 4
NTLM user authentication in Windows
.RS 4
\%https://support.microsoft.com/en-us/help/102716/ntlm-user-authentication-in-windows
.RE
.IP "45." 4
have been identified
.RS 4
\%http://support.microsoft.com/kb/2793313
.RE
.IP "46." 4
smbclient(1)
.RS 4
\%http://www.samba.org/samba/docs/man/manpages-3/smbclient.1.html
.RE
.IP "47." 4
dacs(1)
.RS 4
\%http://dacs.dss.ca/man/dacs.1.html
.RE
.IP "48." 4
dacscheck(1)
.RS 4
\%http://dacs.dss.ca/man/dacscheck.1.html
.RE
.IP "49." 4
pam_start(3)
.RS 4
\%https://www.freebsd.org/cgi/man.cgi?query=pam_start&apropos=0&sektion=3&manpath=FreeBSD+10.3-RELEASE&format=html
.RE
.IP "50." 4
GNU/Linux
.RS 4
\%http://www.kernel.org/pub/linux/libs/pam/modules.html
.RE
.IP "51." 4
FreeBSD
.RS 4
\%http://www.freebsd.org/doc/en_US.ISO8859-1/articles/pam/pam-freebsd-modules.html
.RE
.IP "52." 4
macOS
.RS 4
\%https://developer.apple.com/library/mac/documentation/Darwin/Reference/ManPages/man3/pam.3.html
.RE
.IP "53." 4
pam_unix(8)
.RS 4
\%https://www.freebsd.org/cgi/man.cgi?query=pam_unix&apropos=0&sektion=8&manpath=FreeBSD+10.3-RELEASE&format=html
.RE
.IP "54." 4
local_unix_authenticate
.RS 4
\%http://dacs.dss.ca/man/#local_unix_authenticate
.RE
.IP "55." 4
ATM
.RS 4
\%https://en.wikipedia.org/wiki/Cash_machine
.RE
.IP "56." 4
pamd(8)
.RS 4
\%http://dacs.dss.ca/man/pamd.8.html
.RE
.IP "57." 4
dacs_url
.RS 4
\%http://dacs.dss.ca/man/dacs.groups.5.html#group_syntax
.RE
.IP "58." 4
local_pam_authenticate.css
.RS 4
\%http://dacs.dss.ca/man//css/local_pam_authenticate.css
.RE
.IP "59." 4
PASSWORD_DIGEST
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html#PASSWORD_DIGEST
.RE
.IP "60." 4
dacspasswd(1)
.RS 4
\%http://dacs.dss.ca/man/dacspasswd.1.html
.RE
.IP "61." 4
RFC 2865
.RS 4
\%https://www.rfc-editor.org/rfc/rfc2865.txt
.RE
.IP "62." 4
RFC 2866
.RS 4
\%https://www.rfc-editor.org/rfc/rfc2866.txt
.RE
.IP "63." 4
RFC 3162
.RS 4
\%https://www.rfc-editor.org/rfc/rfc3162.txt
.RE
.IP "64." 4
RFC 3579
.RS 4
\%https://www.rfc-editor.org/rfc/rfc3579.txt
.RE
.IP "65." 4
RFC 6929
.RS 4
\%https://www.rfc-editor.org/rfc/rfc6929.txt
.RE
.IP "66." 4
FreeRADIUS
.RS 4
\%http://www.freeradius.org
.RE
.IP "67." 4
radiusd(8)
.RS 4
\%http://freeradius.org/radiusd/man/radiusd.html
.RE
.IP "68." 4
RFC 6614
.RS 4
\%https://www.rfc-editor.org/rfc/rfc6614.txt
.RE
.IP "69." 4
libradius(3)
.RS 4
\%https://www.freebsd.org/cgi/man.cgi?query=libradius&apropos=0&sektion=3&manpath=FreeBSD+10.3-RELEASE&format=html
.RE
.IP "70." 4
RFC 2945
.RS 4
\%https://www.rfc-editor.org/rfc/rfc2945.txt
.RE
.IP "71." 4
RFC 5054
.RS 4
\%https://www.rfc-editor.org/rfc/rfc5054.txt
.RE
.IP "72." 4
dacstoken(1)
.RS 4
\%http://dacs.dss.ca/man/dacstoken.1.html
.RE
.IP "73." 4
RFC 4226
.RS 4
\%https://www.rfc-editor.org/rfc/rfc4226.txt
.RE
.IP "74." 4
OATH
.RS 4
\%http://www.openauthentication.org
.RE
.IP "75." 4
pam(3)
.RS 4
\%https://www.freebsd.org/cgi/man.cgi?query=pam&apropos=0&sekti on=0&manpath=FreeBSD+10.3-RELEASE&format=html
.RE
.IP "76." 4
getpwnam(3)
.RS 4
\%https://www.freebsd.org/cgi/man.cgi?query=getpwnam&apropos=0&sektion=3&manpath=FreeBSD+10.3-RELEASE&format=html
.RE
.IP "77." 4
yp(8)
.RS 4
\%https://www.freebsd.org/cgi/man.cgi?query=yp&apropos=0&sektion=8&manpath=FreeBSD+10.3-RELEASE&format=html
.RE
.IP "78." 4
pam.conf(5)
.RS 4
\%https://www.freebsd.org/cgi/man.cgi?query=pam.conf&apropos=0&sektion=5&manpath=FreeBSD+10.3-RELEASE&format=html
.RE
.IP "79." 4
dacs.groups(5)
.RS 4
\%http://dacs.dss.ca/man/dacs.groups.5.html
.RE
.IP "80." 4
roles_reply.dtd
.RS 4
\%http://dacs.dss.ca/man/../dtd-xsd/roles_reply.dtd
.RE
.IP "81." 4
ROLE_STRING_MAX_LENGTH
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html#ROLE_STRING_MAX_LENGTH
.RE
.IP "82." 4
OPTION directive
.RS 4
\%http://dacs.dss.ca/man/#r_OPTION
.RE
.IP "83." 4
OPTION* directive
.RS 4
\%http://dacs.dss.ca/man/#r_OPTION*
.RE
.IP "84." 4
groups(1)
.RS 4
\%https://www.freebsd.org/cgi/man.cgi?query=groups&apropos=0&sektion=1&manpath=FreeBSD+10.3-RELEASE&format=html
.RE
.IP "85." 4
dacs_signout(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_signout.8.html
.RE
.IP "86." 4
dacscred(1)
.RS 4
\%http://dacs.dss.ca/man/dacscred.1.html
.RE
.IP "87." 4
dacs_autologin_ssl(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_autologin_ssl.8.html
.RE
.IP "88." 4
www.dss.ca
.RS 4
\%http://www.dss.ca
.RE
.IP "89." 4
LICENSE
.RS 4
\%http://dacs.dss.ca/man/../misc/LICENSE
.RE