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] [-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 "bobo" via a RADIUS server, a command line similar to
       this might be used:

           % dacsauth -m radius passwd required -ORADIUS_SERVER=radius.example.com -ORADIUS_SECRET=testing123 -u bobo -p hello

       To authenticate against the Google[19](TM) 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
       Copyright © 2003-2018 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)
           https://www.freebsd.org/cgi/man.cgi?query=sshd&apropos=0&sektion=8&manpath=FreeBSD+10.3-RELEASE&format=html

       26. sshd_config(5)
           https://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



DACS 1.4.40                        02/19/2019                        DACSAUTH(1)