Ubuntu Manpage: dacs_auth_agent - DACS delegated authentication service

NAME

       dacs_auth_agent - DACS delegated authentication service

SYNOPSIS

       dacs_auth_agent [dacsoptions[1]]

DESCRIPTION

This web service is part of the DACS suite.

The dacs_auth_agent web service is used to request DACS credentials outside of the usual
DACS authentication procedure (see dacs_authenticate(8)[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 DACS credentials and
satisfying DACS access control rules that grant it access to this service. In other words,
an agent simply requests credentials for a given identity from dacs_auth_agent and they
are returned if an access control rule grants access and dacs_auth_agent is configured
appropriately.

The agent's DACS credentials can be obtained through dacs_authenticate(8)[2],
dacs_auth_transfer(8)[3], dacscred(1)[4], dacscookie(1)[5], or even dacs_auth_agent.

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.

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

Much like Unix's su(1)[6] 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's password, obtaining the user's client certificate, or following the user's usual
authentication procedure.

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-DACS based system or a different DACS
federation, into credentials understood by the federation of the receiving jurisdiction.
It is only necessary for the agent to understand the foreign credentials; DACS never sees
them.

Another use of this service is in conjunction with middleware that does its own
authentication. Having authenticated a user, an application can ask dacs_auth_agent for
DACS credentials for the user.

Web Service Arguments
In addition to the standard CGI arguments[7], dacs_auth_agent understands the following
CGI arguments:

USERNAME
If present, the agent asserts that USERNAME is in some sense known to this
jurisdiction.

ALIEN_FEDERATION
If present, the agent asserts that ALIEN_USERNAME, which must be provided, is
associated with the named external system. This can be any string comprised of
characters allowed in a DACS username; presumably the agent and DACS jurisdiction have
agreed on the name to use. This name, or a string mapped from it, will be incorporated
into the resulting DACS username and credentials.

ALIEN_USERNAME
If present, the ALIEN_FEDERATION argument must also be given. The agent asserts that
the given name, relative to ALIEN_FEDERATION, has been authenticated. This can be any
string comprised of characters allowed in a DACS username. This name, or a string
mapped from it, will be incorporated into the resulting DACS username and credentials.

DACS_JURISDICTION
This identifies the receiving jurisdiction.

DACS_BROWSER
This optional parameter is as described for the dacs_authenticate(8)[2] service.

OPERATION
This optional parameter is as described for the dacs_authenticate(8)[2] service.

COOKIE_SYNTAX
This optional parameter is as described for the dacs_authenticate(8)[2] service.

Operation
There are two modes of operation. In local mode, the USERNAME argument is provided and is
purported to be the DACS username of a user known to the receiving jurisdiction.

The second mode, called alien mode, is selected if both an ALIEN_FEDERATION argument and
an ALIEN_USERNAME argument are present. It is an error if only one of these arguments is
given, and the USERNAME is ignored. The mode checks that the ALIEN_FEDERATION and the
ALIEN_USERNAME relative to it are satisfactory. This is done by requiring the
ALIEN_FEDERATION to be recognized by the receiving jurisdiction; it may optionally be
mapped to a different string. Similarly, the ALIEN_USERNAME argument must be recognized,
relative to ALIEN_FEDERATION or the string mapped from it.

Credentials that have been designated as an ADMIN_IDENTITY[8] will be returned only if the
AUTH_AGENT_ALLOW_ADMIN_IDENTITY[9] configuration directive has the value "yes". Refer to
dacs.conf(5)[10] for a description of these configuration directives.

A revocation test is always performed on the DACS identity; see dacs.acls(5)[11] for a
description of how authentication revocation works.

Local Mode
If the USERNAME argument is provided, it must consist of printable characters, as
determined by isprint(3)[12].

By default, dacs_auth_agent will blindly accept the trusted client's assertion that
USERNAME is known to the receiving jurisdiction. An administrator can constrain
USERNAME, however, and optionally map it into a replacement that is a valid DACS
username.

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 DACS username, becomes the
mapped username. An evaluation error is fatal. The value of the USERNAME argument is
available to each expression as ${Expr::_} (reminiscent of Perl's $_ variable).

For example, consider the configuration directive:

VFS "[auth_agent_local]dacs-fs:/usr/local/dacs/auth_agent_local_users"

and the file /usr/local/dacs/auth_agent_local_users, which contains:

regsub(${Expr::_}, "^auggie doggie$", "auggie")
regsub(${Expr::_}, "^julia$", "sara")
strtr(regsub(${Expr::_}, \
"$[^:]*$://$[^.]*$\\.$.*$", '${1}-${2}@${3}'), \
"A-Z", "a-z")

If USERNAME is "auggie doggie", credentials will be issued for "auggie". If USERNAME
is "julia", credentials will be issued for "sara". If USERNAME 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 OpenID[13] names).

When configured, roles are obtained for USERNAME in the same way as is done for
dacs_authenticate(8)[2].

Alien Mode
The alien mode of operation proceeds as follows:

1. It looks up ALIEN_FEDERATION using item type auth_agent_federations. When forming
a key, the lookup operation will percent-encode any ':' and '%' characters in
ALIEN_FEDERATION, 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 DACS
credentials instead of the ALIEN_FEDERATION argument. In any case, the resulting
value must be valid for a DACS username.

2. It looks up ALIEN_USERNAME 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 ':' and '%'
characters in ALIEN_USERNAME, 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 DACS credentials instead of the
ALIEN_USERNAME argument. In any case, the resulting string must be valid for a
DACS username.

3. A DACS username will be formed using the federation name and username strings
derived in the previous steps.

EXAMPLES

       The following is an example of local mode operation. Assume the following configuration
       directive is in effect:

           VFS "[auth_agent_local]dacs-fs:/usr/local/dacs/auth_agent_local_users"

       Also assume that the file /usr/local/dacs/auth_agent_local_users contains the expression:

           regsub(${Expr::_}, \
               "\([^:]*\)://\([^.]*\)\\.\(.*\)", '${1}-${2}@${3}')

       If a request is made with USERNAME equal to "http://Bob.Example.com", new credentials will
       be issued for "http-Bob@Example.com" relative to the current jurisdiction.

       The following is an example of alien mode operation. Assume the following configuration
       directives are in effect:

           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"

       Also assume that the file /usr/local/dacs/auth_agent_feds consists of the line

           MARS:

       and the file /usr/local/dacs/auth_agent_fed_mars consists of the line

           gazoo:

       If a request is made with ALIEN_FEDERATION equal to "MARS" and ALIEN_USERNAME equal to
       "gazoo", the request will satisfy alien mode's rules of operation with the strings "MARS"
       and "gazoo" being used to form the DACS username relative to the current jurisdiction
       (DACS_JURISDICTION).

       If instead ALIEN_FEDERATION were "http://example.com" and the file
       /usr/local/dacs/auth_agent_feds looked like:

           http%3A//example.com:example

       then the string "example" would be used with "gazoo" to form the DACS username.

DIAGNOSTICS

       The program exits 0 if everything was fine, 1 if an error occurred.

NOTES

       The word "alien" is used because it sounds cooler than "foreign" and is arguably easier to
       spell.

       A superficially similar feature called "affiliated DACS federations", which provides
       single sign-on across federation boundaries, is sometimes a more appropriate solution; see
       dacs_auth_transfer(8)[3].

BUGS

       It should be possible for keys that are matched against USERNAME to be regular expressions
       and for the corresponding replacement values to interpolate matched substrings.

AUTHOR

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

COPYING

       Copyright2003-2014 Distributed Systems Software. See the LICENSE[18] file that accompanies
       the distribution for licensing information.

NOTES

        1. dacsoptions
           http://dacs.dss.ca/man/dacs.1.html#dacsoptions

        2. dacs_authenticate(8)
           http://dacs.dss.ca/man/dacs_authenticate.8.html

        3. dacs_auth_transfer(8)
           http://dacs.dss.ca/man/dacs_auth_transfer.8.html

        4. dacscred(1)
           http://dacs.dss.ca/man/dacscred.1.html

        5. dacscookie(1)
           http://dacs.dss.ca/man/dacscookie.1.html

        6. su(1)
           http://www.freebsd.org/cgi/man.cgi?query=su&apropos=0&sektion=1&manpath=FreeBSD+10.1-RELEASE&format=html

        7. standard CGI arguments
           http://dacs.dss.ca/man/dacs.services.8.html#standard_cgi_args

        8. ADMIN_IDENTITY
           http://dacs.dss.ca/man/dacs.conf.5.html#ADMIN_IDENTITY

        9. AUTH_AGENT_ALLOW_ADMIN_IDENTITY
           http://dacs.dss.ca/man/dacs.conf.5.html#AUTH_AGENT_ALLOW_ADMIN_IDENTITY

       10. dacs.conf(5)
           http://dacs.dss.ca/man/dacs.conf.5.html

       11. dacs.acls(5)
           http://dacs.dss.ca/man/dacs.acls.5.html

       12. isprint(3)
           http://www.freebsd.org/cgi/man.cgi?query=isprint&apropos=0&sektion=3&manpath=FreeBSD+10.1-RELEASE&format=html

       13. OpenID
           http://openid.net/

       14. dacs_current_credentials(8)
           http://dacs.dss.ca/man/dacs_current_credentials.8.html

       15. dacs_signout(8)
           http://dacs.dss.ca/man/dacs_signout.8.html

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

       17. www.dss.ca
           http://www.dss.ca

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

NAME

SYNOPSIS

DESCRIPTION

EXAMPLES

DIAGNOSTICS

NOTES

BUGS

SEE ALSO

AUTHOR

COPYING

NOTES