dacsauth

DACSAUTH(1)                  DACS Commands Manual                  DACSAUTH(1)



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



DACS 1.4.28b                      02/04/2014                       DACSAUTH(1)