Provided by: dacs_1.4.28b-3ubuntu2_amd64 bug

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] [-q] [{-u | -user} username] [-v]
                        dacsauth-modules

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, or -prompt 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 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 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.

       -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.

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).

       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.

           % 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[17] 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)[18] and pamd(8)[19] 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[20] or
           local_roles[21] to obtain roles, but local_ldap_roles[22] 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[20] 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[23] for user "bobo", known within the
       directory by the Common Name "Bobo Baggins", using the (external) local_ldap_roles[22]
       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 Baggins" \
               -DVFS="[federation_keys]dacs-fs:/usr/local/dacs/federations/federation_keys" \
                -fn EXAMPLE -fj FEDROOT -prompt
           DnsAdmins,Print_Operators,Domain_Admins,Administrators

       Because there are too many flags to easily and correctly place on the command line, the
       options that are needed to do this are read from a file that is specified by the -Of flag.
       This also provides a more secure way to pass passwords to the program; ensure that access
       to the file is restricted appropriately. The file
       /usr/local/dacs/ldap_roles_options_direct might contain configuration such as this:

           LDAP_BIND_METHOD=direct
           LDAP_ADMIN_URL*="ldap://winders.example.com/CN=" . encode(url,${Args::DACS_USERNAME}) . ",CN=Users,DC=example,DC=com"

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

       The following example is like the previous one, except that it uses the "indirect" binding
       method and therefore does not need to be given the user's Common Name:

           % 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
           DnsAdmins,Print_Operators,Domain_Admins,Administrators

       The file /usr/local/dacs/ldap_roles_options_indirect might contain configuration such as
       this:

           LDAP_BIND_METHOD=indirect
           LDAP_ADMIN_URL=ldap://winders.example.com/CN=Administrator,CN=Users,DC=example,DC=com

           # Search under Users...
           LDAP_SEARCH_ROOT_DN=CN=Users,DC=example,DC=com

           LDAP_ADMIN_PASSWORD=theSecretAdminPassword
           LDAP_SEARCH_FILTER*="(sAMAccountName=${Args::DACS_USERNAME})"
           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

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)[24]

AUTHOR

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

COPYING

       Copyright2003-2013 Distributed Systems Software. See the LICENSE[26] 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.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. Google
           http://www.google.com

       18. dacs_authenticate(8)
           http://dacs.dss.ca/man/dacs_authenticate.8.html#local_pam_authenticate

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

       20. local_unix_roles
           http://dacs.dss.ca/man/dacs_authenticate.8.html#local_unix_roles

       21. local_roles
           http://dacs.dss.ca/man/dacs_authenticate.8.html#local_roles

       22. local_ldap_roles
           http://dacs.dss.ca/man/dacs_authenticate.8.html#local_ldap_roles

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

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

       25. www.dss.ca
           http://www.dss.ca

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