.\" Copyright (c) 2003-2012
.\" Distributed Systems Software.  All rights reserved.
.\" See the file LICENSE for redistribution information.
.\" $Id: copyright-nr 2564 2012-03-02 00:17:08Z brachman $
'\" t
.\"     Title: dacsauth
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 02/19/2019
.\"    Manual: DACS Commands Manual
.\"    Source: DACS 1.4.40
.\"  Language: English
.\"
.TH "DACSAUTH" "1" "02/19/2019" "DACS 1.4.40" "DACS Commands Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
dacsauth \- authentication check
.SH "SYNOPSIS"
.HP \w'\fBdacsauth\fR\ 'u
\fBdacsauth\fR [\fB\-m\ \fR\fB\fIauth\-module\-spec\fR\fR] [...] [\fB\-r\ \fR\fB\fIroles\-module\-spec\fR\fR] [...] [\fB\-D\fR\fB\fIdirective\fR\fR\fB=\fR\fB\fIvalue\fR\fR] [\fB\-aux\fR]
.br
[\fB\-fj\ \fR\fB\fIjurname\fR\fR] [\fB\-fn\ \fR\fB\fIfedname\fR\fR] [\fB\-h\fR | \fB\-help\fR] [\fB\-id\fR] [\fB\-ll\ \fR\fB\fIlog_level\fR\fR] [\fB\-p\ \fR\fB\fIpassword\fR\fR]
.br
[\fB\-pf\ \fR\fB\fIfile\fR\fR] [\fB\-prompt\fR] [\fB\-promptwith\ \fR\fB\fIprompt\fR\fR] [\fB\-q\fR] [{\fB\-u\fR\ |\ \fB\-user\fR}\ \fIusername\fR] [\fB\-v\fR]
.HP \w'\fBdacsauth\fR\ 'u
\fBdacsauth\fR \fB\-modules\fR
.HP \w'\fBdacsauth\fR\ 'u
\fBdacsauth\fR \fB\-\-version\fR
.SH "DESCRIPTION"
.PP
This program is part of the
\fBDACS\fR
suite\&.
.PP
The
\fBdacsauth\fR
utility tests whether given authentication material satisfies authentication requirements and indicates the outcome through the process\*(Aqs exit status\&. It is similar to
\m[blue]\fBdacs_authenticate(8)\fR\m[]\&\s-2\u[1]\d\s+2
and
\m[blue]\fBdacscred(1)\fR\m[]\&\s-2\u[2]\d\s+2\&.
.PP
\fBdacsauth\fR
provides a way for scripts and other programs to leverage the
\fBDACS\fR
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
\m[blue]\fBdacs_auth_agent(8)\fR\m[]\&\s-2\u[3]\d\s+2
to return
\fBDACS\fR
credentials\&.
.PP
\fBdacsauth\fR
can also be used to retrieve role information associated with a given user\&.
.PP
\fBdacsauth\fR
does not read any
\fBDACS\fR
configuration files\&. Everything needed to perform the test must be specified as an argument\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBTip\fR
.ps -1
.br
.PP
If
\fBdacsauth\fR
uses a built\-in module to perform authentication, or look up roles,
\fIno server component is required\fR\&. This means that you can use
\fBdacsauth\fR
without having to access or even configure a web server, including Apache\&.
.sp .5v
.RE
.SH "OPTIONS"
.PP
The following command line flags are recognized\&. At least one
\fB\-m\fR
flag (to perform authentication testing), or at least one
\fB\-r\fR
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\&.
.PP
\fB\-D\fR\fB\fIdirective\fR\fR\fB=\fR\fB\fIvalue\fR\fR
.RS 4
This is equivalent to setting
\fIdirective\fR, a general
\fBDACS\fR
configuration directive, to
\fIvalue\fR\&. See
\m[blue]\fBdacs\&.conf(5)\fR\m[]\&\s-2\u[4]\d\s+2\&.
.RE
.PP
\fB\-aux\fR
.RS 4
The next string provided by the
\fB\-p\fR,
\fB\-pf\fR,
\fB\-prompt\fR, or
\fB\-promptwith\fR
flag will be the value of the
\fIAUXILIARY\fR
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\&.
.RE
.PP
\fB\-fj\fR \fIjurname\fR
.RS 4
Use
\fIjurname\fR, which must be syntactically valid, as the jurisdiction name\&. If required but not provided, a value derived from the host\*(Aqs domain name will be used\&.
.RE
.PP
\fB\-fn\fR \fIfedname\fR
.RS 4
Use
\fIfedname\fR, which must be syntactically valid, as the federation name\&. If required but not provided, a value derived from the host\*(Aqs domain name will be used\&.
.RE
.PP
\fB\-h\fR
.br
\fB\-help\fR
.RS 4
Display a help message and exit\&.
.RE
.PP
\fB\-id\fR
.RS 4
If successful, print the authenticated
\fBDACS\fR
identity to the standard output\&.
.RE
.PP
\fB\-ll\fR \fIlog_level\fR
.RS 4
Set the debugging output level to
\fIlog_level\fR
(see
\m[blue]\fBdacs(1)\fR\m[]\&\s-2\u[5]\d\s+2)\&. The default level is
warn\&.
.RE
.PP
\fB\-m\fR \fIauth\-module\-spec\fR
.RS 4
Each type of authentication test that is required is described by an
\fIauth\-module\-spec\fR
that immediately follows the
\fB\-m\fR
flag\&. Each
\fIauth\-module\-spec\fR
is essentially an alternate representation of an
\m[blue]\fBAuth clause\fR\m[]\&\s-2\u[6]\d\s+2
and its directives, which are used by
\m[blue]\fBdacs_authenticate(8)\fR\m[]\&\s-2\u[1]\d\s+2\&. Just as the order in which
Auth
clauses appear in a
\fBDACS\fR
configuration file, the order in which the
\fB\-m\fR
flags appear may be significant, depending on the
\fIcontrol\fR
keywords\&. During processing, successive
\fB\-m\fR
components are automatically assigned names,
auth_module_1,
auth_module_2, and so on, mainly for error reporting purposes\&.
.sp
An
\fIauth\-module\-spec\fR
has the following syntax:
.HP \w'\ 'u \fImodule\fR \fIstyle\fR \fIcontrol\fR [\fB\-Of\ \fR\fB\fIfilename\fR\fR] [...] [\fB\-O\fR\fB\fIname\fR\fR\fB=\fR\fB\fIvalue\fR\fR] [...] [\fB\-expr\ \fR\fB\fIEXPR\fR\fR] [\fB\-vfs\ \fR\fB\fIvfs_uri\fR\fR] [...]
.sp
The
\fImodule\fR
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
\m[blue]\fBURL\fR\m[]\&\s-2\u[7]\d\s+2
directive)\&. Next must appear a recognized authentication style keyword specifier (equivalent to the
\m[blue]\fBSTYLE\fR\m[]\&\s-2\u[8]\d\s+2
directive)\&. Next, the
\fIcontrol\fR
keyword follows, which is identical to the
\m[blue]\fBCONTROL\fR\m[]\&\s-2\u[9]\d\s+2
directive in the
Auth
clause\&. After the
\fIcontrol\fR
keyword, the flags described below may follow, in any order\&.
.sp
An
\fIauth\-module\-spec\fR
ends when the first invalid flag (or the end of flags) is encountered\&.
.sp
The
\fB\-O\fR
flag is equivalent to an
\m[blue]\fBOPTION\fR\m[]\&\s-2\u[10]\d\s+2
directive\&.
.sp
The
\fB\-Of\fR
flag is followed by the name of a file from which to read options, one per line, in the format
\fIname\fR=\fIvalue\fR\&. Blank lines and lines beginning with a \*(Aq#\*(Aq 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
\fB\-Of\fR
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\&.
.sp
The
\fB\-expr\fR
flag is equivalent to the
\m[blue]\fBEXPR\fR\m[]\&\s-2\u[11]\d\s+2
directive\&. The
\fB\-vfs\fR
flag is used to configure
\m[blue]\fBVFS\fR\m[]\&\s-2\u[12]\d\s+2
directives required by this module\&.
.RE
.PP
\fB\-modules\fR
.RS 4
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:
.sp
.if n \{\
.RS 4
.\}
.nf
% dacsauth \-modules
.fi
.if n \{\
.RE
.\}
.sp
The set of available (enabled) built\-in authentication and roles modules is determined when
\fBDACS\fR
is built\&.
.RE
.PP
\fB\-p \fR\fB\fIpassword\fR\fR
.RS 4
Specify the password to use (equivalent to the
\fIPASSWORD\fR
argument to
\fBdacs_authenticate\fR)\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBSecurity\fR
.ps -1
.br
A password given on the command line may be visible to other users on the same system\&.
.sp .5v
.RE
.RE
.PP
\fB\-pf \fR\fB\fIfile\fR\fR
.RS 4
Read the password to use from
\fIfile\fR
(equivalent to the
\fIPASSWORD\fR
argument to
\fBdacs_authenticate\fR)\&. If
\fIfile\fR
is "\-", then the password is read from the standard input without prompting\&.
.RE
.PP
\fB\-prompt\fR
.RS 4
Prompt for the password and read it from
stdin
(equivalent to the
\fIPASSWORD\fR
argument to
\fBdacs_authenticate\fR)\&. The password is not echoed\&.
.RE
.PP
\fB\-promptwith \fR\fB\fIprompt\fR\fR
.RS 4
Prompt for the password using the given string (\fIprompt\fR) and read it from
stdin
(equivalent to the
\fIPASSWORD\fR
argument to
\fBdacs_authenticate\fR)\&. The password is not echoed\&.
.RE
.PP
\fB\-q\fR
.RS 4
Be more quiet by reducing the debugging output level\&.
.RE
.PP
\fB\-r\fR \fIrole\-module\-spec\fR
.RS 4
Roles for
\fIusername\fR
can be determined by giving this flag, which is immediately followed by a
\fIroles\-module\-spec\fR\&. The
\fB\-r\fR
flag may be repeated, and the resulting roles are combined\&. Each
\fIroles\-module\-spec\fR
is essentially an alternate representation of a
Roles
clause that is used by
\m[blue]\fBdacs_authenticate(8)\fR\m[]\&\s-2\u[13]\d\s+2\&. Successive
\fB\-r\fR
components are assigned names,
roles_module_1,
roles_module_2, and so on, mainly for error reporting purposes\&.
.sp
A
\fIroles\-module\-spec\fR
has the following syntax:
.HP \w'\ 'u \fImodule\fR [\fB\-Of\ \fR\fB\fIfilename\fR\fR] [...] [\fB\-O\fR\fB\fIname\fR\fR\fB=\fR\fB\fIvalue\fR\fR\ [...]] [\fB\-expr\ \fR\fB\fIEXPR\fR\fR] [\fB\-vfs\ \fR\fB\fIvfs_uri\fR\fR] [...]
The
\fImodule\fR
component is equivalent to the
Roles
clause\*(Aqs
\m[blue]\fBURL\fR\m[]\&\s-2\u[14]\d\s+2
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\&.
.sp
Flags may follow the
\fImodule\fR
component, in any order\&. A
\fIroles\-module\-spec\fR
ends when the first invalid flag (or the end of flags) is encountered\&.
.sp
The
\fB\-O\fR
flag is equivalent to an
\m[blue]\fBOPTION\fR\m[]\&\s-2\u[10]\d\s+2
directive\&.
.sp
The
\fB\-Of\fR
flag is followed by an argument that is the name of a file from which to read options, one per line, in the format
\fIname\fR=\fIvalue\fR\&. Blank lines and lines beginning with a \*(Aq#\*(Aq are ignored; note that these lines do not begin with "\-O" and quotes are simply copied and not interpreted\&. The
\fB\-Of\fR
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\&.
.sp
The
\fB\-expr\fR
flag is equivalent to the
\m[blue]\fBEXPR\fR\m[]\&\s-2\u[11]\d\s+2
directive\&. The
\fB\-vfs\fR
flag is used to configure
\m[blue]\fBVFS\fR\m[]\&\s-2\u[12]\d\s+2
directives required by
\fImodule\fR\&.
.RE
.PP
\fB\-u \fR\fB\fIusername\fR\fR
.br
\fB\-user \fR\fB\fIusername\fR\fR
.RS 4
The username to authenticate against (equivalent to the
\fIUSERNAME\fR
argument to
\fBdacs_authenticate\fR)\&. This username is implicitly associated with the effective federation and jurisdiction (see the
\m[blue]\fB\-fn\fR\m[]\&\s-2\u[15]\d\s+2
and
\m[blue]\fB\-fj\fR\m[]\&\s-2\u[16]\d\s+2
flags)\&.
.RE
.PP
\fB\-v\fR
.RS 4
The
\fB\-v\fR
flag bumps the debugging output level to
debug
or (if repeated)
trace\&.
.RE
.PP
\fB\-\-version\fR
.RS 4
Display the program\*(Aqs version information and then exit\&.
.RE
.SH "EXAMPLES"
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBSecurity\fR
.ps -1
.br
.PP
If
\fBdacsauth\fR
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
\fBDACS\fR
cryptographic keys, specifically
federation_keys
and possibly
\fBDACS\fR
or system password files; the external module will then need to execute with sufficient privileges to access any files it requires\&.
.PP
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\&.
.PP
\fBdacsauth\fR
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)\&.
.sp .5v
.RE
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.PP
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
\m[blue]\fBlocal_ldap_authenticate\fR\m[]\&\s-2\u[17]\d\s+2
and
\m[blue]\fBlocal_ldap_roles\fR\m[]\&\s-2\u[18]\d\s+2
for additional information\&.
.sp .5v
.RE
.PP
This example authenticates user "bobo" with password "test" against the
\fBDACS\fR
password file
/usr/local/dacs/conf/passwd:
.sp
.if n \{\
.RS 4
.\}
.nf
% dacsauth \-m passwd passwd required
  \-vfs "[passwds]dacs\-kwv\-fs:/usr/local/dacs/conf/passwd" \-q \-u bobo \-p test
.fi
.if n \{\
.RE
.\}
.sp
If the command\*(Aqs exit status is zero, the authentication test succeeded, otherwise it failed\&.
.PP
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\&.
.sp
.if n \{\
.RS 4
.\}
.nf
% sudo dacsauth \-m unix passwd required \-u bobo \-prompt
.fi
.if n \{\
.RE
.\}
.PP
In the next example,
\fBdacsauth\fR
attempts to authenticate "bobo" via NTLM on
winders\&.example\&.com:
.sp
.if n \{\
.RS 4
.\}
.nf
% dacsauth \-m ntlm passwd suff \-OSAMBA_SERVER="winders\&.example\&.com" \e
    \-prompt \-u bobo
.fi
.if n \{\
.RE
.\}
.PP
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\&.
.sp
.if n \{\
.RS 4
.\}
.nf
% dacsauth \-m https://example\&.example\&.com/cgi\-bin/dacs/local_ntlm_authenticate \e
   passwd sufficient \-OSAMBA_SERVER="winders\&.example\&.com" \e
  \-fn EXAMPLE \-fj FEDROOT \-u bobo \-pf mypass \e
  \-DVFS="[federation_keys]dacs\-fs:/usr/local/dacs/federations/example/federation_keys"
.fi
.if n \{\
.RE
.\}
.PP
To authenticate "bobo" via a RADIUS server, a command line similar to this might be used:
.sp
.if n \{\
.RS 4
.\}
.nf
% dacsauth \-m radius passwd required \-ORADIUS_SERVER=radius\&.example\&.com \-ORADIUS_SECRET=testing123 \-u bobo \-p hello
.fi
.if n \{\
.RE
.\}
.PP
To authenticate against the
\m[blue]\fBGoogle\fR\m[]\&\s-2\u[19]\d\s+2(TM) account
nobody@gmail\&.com, one might use:
.sp
.if n \{\
.RS 4
.\}
.nf
% dacsauth \-m http passwd suff \e
  \-OAUTH_URL="https://www\&.google\&.com/accounts/ClientLogin" \e
  \-OUSERNAME_PARAMETER=Email \-OPASSWORD_PARAMETER=Passwd \e
  \-Oservice=xapi \-Osource=DSS\-DACS\-1\&.4 \-prompt \-u nobody@gmail\&.com
.fi
.if n \{\
.RE
.\}
.PP
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\&.
.sp
.if n \{\
.RS 4
.\}
.nf
% dacsauth \-m expr expr suffi \e
 \-expr \*(Aq${Args::PASSWORD} eq "foo" ? ${Args::USERNAME} : ""\*(Aq \e
    \-user bobo \-prompt
.fi
.if n \{\
.RE
.\}
.PP
Authentication against an Apache
\fBhtdigest\fR
password file is performed in the following example, where the password is read from
stdin:
.sp
.if n \{\
.RS 4
.\}
.nf
% echo "test" | dacsauth \-m apache digest sufficient \e
  \-OAUTH_MODULE=mod_auth_digest \e
  \-OAUTH_FILE=/usr/local/apache2/conf/passwords\&.digest \e
  \-OAUTH_REALM="DACS Digest Auth Area" \e
  \-u bobo \-pf \-
.fi
.if n \{\
.RE
.\}
.PP
Authentication via the PAM module works differently than the other modules \- and is more complicated to use \- because
\fBdacsauth\fR
may need to be run several times, depending on what information PAM requires\&. Instead of returning a yes/no decision,
\fBdacsauth\fR
may print prompts for more information to
stdout\&. Please review the operational details presented in
\m[blue]\fBdacs_authenticate(8)\fR\m[]\&\s-2\u[20]\d\s+2
and
\m[blue]\fBpamd(8)\fR\m[]\&\s-2\u[21]\d\s+2
before attempting to use this module\&.
.PP
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
\fBdacsauth\fR
is run, although it could be if it were known\&.
.sp
.if n \{\
.RS 4
.\}
.nf
% dacsauth \-m pam prompted suffic \e
 \-vfs "[federation_keys]dacs\-fs:/usr/local/dacs/federations/dss/federation_keys" \e
 \-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 \e
 \-vfs "[federation_keys]dacs\-fs:/usr/local/dacs/federations/dss/federation_keys" \e
 \-OAUTH_PROMPT_VAR1="bobo" \e
 \-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 \e
 \-vfs "[federation_keys]dacs\-fs:/usr/local/dacs/federations/dss/federation_keys" \e
 \-OAUTH_PROMPT_VAR2="apassword" \e
 \-OAUTH_TRANSID="10\&.0\&.0\&.124:57849:85748:9997c5588a6239e3"\-fj EXAMPLE \-fn TEST
.fi
.if n \{\
.RE
.\}
.sp
The first time
\fBdacsauth\fR
is run in the example it returns a prompt for the username ("Login:") that is associated with the transaction variable
\fIAUTH_PROMPT_VAR1\fR
and a transaction identifier (\fIAUTH_TRANSID\fR)\&. The latter must be passed to the subsequent executions of
\fBdacsauth\fR\&. The second run of
\fBdacsauth\fR
passes the username ("bobo") and returns another prompt ("Password:") that is associated with the transaction variable
\fIAUTH_PROMPT_VAR2\fR\&. The third run passes the password ("apassword") but no prompt is returned, indicating that the session is complete and the program\*(Aqs exit status reflects the outcome of authentication\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBTip\fR
.ps -1
.br
.PP
Whether
\fBdacsauth\fR
requires a password to retrieve roles depends on the particular roles module being used\&. For example, a password is not required by
\m[blue]\fBlocal_unix_roles\fR\m[]\&\s-2\u[22]\d\s+2
or
\m[blue]\fBlocal_roles\fR\m[]\&\s-2\u[23]\d\s+2
to obtain roles, but
\m[blue]\fBlocal_ldap_roles\fR\m[]\&\s-2\u[18]\d\s+2
will probably need a password to bind to the directory and obtain roles\&.
.sp .5v
.RE
.PP
This example prints the role string for user "bobo" by calling the built\-in
\m[blue]\fBlocal_unix_roles\fR\m[]\&\s-2\u[22]\d\s+2
module:
.sp
.if n \{\
.RS 4
.\}
.nf
% dacsauth \-r unix \-u bobo
bobo,wheel,www,users
.fi
.if n \{\
.RE
.\}
.PP
The next example is similar to the previous one, except an external roles module is used:
.sp
.if n \{\
.RS 4
.\}
.nf
% dacsauth \-r https://example\&.example\&.com/cgi\-bin/dacs/local_unix_roles \e
  \-DVFS="[federation_keys]dacs\-fs:/usr/local/dacs/federations/federation_keys" \e
  \-fn EXAMPLE \-u bobo
bobo,wheel,www,users
.fi
.if n \{\
.RE
.\}
.sp
The external roles module might be executed on a different host than the one running
\fBdacsauth\fR\&. Provided
\fBdacsauth\fR
has been installed and a matching
federation_keys
file is available on the local host, the local host need not be a
\fBDACS\fR
jurisdiction or have any other
\fBDACS\fR
configuration\&.
.PP
The following example prints the
\m[blue]\fBrole string\fR\m[]\&\s-2\u[24]\d\s+2
for user "bobo" (sAMAccountName), known within the directory by the Common Name "Bobo Baggins", using the (external)
\m[blue]\fBlocal_ldap_roles\fR\m[]\&\s-2\u[18]\d\s+2
module and the "direct" binding method:
.sp
.if n \{\
.RS 4
.\}
.nf
% dacsauth \-r https://example\&.example\&.com/cgi\-bin/dacs/local_ldap_roles \e
    \-Of /usr/local/dacs/ldap_roles_options_direct \-u "bobo" \e
    \-DVFS="[federation_keys]dacs\-fs:/usr/local/dacs/federations/federation_keys" \e
     \-fn EXAMPLE \-fj FEDROOT \-prompt
Password?
RA_AllowMediaAccess,WSSUsers,RA_AllowHomePageLinks,RA_AllowAddInAccess,RA_AllowComputerAccess,RA_AllowRemoteAccess
.fi
.if n \{\
.RE
.\}
.sp
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
\fB\-Of\fR
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:
.sp
.if n \{\
.RS 4
.\}
.nf
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, \e
    ldap(dn_index, "${LDAP::attrvalue}", 1)), " ", "_") : ""
.fi
.if n \{\
.RE
.\}
.sp
Notice that in this context the variable that denotes an authenticated username is referenced (\fI${Args::DACS_USERNAME}\fR) rather than the variable that denotes a purported username (\fI${Args::USERNAME}\fR)\&.
.PP
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:
.sp
.if n \{\
.RS 4
.\}
.nf
% dacsauth \-r https://example\&.example\&.com/cgi\-bin/dacs/local_ldap_roles \e
    \-Of /usr/local/dacs/ldap_roles_options_indirect \-u bobo \e
    \-DVFS="[federation_keys]dacs\-fs:/usr/local/dacs/federations/federation_keys" \e
     \-fn EXAMPLE \-fj FEDROOT \-p bobospassword
RA_AllowMediaAccess,WSSUsers,RA_AllowHomePageLinks,RA_AllowAddInAccess,RA_AllowComputerAccess,RA_AllowRemoteAccess
.fi
.if n \{\
.RE
.\}
.sp
The file
/usr/local/dacs/ldap_roles_options_indirect
might contain configuration similar to this:
.sp
.if n \{\
.RS 4
.\}
.nf
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, \e
    ldap(dn_index, "${LDAP::attrvalue}", 1)), " ", "_") : ""
.fi
.if n \{\
.RE
.\}
.PP
Suppose one wanted to use
\fBdacsauth\fR
to authenticate a user via LDAP in a way analogous to this
dacs\&.conf
configuration:
.sp
.if n \{\
.RS 4
.\}
.nf
<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* \*(Aq"ldap://winders\&.example\&.com/cn=" \&. encode(url, ${Args::USERNAME}) \&. ",cn=Users,dc=example,dc=local"\*(Aq
LDAP_USERNAME_EXPR* \*(Aq"${LDAP::sAMAccountName}"\*(Aq
LDAP_ROLES_SELECTOR* \*(Aq"${LDAP::attrname}" eq "memberOf" \e
    ? strtr(ldap(rdn_attrvalue, ldap(dn_index, "${LDAP::attrvalue}", 1)), " ", "_") : ""\*(Aq
</Auth>
.fi
.if n \{\
.RE
.\}
.sp
A file like this (e\&.g\&.,
/usr/local/dacs/ldap_auth_options_direct) would contain the following directives:
.sp
.if n \{\
.RS 4
.\}
.nf
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" \e
    ? strtr(ldap(rdn_attrvalue, ldap(dn_index, "${LDAP::attrvalue}", 1)), " ", "_") : ""
.fi
.if n \{\
.RE
.\}
.sp
Authentication could then be performed using a command like this:
.sp
.if n \{\
.RS 4
.\}
.nf
% dacsauth \-fj FEDROOT \e
  \-m http://example\&.example\&.com/cgi\-bin/dacs/local_ldap_authenticate passwd suff \e
  \-Of /usr/local/dacs/ldap_auth_options_direct \e
  \-DVFS="[federation_keys]dacs\-fs:/usr/local/dacs/federations/federation_keys" \e
  \-fn EXAMPLE \-u bobo \-prompt
.fi
.if n \{\
.RE
.\}
.PP
For indirect authentication, a configuration file similar to this could be used:
.sp
.if n \{\
.RS 4
.\}
.nf
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" \e
? strtr(ldap(rdn_attrvalue, ldap(dn_index, "${LDAP::attrvalue}", 1)), " ", "_") : ""
.fi
.if n \{\
.RE
.\}
.sp
.SS "Enhancing SSH Security"
.PP
The OpenSSH SSH daemon
\m[blue]\fBsshd(8)\fR\m[]\&\s-2\u[25]\d\s+2
provides a hook, executed after normal authentication, that allows an arbitrary command to be executed rather than the user\*(Aqs shell\&. Refer to the description of the
ForceCommand
and
Match
keywords in
\m[blue]\fBsshd_config(5)\fR\m[]\&\s-2\u[26]\d\s+2\&. This feature can be used to insert
\fBDACS\fR
authentication capabilities into
\fBsshd\fR
for users that sign on through
\fBssh\fR\&. To do this, the
ForceCommand
keyword names a small program that runs
\fBdacsauth\fR, 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\*(Aqs shell or other program\&. In a similar way,
\m[blue]\fBdacscheck(1)\fR\m[]\&\s-2\u[27]\d\s+2
can be called by the small program to consult
\fBDACS\fR
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\&.
.SH "DIAGNOSTICS"
.PP
The program exits
0
if authentication was successful or with
1
if authentication failed or an error occurred\&.
.SH "BUGS"
.PP
This command only supplies partial support for interacting with
\fBdacs_authenticate\fR\&. It may not be possible for an authentication module to return role information, as can be done by
\fBdacs_authenticate\fR\&.
.PP
It would be better if the
\fB\-m\fR
flag were instead
\fB\-a\fR
(for "authenticate")\&.
.SH "SEE ALSO"
.PP
\m[blue]\fBdacscred(1)\fR\m[]\&\s-2\u[2]\d\s+2,
\m[blue]\fBdacs_authenticate(8)\fR\m[]\&\s-2\u[1]\d\s+2,
\m[blue]\fBdacs\&.exprs(5)\fR\m[]\&\s-2\u[28]\d\s+2
.SH "AUTHOR"
.PP
Distributed Systems Software (\m[blue]\fBwww\&.dss\&.ca\fR\m[]\&\s-2\u[29]\d\s+2)
.SH "COPYING"
.PP
Copyright \(co 2003\-2018 Distributed Systems Software\&. See the
\m[blue]\fBLICENSE\fR\m[]\&\s-2\u[30]\d\s+2
file that accompanies the distribution for licensing information\&.
.SH "NOTES"
.IP " 1." 4
dacs_authenticate(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_authenticate.8.html
.RE
.IP " 2." 4
dacscred(1)
.RS 4
\%http://dacs.dss.ca/man/dacscred.1.html
.RE
.IP " 3." 4
dacs_auth_agent(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_auth_agent.8.html
.RE
.IP " 4." 4
dacs.conf(5)
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html
.RE
.IP " 5." 4
dacs(1)
.RS 4
\%http://dacs.dss.ca/man/dacs.1.html
.RE
.IP " 6." 4
Auth clause
.RS 4
\%http://dacs.dss.ca/man/dacs_authenticate.8.html#auth_clause
.RE
.IP " 7." 4
URL
.RS 4
\%http://dacs.dss.ca/man/dacs_authenticate.8.html#URL
.RE
.IP " 8." 4
STYLE
.RS 4
\%http://dacs.dss.ca/man/dacs_authenticate.8.html#STYLE
.RE
.IP " 9." 4
CONTROL
.RS 4
\%http://dacs.dss.ca/man/dacs_authenticate.8.html#CONTROL
.RE
.IP "10." 4
OPTION
.RS 4
\%http://dacs.dss.ca/man/dacs_authenticate.8.html#OPTION
.RE
.IP "11." 4
EXPR
.RS 4
\%http://dacs.dss.ca/man/dacs_authenticate.8.html#EXPR
.RE
.IP "12." 4
VFS
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html#VFS
.RE
.IP "13." 4
dacs_authenticate(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_authenticate.8.html#roles_clause
.RE
.IP "14." 4
URL
.RS 4
\%http://dacs.dss.ca/man/dacs_authenticate.8.html#r_URL
.RE
.IP "15." 4
-fn
.RS 4
\%http://dacs.dss.ca/man/#fn_flag
.RE
.IP "16." 4
-fj
.RS 4
\%http://dacs.dss.ca/man/#fj_flag
.RE
.IP "17." 4
local_ldap_authenticate
.RS 4
\%http://dacs.dss.ca/man/dacs_authenticate.8.html#local_ldap_authenticate
.RE
.IP "18." 4
local_ldap_roles
.RS 4
\%http://dacs.dss.ca/man/dacs_authenticate.8.html#local_ldap_roles
.RE
.IP "19." 4
Google
.RS 4
\%http://www.google.com
.RE
.IP "20." 4
dacs_authenticate(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_authenticate.8.html#local_pam_authenticate
.RE
.IP "21." 4
pamd(8)
.RS 4
\%http://dacs.dss.ca/man/pamd.8.html
.RE
.IP "22." 4
local_unix_roles
.RS 4
\%http://dacs.dss.ca/man/dacs_authenticate.8.html#local_unix_roles
.RE
.IP "23." 4
local_roles
.RS 4
\%http://dacs.dss.ca/man/dacs_authenticate.8.html#local_roles
.RE
.IP "24." 4
role string
.RS 4
\%http://dacs.dss.ca/man/dacs.1.html#roles
.RE
.IP "25." 4
sshd(8)
.RS 4
\%https://www.freebsd.org/cgi/man.cgi?query=sshd&apropos=0&sektion=8&manpath=FreeBSD+10.3-RELEASE&format=html
.RE
.IP "26." 4
sshd_config(5)
.RS 4
\%https://www.freebsd.org/cgi/man.cgi?query=sshd_config&apropos=0&sektion=5&manpath=FreeBSD+10.3-RELEASE&format=html
.RE
.IP "27." 4
dacscheck(1)
.RS 4
\%http://dacs.dss.ca/man/dacscheck.1.html
.RE
.IP "28." 4
dacs.exprs(5)
.RS 4
\%http://dacs.dss.ca/man/dacs.exprs.5.html
.RE
.IP "29." 4
www.dss.ca
.RS 4
\%http://www.dss.ca
.RE
.IP "30." 4
LICENSE
.RS 4
\%http://dacs.dss.ca/man/../misc/LICENSE
.RE