.\" 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: dacs_auth_agent
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 02/19/2019
.\"    Manual: DACS Web Services Manual
.\"    Source: DACS 1.4.40
.\"  Language: English
.\"
.TH "DACS_AUTH_AGENT" "8" "02/19/2019" "DACS 1.4.40" "DACS Web Services 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"
dacs_auth_agent \- \fBDACS\fR delegated authentication service
.SH "SYNOPSIS"
.HP \w'\fBdacs_auth_agent\fR\ 'u
\fBdacs_auth_agent\fR [\fI\m[blue]\fBdacsoptions\fR\m[]\&\s-2\u[1]\d\s+2\fR]
.SH "DESCRIPTION"
.PP
This web service is part of the
\fBDACS\fR
suite\&.
.PP
The
\fBdacs_auth_agent\fR
web service is used to request
\fBDACS\fR
credentials outside of the usual
\fBDACS\fR
authentication procedure (see
\m[blue]\fBdacs_authenticate(8)\fR\m[]\&\s-2\u[2]\d\s+2)\&. The client making the service request, whether a user agent or middleware, is considered to be an "agent" trusted by the jurisdiction that receives the request by virtue of having obtained
\fBDACS\fR
credentials and satisfying
\fBDACS\fR
access control rules that grant it access to this service\&. In other words, an agent simply requests credentials for a given identity from
\fBdacs_auth_agent\fR
and they are returned if an access control rule grants access and
\fBdacs_auth_agent\fR
is configured appropriately\&.
.PP
The agent\*(Aqs
\fBDACS\fR
credentials can be obtained through
\m[blue]\fBdacs_authenticate(8)\fR\m[]\&\s-2\u[2]\d\s+2,
\m[blue]\fBdacs_auth_transfer(8)\fR\m[]\&\s-2\u[3]\d\s+2,
\m[blue]\fBdacscred(1)\fR\m[]\&\s-2\u[4]\d\s+2,
\m[blue]\fBdacscookie(1)\fR\m[]\&\s-2\u[5]\d\s+2, or even
\fBdacs_auth_agent\fR\&.
.PP
If the request is successful, credentials are returned to the client within an HTTP cookie\&. Credentials generated by this service can be distinguished from those created by one of the other methods\&.
.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
Access control rules are responsible for expressing restrictions on the types of operations to be granted to various trusted agents\&. Access to this web service must not be granted without establishing and testing carefully crafted access control rules and appropriate configuration\&. By default, all access to this service is denied\&.
.sp .5v
.RE
.PP
Much like Unix\*(Aqs
\m[blue]\fBsu(1)\fR\m[]\&\s-2\u[6]\d\s+2
command lets the superuser assume the Unix identity of any other user, this service provides a way for a privileged client to request credentials for a user known to the receiving jurisdiction\&. Any other credentials in the possession of the client remain in effect\&. Help desk personnel and system administrators can use this capability to assist users by temporarily impersonating a user without having to know the user\*(Aqs password, obtaining the user\*(Aqs client certificate, or following the user\*(Aqs usual authentication procedure\&.
.PP
The service can also be invoked to effectively import an identity that is recognized by the agent but possibly not known to the receiving jurisdiction\&. This provides a way to convert foreign credentials, whether from a non\-\fBDACS\fR
based system or a different
\fBDACS\fR
federation, into credentials understood by the federation of the receiving jurisdiction\&. It is only necessary for the agent to understand the foreign credentials;
\fBDACS\fR
never sees them\&.
.PP
Another use of this service is in conjunction with middleware that does its own authentication\&. Having authenticated a user, an application can ask
\fBdacs_auth_agent\fR
for
\fBDACS\fR
credentials for the user\&.
.SS "Web Service Arguments"
.PP
In addition to the
\m[blue]\fBstandard CGI arguments\fR\m[]\&\s-2\u[7]\d\s+2,
\fBdacs_auth_agent\fR
understands the following CGI arguments:
.PP
\fIUSERNAME\fR
.RS 4
If present, the agent asserts that
\fIUSERNAME\fR
is in some sense known to this jurisdiction\&.
.RE
.PP
\fIALIEN_FEDERATION\fR
.RS 4
If present, the agent asserts that
\fIALIEN_USERNAME\fR, which must be provided, is associated with the named external system\&. This can be any string comprised of characters allowed in a
\fBDACS\fR
username; presumably the agent and
\fBDACS\fR
jurisdiction have agreed on the name to use\&. This name, or a string mapped from it, will be incorporated into the resulting
\fBDACS\fR
username and credentials\&.
.RE
.PP
\fIALIEN_USERNAME\fR
.RS 4
If present, the
\fIALIEN_FEDERATION\fR
argument must also be given\&. The agent asserts that the given name, relative to
\fIALIEN_FEDERATION\fR, has been authenticated\&. This can be any string comprised of characters allowed in a
\fBDACS\fR
username\&. This name, or a string mapped from it, will be incorporated into the resulting
\fBDACS\fR
username and credentials\&.
.RE
.PP
\fIDACS_JURISDICTION\fR
.RS 4
This identifies the receiving jurisdiction\&.
.RE
.PP
\fIDACS_BROWSER\fR
.RS 4
This optional parameter is as described for the
\m[blue]\fBdacs_authenticate(8)\fR\m[]\&\s-2\u[2]\d\s+2
service\&.
.RE
.PP
\fIOPERATION\fR
.RS 4
This optional parameter is as described for the
\m[blue]\fBdacs_authenticate(8)\fR\m[]\&\s-2\u[2]\d\s+2
service\&.
.RE
.PP
\fICOOKIE_SYNTAX\fR
.RS 4
This optional parameter is as described for the
\m[blue]\fBdacs_authenticate(8)\fR\m[]\&\s-2\u[2]\d\s+2
service\&.
.RE
.SS "Operation"
.PP
There are two modes of operation\&. In
local mode, the
\fIUSERNAME\fR
argument is provided and is purported to be the
\fBDACS\fR
username of a user known to the receiving jurisdiction\&.
.PP
The second mode, called
alien mode, is selected if both an
\fIALIEN_FEDERATION\fR
argument and an
\fIALIEN_USERNAME\fR
argument are present\&. It is an error if only one of these arguments is given, and the
\fIUSERNAME\fR
is ignored\&. The mode checks that the
\fIALIEN_FEDERATION\fR
and the
\fIALIEN_USERNAME\fR
relative to it are satisfactory\&. This is done by requiring the
\fIALIEN_FEDERATION\fR
to be recognized by the receiving jurisdiction; it may optionally be mapped to a different string\&. Similarly, the
\fIALIEN_USERNAME\fR
argument must be recognized, relative to
\fIALIEN_FEDERATION\fR
or the string mapped from it\&.
.PP
Credentials that have been designated as an
\m[blue]\fBADMIN_IDENTITY\fR\m[]\&\s-2\u[8]\d\s+2
will be returned only if the
\m[blue]\fBAUTH_AGENT_ALLOW_ADMIN_IDENTITY\fR\m[]\&\s-2\u[9]\d\s+2
configuration directive has the value "yes"\&. Refer to
\m[blue]\fBdacs\&.conf(5)\fR\m[]\&\s-2\u[10]\d\s+2
for a description of these configuration directives\&.
.PP
A revocation test is always performed on the
\fBDACS\fR
identity; see
\m[blue]\fBdacs\&.acls(5)\fR\m[]\&\s-2\u[11]\d\s+2
for a description of how authentication revocation works\&.
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBLocal Mode\fR
.RS 4
.PP
If the
\fIUSERNAME\fR
argument is provided, it must consist of printable characters, as determined by
\m[blue]\fBisprint(3)\fR\m[]\&\s-2\u[12]\d\s+2\&.
.PP
By default,
\fBdacs_auth_agent\fR
will blindly accept the trusted client\*(Aqs assertion that
\fIUSERNAME\fR
is known to the receiving jurisdiction\&. An administrator can constrain
\fIUSERNAME\fR, however, and optionally map it into a replacement that is a valid
\fBDACS\fR
username\&.
.PP
If the virtual filestore item type "auth_agent_local" is configured, it is expected to name a file consisting of expressions, one per line (a continued line ends with a backslash)\&. Each expression is evaluated in turn until one returns a non\-empty string value; this value, which must be a syntactically correct
\fBDACS\fR
username, becomes the mapped username\&. An evaluation error is fatal\&. The value of the
\fIUSERNAME\fR
argument is available to each expression as
\fI${Expr::_}\fR
(reminiscent of Perl\*(Aqs
\fI$_\fR
variable)\&.
.PP
For example, consider the configuration directive:
.sp
.if n \{\
.RS 4
.\}
.nf
VFS "[auth_agent_local]dacs\-fs:/usr/local/dacs/auth_agent_local_users"
.fi
.if n \{\
.RE
.\}
.sp
and the file
/usr/local/dacs/auth_agent_local_users, which contains:
.sp
.if n \{\
.RS 4
.\}
.nf
regsub(${Expr::_}, "^auggie doggie$", "auggie")
regsub(${Expr::_}, "^julia$", "sara")
strtr(regsub(${Expr::_}, \e
    "\e([^:]*\e)://\e([^\&.]*\e)\e\e\&.\e(\&.*\e)", \*(Aq${1}\-${2}@${3}\*(Aq), \e
      "A\-Z", "a\-z")
.fi
.if n \{\
.RE
.\}
.sp
If
\fIUSERNAME\fR
is "auggie doggie", credentials will be issued for "auggie"\&. If
\fIUSERNAME\fR
is "julia", credentials will be issued for "sara"\&. If
\fIUSERNAME\fR
is "https://Bob\&.Example\&.com", the third expression will return the string "https\-bob@example\&.com", which will become the mapped name (this example is apropos of mapping
\m[blue]\fBOpenID\fR\m[]\&\s-2\u[13]\d\s+2
names)\&.
.PP
When configured, roles are obtained for
\fIUSERNAME\fR
in the same way as is done for
\m[blue]\fBdacs_authenticate(8)\fR\m[]\&\s-2\u[2]\d\s+2\&.
.RE
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBAlien Mode\fR
.RS 4
.PP
The alien mode of operation proceeds as follows:
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  1." 4.2
.\}
It looks up
\fIALIEN_FEDERATION\fR
using item type
auth_agent_federations\&. When forming a key, the lookup operation will percent\-encode any \*(Aq:\*(Aq and \*(Aq%\*(Aq characters in
\fIALIEN_FEDERATION\fR, so the same encoding is required for keys that appear in
auth_agent_federations\&. If it is not found, authentication fails\&. If found, it may optionally have a value; that value will be used within the resulting
\fBDACS\fR
credentials instead of the
\fIALIEN_FEDERATION\fR
argument\&. In any case, the resulting value must be valid for a
\fBDACS\fR
username\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  2." 4.2
.\}
It looks up
\fIALIEN_USERNAME\fR
using an item type constructed by prepending the string "auth_agent_federation_" to the federation name derived during the previous step\&. When forming a key, the lookup operation will percent\-encode any \*(Aq:\*(Aq and \*(Aq%\*(Aq characters in
\fIALIEN_USERNAME\fR, so the same encoding is required for stored keys\&. If it is not found, authentication fails\&. If found, it may optionally have a value; that value will be used within the resulting
\fBDACS\fR
credentials instead of the
\fIALIEN_USERNAME\fR
argument\&. In any case, the resulting string must be valid for a
\fBDACS\fR
username\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  3." 4.2
.\}
A
\fBDACS\fR
username will be formed using the federation name and username strings derived in the previous steps\&.
.RE
.sp
.RE
.SH "EXAMPLES"
.PP
The following is an example of local mode operation\&. Assume the following configuration directive is in effect:
.sp
.if n \{\
.RS 4
.\}
.nf
VFS "[auth_agent_local]dacs\-fs:/usr/local/dacs/auth_agent_local_users"
.fi
.if n \{\
.RE
.\}
.sp
Also assume that the file
/usr/local/dacs/auth_agent_local_users
contains the expression:
.sp
.if n \{\
.RS 4
.\}
.nf
regsub(${Expr::_}, \e
    "\e([^:]*\e)://\e([^\&.]*\e)\e\e\&.\e(\&.*\e)", \*(Aq${1}\-${2}@${3}\*(Aq)
.fi
.if n \{\
.RE
.\}
.sp
If a request is made with
\fIUSERNAME\fR
equal to "http://Bob\&.Example\&.com", new credentials will be issued for "http\-Bob@Example\&.com" relative to the current jurisdiction\&.
.PP
The following is an example of alien mode operation\&. Assume the following configuration directives are in effect:
.sp
.if n \{\
.RS 4
.\}
.nf
VFS "[auth_agent_federations]dacs\-kwv\-fs:/usr/local/dacs/auth_agent_feds"
VFS "[auth_agent_federation_mars]dacs\-kwv\-fs:/usr/local/dacs/auth_agent_fed_mars"
.fi
.if n \{\
.RE
.\}
.sp
Also assume that the file
/usr/local/dacs/auth_agent_feds
consists of the line
.sp
.if n \{\
.RS 4
.\}
.nf
MARS:
.fi
.if n \{\
.RE
.\}
.sp
and the file
/usr/local/dacs/auth_agent_fed_mars
consists of the line
.sp
.if n \{\
.RS 4
.\}
.nf
gazoo:
.fi
.if n \{\
.RE
.\}
.sp
If a request is made with
\fIALIEN_FEDERATION\fR
equal to "MARS" and
\fIALIEN_USERNAME\fR
equal to "gazoo", the request will satisfy alien mode\*(Aqs rules of operation with the strings "MARS" and "gazoo" being used to form the
\fBDACS\fR
username relative to the current jurisdiction (\fIDACS_JURISDICTION\fR)\&.
.PP
If instead
\fIALIEN_FEDERATION\fR
were "http://example\&.com" and the file
/usr/local/dacs/auth_agent_feds
looked like:
.sp
.if n \{\
.RS 4
.\}
.nf
http%3A//example\&.com:example
.fi
.if n \{\
.RE
.\}
.sp
then the string "example" would be used with "gazoo" to form the
\fBDACS\fR
username\&.
.SH "DIAGNOSTICS"
.PP
The program exits
0
if everything was fine,
1
if an error occurred\&.
.SH "NOTES"
.PP
The word "alien" is used because it sounds cooler than "foreign" and is arguably easier to spell\&.
.PP
A superficially similar feature called "affiliated
\fBDACS\fR
federations", which provides single sign\-on across federation boundaries, is sometimes a more appropriate solution; see
\m[blue]\fBdacs_auth_transfer(8)\fR\m[]\&\s-2\u[3]\d\s+2\&.
.SH "BUGS"
.PP
It should be possible for keys that are matched against
\fIUSERNAME\fR
to be regular expressions and for the corresponding replacement values to interpolate matched substrings\&.
.SH "SEE ALSO"
.PP
\m[blue]\fBdacs_authenticate(8)\fR\m[]\&\s-2\u[2]\d\s+2,
\m[blue]\fBdacs_auth_transfer(8)\fR\m[]\&\s-2\u[3]\d\s+2,
\m[blue]\fBdacs_current_credentials(8)\fR\m[]\&\s-2\u[14]\d\s+2,
\m[blue]\fBdacs_signout(8)\fR\m[]\&\s-2\u[15]\d\s+2,
\m[blue]\fBdacs\&.exprs(5)\fR\m[]\&\s-2\u[16]\d\s+2,
\m[blue]\fBdacscred(1)\fR\m[]\&\s-2\u[4]\d\s+2,
\m[blue]\fBdacscookie(1)\fR\m[]\&\s-2\u[5]\d\s+2\&.
.SH "AUTHOR"
.PP
Distributed Systems Software (\m[blue]\fBwww\&.dss\&.ca\fR\m[]\&\s-2\u[17]\d\s+2)
.SH "COPYING"
.PP
Copyright \(co 2003\-2018 Distributed Systems Software\&. See the
\m[blue]\fBLICENSE\fR\m[]\&\s-2\u[18]\d\s+2
file that accompanies the distribution for licensing information\&.
.SH "NOTES"
.IP " 1." 4
dacsoptions
.RS 4
\%http://dacs.dss.ca/man/dacs.1.html#dacsoptions
.RE
.IP " 2." 4
dacs_authenticate(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_authenticate.8.html
.RE
.IP " 3." 4
dacs_auth_transfer(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_auth_transfer.8.html
.RE
.IP " 4." 4
dacscred(1)
.RS 4
\%http://dacs.dss.ca/man/dacscred.1.html
.RE
.IP " 5." 4
dacscookie(1)
.RS 4
\%http://dacs.dss.ca/man/dacscookie.1.html
.RE
.IP " 6." 4
su(1)
.RS 4
\%https://www.freebsd.org/cgi/man.cgi?query=su&apropos=0&sektion=1&manpath=FreeBSD+10.3-RELEASE&format=html
.RE
.IP " 7." 4
standard CGI arguments
.RS 4
\%http://dacs.dss.ca/man/dacs.services.8.html#standard_cgi_args
.RE
.IP " 8." 4
ADMIN_IDENTITY
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html#ADMIN_IDENTITY
.RE
.IP " 9." 4
AUTH_AGENT_ALLOW_ADMIN_IDENTITY
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html#AUTH_AGENT_ALLOW_ADMIN_IDENTITY
.RE
.IP "10." 4
dacs.conf(5)
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html
.RE
.IP "11." 4
dacs.acls(5)
.RS 4
\%http://dacs.dss.ca/man/dacs.acls.5.html
.RE
.IP "12." 4
isprint(3)
.RS 4
\%https://www.freebsd.org/cgi/man.cgi?query=isprint&apropos=0&sektion=3&manpath=FreeBSD+10.3-RELEASE&format=html
.RE
.IP "13." 4
OpenID
.RS 4
\%http://openid.net/
.RE
.IP "14." 4
dacs_current_credentials(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_current_credentials.8.html
.RE
.IP "15." 4
dacs_signout(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_signout.8.html
.RE
.IP "16." 4
dacs.exprs(5)
.RS 4
\%http://dacs.dss.ca/man/dacs.exprs.5.html
.RE
.IP "17." 4
www.dss.ca
.RS 4
\%http://www.dss.ca
.RE
.IP "18." 4
LICENSE
.RS 4
\%http://dacs.dss.ca/man/../misc/LICENSE
.RE