Names

Please refer to dacs(1) for details about naming, identities, and roles.

Credentials and Cookies

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

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

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

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

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

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

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

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

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

DACS formulates these response headers as follows.

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

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

where application-name is DACS for purposes of authentication, federation-name is the official name assigned to the federation for which the cookie is valid, jurisdiction-name is the name of the authenticating jurisdiction, and username is the authenticated name of the user. If the jurisdiction-name is omitted, the username must also be omitted. Semicolons, commas, and whitespace within the name must be URL-style encoded. A colon (or the configured name component terminator string) may not appear in the name component it terminates. Here is an example of a cookie name:

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

DACS can also return HTTP cookies for other purposes. The NAME attribute of these cookies has the same general format as an authentication cookie (NAT-DACS:MYFED::MYJUR:da619dc9fe935e55) but may be followed by a username terminator and an additional component; e.g., DACS:EXAMPLE:::SELECTED.

The default terminator syntax of the NAME attribute can be overridden through the COOKIE_NAME_TERMINATORS directive.

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

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.

When operating securely (see the SECURE_MODE directive in dacs.conf(5)) 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.

local_apache_authenticate

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

local_cas_authenticate

This module coordinates with a specified Central Authentication Service (CAS) server to authenticate a user that is purportedly known to that server. The module implements the client side of the CAS 2.0 Protocol and can be used in two different modes: interactive and non-interactive. (This module should interoperate with servers implementing the CAS 3.0 Protocol due to backward compatibility, but this has not been confirmed.)

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

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

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

The STYLE should be configured as cas for this module.

The following module-specific OPTION directive value is understood:

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

local_cert_authenticate

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

The STYLE should be configured as certificate for this module.

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

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

SSLOptions +StdEnvVars +ExportCertData

The following configuration directives are specific to this module:

local_grid_authenticate

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

The STYLE should be configured as password for this module.

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

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

The following OPTION directive values are understood:

local_http_authenticate

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

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

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

The STYLE should be configured as password for this module.

The following OPTION directive values are understood:

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

For Google™ account authentication, for instance, the following configuration might be used:

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

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

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

#! /bin/sh

/bin/cat <<HERE

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

exit 0

Also assume the following Auth clause has been configured:

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

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

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

This expression is equivalent:

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

local_infocard_authenticate

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

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

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

For additional information about InfoCards, please refer to:

local_ldap_authenticate

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

The STYLE should be configured as password for this module.

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

The module implements two different approaches to authentication:

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

The following configuration directives are specific to this module:

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

<Auth id="ldap">
  ...
  OPTION 'LDAP_OPT_X_TLS_CACERTFILE=/usr/local/apache2.4/conf/ssl.crt/cert.crt'
  OPTION 'LDAP_OPT_X_TLS_CACERTDIR=/usr/local/apache2.4/conf/ssl.crt'
  OPTION 'LDAP_OPT_X_TLS=LDAP_OPT_X_TLS_NEVER'
  OPTION 'LDAP_OPT_X_TLS_REQUIRE_CERT=LDAP_OPT_X_TLS_NEVER'
  OPTION 'LDAP_OPT_TIMEOUT=17'
  OPTION 'LDAP_OPT_DEBUG_LEVEL=1'
  ...
</Auth>

SetEnv LDAPTLS_CACERT /path/to/my/ca.crt

The following configuration illustrates authentication using this module:

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

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

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

local_native_authenticate

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

The STYLE should be configured as native for this module.

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

There are no directives or options specific to this module.

local_ntlm_authenticate

The local_ntlm_authenticate module authenticates users through Windows NT LAN Manager using the NTLM protocol [1, 2]. This module uses the libdsm library that is included with DACS to provide NTLM authentication based on a username and password. The module does not need to be (and will not usually be) executed on the host running Windows.

DACS originally used functionality provided by Samba libraries. Although this is no longer the case, the names of the directives used by this module have not been changed.

For details, please refer to NTLM user authentication in Windows.

The STYLE should be configured as password for this module.

The following OPTION directive values are understood:

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

The following illustrates how this module might be configured:

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

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

There are no directives specific to this module.

local_pam_authenticate

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

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

The STYLE should be configured as prompted for this module.

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

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

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

This "prompter" service might be configured as follows:

OPTION "PAM_HANDLER_URL=/dacs_pam_handler"

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

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

If an HTML form is emitted, its appearance can be customized somewhat through the default stylesheet local_pam_authenticate.css. 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:

For example, consider the configuration directive:

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

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

Customization of the HTML form is possible using configuration variables:

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

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

local_passwd_authenticate

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

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

The STYLE should be configured as password for this module.

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

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

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

There are no directives or options specific to this module.

local_radius_authenticate

The local_radius_authenticate 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 USERNAME and PASSWORD parameters it is given. For details, refer to RFC 2865 (also RFC 2866, RFC 3162, RFC 3579, RFC 6929, and others).

The STYLE should be configured as password for this module.

The following OPTION directive values are understood:

The following illustrates how this module might be configured:

<Auth id="radius">
  URL "https://example.com/cgi-bin/dacs/local_radius_authenticate"
  STYLE "passwd"
  CONTROL "sufficient"
  OPTION 'RADIUS_SERVER=10.0.0.123'
  OPTION 'RADIUS_PORT=0'
  OPTION 'RADIUS_SECRET=ASecretRadiusPassweird'
  OPTION 'RADIUS_OK_MSG="OK DACS."'
  OPTION 'RADIUS_TIMEOUT=2'
  OPTION 'RADIUS_DEAD_TIME=4'
  OPTION 'RADIUS_MAX_TRIES=3'
</Auth>

With this configuration, dacs_authenticate 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.

local_simple_authenticate

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

The STYLE should be configured as simple for this module.

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

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

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

There are no directives or options specific to this module.

local_tgma_authenticate

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

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

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

The STYLE should be configured as tgma for this module.

local_token_authenticate

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

The STYLE should be configured as password for this module.

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

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

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

The following OPTION directive value is understood:

local_unix_authenticate

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

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

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

The STYLE should be configured as password for this module.

The following OPTION directive values are understood:

local_roles

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

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

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

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

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

local_ldap_roles

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

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

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

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

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

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

For example, the resulting role string might look like:

DnsAdmins,Print_Operators,Domain_Admins,Administrators

local_unix_roles

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