Provided by: dacs_1.4.38a-2build1_amd64 
NAME
dacsauth - authentication check
SYNOPSIS
dacsauth [-m auth-module-spec] [...] [-r roles-module-spec] [...] [-Ddirective=value] [-aux]
[-fj jurname] [-fn fedname] [-h | -help] [-id] [-ll log_level] [-p password]
[-pf file] [-prompt] [-promptwith prompt] [-q] [{-u | -user} username] [-v]
dacsauth -modules
dacsauth --version
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)[1] and
dacscred(1)[2].
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)[3] to return
DACS credentials.
dacsauth can also be used to retrieve role information associated with a given user.
dacsauth does not read any DACS configuration files. Everything needed to perform the test must be
specified as an argument.
Tip
If dacsauth uses a built-in module to perform authentication, or look up roles, no server component
is required. This means that you can use dacsauth without having to access or even configure a web
server, including Apache.
OPTIONS
The following command line flags are recognized. At least one -m flag (to perform authentication
testing), or at least one -r flag must be specified (to form a role descriptor string for the identity
and print it to stdout). A combination of both flags is allowed, in which case a role descriptor string
is output only if the authentication test is successful.
-Ddirective=value
This is equivalent to setting directive, a general DACS configuration directive, to value. See
dacs.conf(5)[4].
-aux
The next string provided by the -p, -pf, -prompt, or -promptwith flag will be the value of the
AUXILIARY authentication argument. This provides a secure way to pass sensitive auxiliary
information, such as a PIN, to the program. A flag to obtain the password, if any, must precede this
flag on the command line.
-fj jurname
Use jurname, which must be syntactically valid, as the jurisdiction name. If required but not
provided, a value derived from the host's domain name will be used.
-fn fedname
Use fedname, which must be syntactically valid, as the federation name. If required but not provided,
a value derived from the host's domain name will be used.
-h
-help
Display a help message and exit.
-id
If successful, print the authenticated DACS identity to the standard output.
-ll log_level
Set the debugging output level to log_level (see dacs(1)[5]). The default level is warn.
-m auth-module-spec
Each type of authentication test that is required is described by an auth-module-spec that
immediately follows the -m flag. Each auth-module-spec is essentially an alternate representation of
an Auth clause[6] and its directives, which are used by dacs_authenticate(8)[1]. 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. During processing, successive -m components are
automatically assigned names, auth_module_1, auth_module_2, and so on, mainly for error reporting
purposes.
An auth-module-spec has the following syntax:
The module begins with either the name of a built-in module, or a valid abbreviation thereof, or the
(absolute) URL of an external authentication module (equivalent to the URL[7] directive). Next must
appear a recognized authentication style keyword specifier (equivalent to the STYLE[8] directive).
Next, the control keyword follows, which is identical to the CONTROL[9] directive in the Auth
clause. After the control keyword, the flags described below may follow, in any order.
An auth-module-spec ends when the first invalid flag (or the end of flags) is encountered.
The -O flag is equivalent to an OPTION[10] directive.
The -Of flag is followed by the name of a file from which to read options, one per line, in the
format name=value. Blank lines and lines beginning with a '#' are ignored. These lines do not begin
with "-O" and quotes are simply copied and not interpreted. A line can be continued by ending it
with a backslash. The -Of flag can be used to avoid putting passwords on the command line and makes
it easier to write expressions that would otherwise have to be carefully escaped to prevent
interpretation by the shell.
The -expr flag is equivalent to the EXPR[11] directive. The -vfs flag is used to configure VFS[12]
directives required by this module.
-modules
Display a list of built-in authentication modules and roles modules, one per line, and then exit. The
canonical module name is printed, followed by zero or more equivalent abbreviations. For
authentication modules, the authentication style is shown. To list the available modules, run the
command:
% dacsauth -modules
The set of available (enabled) built-in authentication and roles modules is determined when DACS is
built.
-p password
Specify the password to use (equivalent to the PASSWORD argument to dacs_authenticate).
Security
A password given on the command line may be visible to other users on the same system.
-pf file
Read the password to use from file (equivalent to the PASSWORD argument to dacs_authenticate). If
file is "-", then the password is read from the standard input without prompting.
-prompt
Prompt for the password and read it from stdin (equivalent to the PASSWORD argument to
dacs_authenticate). The password is not echoed.
-promptwith prompt
Prompt for the password using the given string (prompt) and read it from stdin (equivalent to the
PASSWORD argument to dacs_authenticate). The password is not echoed.
-q
Be more quiet by reducing the debugging output level.
-r role-module-spec
Roles for username can be determined by giving this flag, which is immediately followed by a
roles-module-spec. The -r flag may be repeated, and the resulting roles are combined. Each
roles-module-spec is essentially an alternate representation of a Roles clause that is used by
dacs_authenticate(8)[13]. Successive -r components are assigned names, roles_module_1,
roles_module_2, and so on, mainly for error reporting purposes.
A roles-module-spec has the following syntax:
The module component is equivalent to the Roles clause's URL[14] directive and is either the name of
an available built-in roles module, a valid abbreviation thereof, or the (absolute) URL of an
external roles module.
Flags may follow the module component, in any order. A roles-module-spec ends when the first invalid
flag (or the end of flags) is encountered.
The -O flag is equivalent to an OPTION[10] directive.
The -Of flag is followed by an argument that is the name of a file from which to read options, one
per line, in the format name=value. Blank lines and lines beginning with a '#' are ignored; note
that these lines do not begin with "-O" and quotes are simply copied and not interpreted. The -Of
flag can be used to avoid putting passwords on the command line and makes it easier to write
expressions that would otherwise have to be carefully escaped to prevent interpretation by the
shell, for example.
The -expr flag is equivalent to the EXPR[11] directive. The -vfs flag is used to configure VFS[12]
directives required by module.
-u username
-user username
The username to authenticate against (equivalent to the USERNAME argument to dacs_authenticate). This
username is implicitly associated with the effective federation and jurisdiction (see the -fn[15] and
-fj[16] flags).
-v
The -v flag bumps the debugging output level to debug or (if repeated) trace.
--version
Display the program's version information and then exit.
EXAMPLES
Security
If dacsauth uses a built-in module to perform authentication, it must run setuid or setgid to obtain
sufficient privileges to access the required password file (the same is true for built-in roles
modules). If it uses an external module, that module will need to execute with sufficient privileges
to access DACS cryptographic keys, specifically federation_keys and possibly DACS or system password
files; the external module will then need to execute with sufficient privileges to access any files
it requires.
Be sure to use the federation_keys that are correct for your federation. Referencing authentication
modules in two or more federations will probably not work.
dacsauth should therefore not ordinarily run as the UID of the user that invokes it (unless that
happens to be root) because it will not be able to access the information it requires. This will also
prevent a user from "cheating" (e.g., by attaching to the running module with a debugger).
Note
Examples in this section that involve NTLM and LDAP were tested against Windows Server 2012. Names
and URLs will likely be different on your system. Refer to the descriptions of
local_ldap_authenticate[17] and local_ldap_roles[18] for additional information.
This example authenticates user "bobo" with password "test" against the DACS password file
/usr/local/dacs/conf/passwd:
% dacsauth -m passwd passwd required
-vfs "[passwds]dacs-kwv-fs:/usr/local/dacs/conf/passwd" -q -u bobo -p test
If the command's exit status is zero, the authentication test succeeded, otherwise it failed.
The following example attempts to authenticate "bobo" against her Unix password file. The program prompts
for the password. It will probably need to be run as root.
% sudo dacsauth -m unix passwd required -u bobo -prompt
In the next example, dacsauth attempts to authenticate "bobo" via NTLM on winders.example.com:
% dacsauth -m ntlm passwd 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 federation_keys and the federation and jurisdiction names must
be specified.
% dacsauth -m https://example.example.com/cgi-bin/dacs/local_ntlm_authenticate \
passwd sufficient -OSAMBA_SERVER="winders.example.com" \
-fn EXAMPLE -fj FEDROOT -u bobo -pf mypass \
-DVFS="[federation_keys]dacs-fs:/usr/local/dacs/federations/example/federation_keys"
To authenticate against the Google[19] account nobody@gmail.com, one might use:
% dacsauth -m http passwd 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
In the following example, an expression is evaluated to determine whether authentication should succeed.
The user ("bobo") is prompted for a password. Only if the string "foo" is given will authentication
succeed. A more realistic example might call another program to help make the determination, for
instance.
% dacsauth -m expr expr suffi \
-expr '${Args::PASSWORD} eq "foo" ? ${Args::USERNAME} : ""' \
-user bobo -prompt
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 digest 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)[20] and pamd(8)[21] 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 prompted 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 prompted 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 prompted 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.
Tip
Whether dacsauth requires a password to retrieve roles depends on the particular roles module being
used. For example, a password is not required by local_unix_roles[22] or local_roles[23] to obtain
roles, but local_ldap_roles[18] will probably need a password to bind to the directory and obtain
roles.
This example prints the role string for user "bobo" by calling the built-in local_unix_roles[22] module:
% dacsauth -r unix -u bobo
bobo,wheel,www,users
The next example is similar to the previous one, except an external roles module is used:
% dacsauth -r https://example.example.com/cgi-bin/dacs/local_unix_roles \
-DVFS="[federation_keys]dacs-fs:/usr/local/dacs/federations/federation_keys" \
-fn EXAMPLE -u bobo
bobo,wheel,www,users
The external roles module might be executed on a different host than the one running dacsauth. Provided
dacsauth has been installed and a matching federation_keys file is available on the local host, the local
host need not be a DACS jurisdiction or have any other DACS configuration.
The following example prints the role string[24] for user "bobo" (sAMAccountName), known within the
directory by the Common Name "Bobo Baggins", using the (external) local_ldap_roles[18] module and the
"direct" binding method:
% dacsauth -r https://example.example.com/cgi-bin/dacs/local_ldap_roles \
-Of /usr/local/dacs/ldap_roles_options_direct -u "bobo" \
-DVFS="[federation_keys]dacs-fs:/usr/local/dacs/federations/federation_keys" \
-fn EXAMPLE -fj FEDROOT -prompt
Password?
RA_AllowMediaAccess,WSSUsers,RA_AllowHomePageLinks,RA_AllowAddInAccess,RA_AllowComputerAccess,RA_AllowRemoteAccess
Because there would be a lot of flags to place on the command line, the options that are needed in this
example are instead read from a file that is specified using the -Of flag. This is also a more secure way
to pass passwords to the program. Ensure that access to the file is restricted appropriately. In this
example, the file /usr/local/dacs/ldap_roles_options_direct might contain configuration such as this:
LDAP_BIND_METHOD=direct
LDAP_USERNAME_URL*="ldap://example.com/cn=" . encode(url, ${Args::DACS_USERNAME}) . ",cn=Users,dc=Example,dc=local"
LDAP_USERNAME_EXPR*="${LDAP::sAMAccountName}"
LDAP_ROLES_SELECTOR*="${LDAP::attrname}" eq "memberOf" ? strtr(ldap(rdn_attrvalue, \
ldap(dn_index, "${LDAP::attrvalue}", 1)), " ", "_") : ""
Notice that in this context the variable that denotes an authenticated username is referenced
(${Args::DACS_USERNAME}) rather than the variable that denotes a purported username (${Args::USERNAME}).
The following example is like the previous one, except that it uses the "indirect" binding method and
therefore is not given the specific URL for the user:
% dacsauth -r https://example.example.com/cgi-bin/dacs/local_ldap_roles \
-Of /usr/local/dacs/ldap_roles_options_indirect -u bobo \
-DVFS="[federation_keys]dacs-fs:/usr/local/dacs/federations/federation_keys" \
-fn EXAMPLE -fj FEDROOT -p bobospassword
RA_AllowMediaAccess,WSSUsers,RA_AllowHomePageLinks,RA_AllowAddInAccess,RA_AllowComputerAccess,RA_AllowRemoteAccess
The file /usr/local/dacs/ldap_roles_options_indirect might contain configuration similar to this:
LDAP_BIND_METHOD=indirect
LDAP_ADMIN_URL=ldap://example.com/cn=admin,cn=Users,dc=Example,dc=local
LDAP_ADMIN_PASSWORD=thESecreTAdmiNPassworD
# Search under Users...
LDAP_SEARCH_ROOT_DN=cn=Users,dc=Example,dc=local
LDAP_SEARCH_FILTER*="(userPrincipalName=${Args::DACS_USERNAME}@Example.local)"
LDAP_ROLES_SELECTOR*="${LDAP::attrname}" eq "memberOf" ? strtr(ldap(rdn_attrvalue, \
ldap(dn_index, "${LDAP::attrvalue}", 1)), " ", "_") : ""
Suppose one wanted to use dacsauth to authenticate a user via LDAP in a way analogous to this dacs.conf
configuration:
<Auth id="ldap">
URL "http://example.example.com/cgi-bin/dacs/local_ldap_authenticate"
STYLE "password,add_roles"
CONTROL "required"
LDAP_BIND_METHOD "direct"
LDAP_USERNAME_URL* '"ldap://winders.example.com/cn=" . encode(url, ${Args::USERNAME}) . ",cn=Users,dc=example,dc=local"'
LDAP_USERNAME_EXPR* '"${LDAP::sAMAccountName}"'
LDAP_ROLES_SELECTOR* '"${LDAP::attrname}" eq "memberOf" \
? strtr(ldap(rdn_attrvalue, ldap(dn_index, "${LDAP::attrvalue}", 1)), " ", "_") : ""'
</Auth>
A file like this (e.g., /usr/local/dacs/ldap_auth_options_direct) would contain the following directives:
LDAP_BIND_METHOD=direct
LDAP_USERNAME_URL*="ldap://winders.example.com/cn=" . encode(url, ${Args::USERNAME}) . ",cn=Users,dc=example,dc=local"
LDAP_USERNAME_EXPR*="${LDAP::sAMAccountName}"
LDAP_ROLES_SELECTOR*="${LDAP::attrname}" eq "memberOf" \
? strtr(ldap(rdn_attrvalue, ldap(dn_index, "${LDAP::attrvalue}", 1)), " ", "_") : ""
Authentication could then be performed using a command like this:
% dacsauth -fj FEDROOT \
-m http://example.example.com/cgi-bin/dacs/local_ldap_authenticate passwd suff \
-Of /usr/local/dacs/ldap_auth_options_direct \
-DVFS="[federation_keys]dacs-fs:/usr/local/dacs/federations/federation_keys" \
-fn EXAMPLE -u bobo -prompt
For indirect authentication, a configuration file similar to this could be used:
LDAP_BIND_METHOD=indirect
LDAP_USERNAME_EXPR*=regsub(${LDAP::userPrincipalName},"@.*","")
LDAP_ADMIN_URL=ldap://winders.example.com/cn=admin,cn=Users,dc=example,dc=local
LDAP_ADMIN_PASSWORD=MySecretAdminPasswordGoesHere
LDAP_SEARCH_ROOT_DN=cn=Users,dc=Example,dc=local
LDAP_SEARCH_FILTER*="(userPrincipalName=${Args::USERNAME}@Example.local)"
LDAP_ROLES_SELECTOR*="${LDAP::attrname}" eq "memberOf" \
? strtr(ldap(rdn_attrvalue, ldap(dn_index, "${LDAP::attrvalue}", 1)), " ", "_") : ""
Enhancing SSH Security
The OpenSSH SSH daemon sshd(8)[25] provides a hook, executed after normal authentication, that allows an
arbitrary command to be executed rather than the user's shell. Refer to the description of the
ForceCommand and Match keywords in sshd_config(5)[26]. This feature can be used to insert DACS
authentication capabilities into sshd for users that sign on through ssh. To do this, the ForceCommand
keyword names a small program that runs dacsauth, which might prompt the user for an additional password
or codeword, validate it, and return the result of authentication through its exit status. Depending on
the result of authentication, the small program can execute the user's shell or other program. In a
similar way, dacscheck(1)[27] can be called by the small program to consult DACS access control rules.
Note that it seems that in some contexts the program run by ForceCommand cannot disable keyboard echo,
which might make this approach inappropriate sometimes.
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. It may not be possible
for an authentication module to return role information, as can be done by dacs_authenticate.
It would be better if the -m flag were instead -a (for "authenticate").
SEE ALSO
dacscred(1)[2], dacs_authenticate(8)[1], dacs.exprs(5)[28]
AUTHOR
Distributed Systems Software (www.dss.ca[29])
COPYING
Copyright2003-2016 Distributed Systems Software. See the LICENSE[30] file that accompanies the
distribution for licensing information.
NOTES
1. dacs_authenticate(8) http://dacs.dss.ca/man/dacs_authenticate.8.html 2. dacscred(1) http://dacs.dss.ca/man/dacscred.1.html 3. dacs_auth_agent(8) http://dacs.dss.ca/man/dacs_auth_agent.8.html 4. dacs.conf(5) http://dacs.dss.ca/man/dacs.conf.5.html 5. dacs(1) http://dacs.dss.ca/man/dacs.1.html 6. Auth clause http://dacs.dss.ca/man/dacs_authenticate.8.html#auth_clause 7. URL http://dacs.dss.ca/man/dacs_authenticate.8.html#URL 8. STYLE http://dacs.dss.ca/man/dacs_authenticate.8.html#STYLE 9. CONTROL http://dacs.dss.ca/man/dacs_authenticate.8.html#CONTROL 10. OPTION http://dacs.dss.ca/man/dacs_authenticate.8.html#OPTION 11. EXPR http://dacs.dss.ca/man/dacs_authenticate.8.html#EXPR 12. VFS http://dacs.dss.ca/man/dacs.conf.5.html#VFS 13. dacs_authenticate(8) http://dacs.dss.ca/man/dacs_authenticate.8.html#roles_clause 14. URL http://dacs.dss.ca/man/dacs_authenticate.8.html#r_URL 15. -fn http://dacs.dss.ca/man/#fn_flag 16. -fj http://dacs.dss.ca/man/#fj_flag 17. local_ldap_authenticate http://dacs.dss.ca/man/dacs_authenticate.8.html#local_ldap_authenticate 18. local_ldap_roles http://dacs.dss.ca/man/dacs_authenticate.8.html#local_ldap_roles 19. Google http://www.google.com 20. dacs_authenticate(8) http://dacs.dss.ca/man/dacs_authenticate.8.html#local_pam_authenticate 21. pamd(8) http://dacs.dss.ca/man/pamd.8.html 22. local_unix_roles http://dacs.dss.ca/man/dacs_authenticate.8.html#local_unix_roles 23. local_roles http://dacs.dss.ca/man/dacs_authenticate.8.html#local_roles 24. role string http://dacs.dss.ca/man/dacs.1.html#roles 25. sshd(8) http://www.freebsd.org/cgi/man.cgi?query=sshd&apropos=0&sektion=8&manpath=FreeBSD+10.3-RELEASE&format=html 26. sshd_config(5) http://www.freebsd.org/cgi/man.cgi?query=sshd_config&apropos=0&sektion=5&manpath=FreeBSD+10.3-RELEASE&format=html 27. dacscheck(1) http://dacs.dss.ca/man/dacscheck.1.html 28. dacs.exprs(5) http://dacs.dss.ca/man/dacs.exprs.5.html 29. www.dss.ca http://www.dss.ca 30. LICENSE http://dacs.dss.ca/man/../misc/LICENSE