DESCRIPTION

This program is part of the DACS suite.

The dacsauth utility tests whether given authentication material satisfies authentication requirements and indicates the outcome through the process's exit status. It is similar to dacs_authenticate(8) and dacscred(1).

dacsauth provides a way for scripts and other programs to leverage the DACS authentication infrastructure. They might use successful authentication as a coarse form of authorization; only a user that provides a correct password might be allowed to run the program, for instance. Or they might return some type of credentials after successful authentication, or perhaps use dacs_auth_agent(8) to return DACS credentials.

dacsauth does not read any DACS configuration files. Everything needed to perform the test must be specified as an argument.

OPTIONS

Each type of authentication test that is required is described by a module_spec that follows the -m flag. Each module_spec is essentially an alternate representation of an Auth clause that is used by dacs_authenticate(8). Just as the order in which Auth clauses appear in a DACS configuration file, the order in which the -m flags appear may be significant, depending on the control keywords.

All modules must be specified before the general command line arguments can appear.

To list the available modules, run the command:

% dacsauth -modules

The set of available built-in authentication and roles modules is determined when DACS is built.

A module_spec has the following syntax:

The name identifies one of the available modules. The control keyword is identical to the CONTROL directive in the Auth clause. The -O flag is equivalent to the OPTION directive. The -expr flag is equivalent to the EXPR directive. The -url flag is equivalent to the URL directive. The -vfs flag is used to configure VFS directives required by this module.

The following command line flags are recognized:

EXAMPLES

This example authenticates user "bobo" with password "test" against the DACS password file /usr/local/apache2/conf/dacs/passwd:

% dacsauth -m passwd required
  -vfs "[passwds]dacs-kwv-fs:/usr/local/apache2/conf/dacs/passwd" \
  -u bobo -p test

This example attempts to authenticate "bobo" against her Unix password file. The program prompts for the password.

% dacsauth -m unix required -u bobo -prompt

In this example, dacsauth attempts to authenticate "bobo" via the NTLM on winders.example.com:

% dacsauth -m ntlm suff -OSAMBA_SERVER="winders.example.com" -prompt -u bobo

This example is similar to the previous one, except that an external authentication module is used and the password is read from a file. Because of the external module, additional configuration must be provided; in particular, the location of the federation_keys must be specified.

% dacsauth -m ntlm sufficient -OSAMBA_SERVER="winders.example.com" \
  -fn EXAMPLE -fj FEDROOT -u bobo -pf mypass \
  -url https://example.example.com/cgi-bin/dacs/local_ntlm_authenticate \
  -DVFS="[federation_keys]dacs-fs:/usr/local/dacs/federations/dss/federation_keys"

To authenticate against a Google™ account, one might use:

% dacsauth -m http suff \
  -OAUTH_URL="https://www.google.com/accounts/ClientLogin" \
  -OUSERNAME_PARAMETER=Email -OPASSWORD_PARAMETER=Passwd \
  -Oservice=xapi -Osource=DSS-DACS-1.4 -prompt -u nobody@gmail.com

This example demonstrates how an expression might be used to determine whether authentication should succeed:

% dacsauth -m expr suffi \
 -expr '${Args::PASSWORD} eq "foo" ? ${Args::USERNAME} : ""' -user bobo -prompt

The user ("bobo") is prompted for a password. Only if it is foo will authentication succeed. A more realistic example might call another program to help make the determination, for instance.

Authentication against an Apache htdigest password file is performed in the following example where the password is read from stdin:

% echo "test" | dacsauth -m apache sufficient \
  -OAUTH_MODULE=mod_auth_digest \
  -OAUTH_FILE=/usr/local/apache2/conf/passwords.digest \
  -OAUTH_REALM="DACS Digest Auth Area" \
  -u bobo -pf -

Authentication via the PAM module works differently than the other modules - and is more complicated to use - because dacsauth may need to be run several times, depending on what information PAM requires. Instead of returning a yes/no decision, dacsauth may print prompts for more information to stdout. Please review the operational details presented in dacs_authenticate(8) and pamd(8) before attempting to use this module.

The following example demonstrates use of the module from the command line. Once the basic ideas are understood, it should be apparent how to write a script to performed the necessary iterations. Details in the example, such as paths, may need to be adjusted for your environment. Note that in this example the username is not specified the first time dacsauth is run, although it could be if it were known.

% dacsauth -m pam suffic \
 -vfs "[federation_keys]dacs-fs:/usr/local/dacs/federations/dss/federation_keys" \
 -OPAMD_HOST=localhost -OPAMD_PORT=dacs-pamd -fj EXAMPLE -fn TEST
AUTH_PROMPT_VAR1="Login:"
AUTH_TRANSID="10.0.0.124:57849:85748:9997c5588a6239e3"
% dacsauth -m pam suffic \
 -vfs "[federation_keys]dacs-fs:/usr/local/dacs/federations/dss/federation_keys" \
 -OAUTH_PROMPT_VAR1="bobo" \
 -OAUTH_TRANSID="10.0.0.124:57849:85748:9997c5588a6239e3"-fj EXAMPLE -fn TEST
AUTH_PROMPT_VAR2="Password:"
AUTH_TRANSID="10.0.0.124:52188:88417:5ffb0015f21ea546"
% dacsauth -m pam suffic \
 -vfs "[federation_keys]dacs-fs:/usr/local/dacs/federations/dss/federation_keys" \
 -OAUTH_PROMPT_VAR2="apassword" \
 -OAUTH_TRANSID="10.0.0.124:57849:85748:9997c5588a6239e3"-fj EXAMPLE -fn TEST

The first time dacsauth is run in the example it returns a prompt for the username ("Login:") that is associated with the transaction variable AUTH_PROMPT_VAR1 and a transaction identifier (AUTH_TRANSID). The latter must be passed to the subsequent executions of dacsauth. The second run of dacsauth passes the username ("bobo") and returns another prompt ("Password:") that is associated with the transaction variable AUTH_PROMPT_VAR2. The third run passes the password ("apassword") but no prompt is returned, indicating that the session is complete and the program's exit status reflects the outcome of authentication.

DIAGNOSTICS

The program exits 0 if authentication was successful or with 1 if authentication failed or an error occurred.

BUGS

This command only supplies partial support for interacting with dacs_authenticate.

SEE ALSO

dacscred(1), dacs_authenticate(8)

AUTHOR

Distributed Systems Software (www.dss.ca)

COPYING

Copyright © 2003-2010 Distributed Systems Software. See the LICENSE file that accompanies the distribution for licensing information.