DACS_AUTH_AGENT(8) | DACS Web Services Manual | DACS_AUTH_AGENT(8) |
NAME¶
dacs_auth_agent - DACS delegated authentication serviceSYNOPSIS¶
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.Web Service Arguments¶
In addition to the standard CGI arguments[7], dacs_auth_agent understands the following CGI arguments: USERNAMEIf 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.
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:
and the file /usr/local/dacs/auth_agent_local_users, which contains:
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].
VFS "[auth_agent_local]dacs-fs:/usr/local/dacs/auth_agent_local_users"
regsub(${Expr::_}, "^auggie doggie$", "auggie") regsub(${Expr::_}, "^julia$", "sara") strtr(regsub(${Expr::_}, \ "\([^:]*\)://\([^.]*\)\\.\(.*\)", '${1}-${2}@${3}'), \ "A-Z", "a-z")
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"
regsub(${Expr::_}, \ "\([^:]*\)://\([^.]*\)\\.\(.*\)", '${1}-${2}@${3}')
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"
MARS:
gazoo:
http%3A//example.com:example
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.SEE ALSO¶
AUTHOR¶
Distributed Systems Software ( www.dss.ca[17])COPYING¶
Copyright2003-2012 Distributed Systems Software. See the LICENSE[18] file that accompanies the distribution for licensing information.NOTES¶
- 1.
- dacsoptions
- 4.
- dacscred(1)
- 6.
- su(1)
- 7.
- standard CGI arguments
- 8.
- ADMIN_IDENTITY
- 9.
- AUTH_AGENT_ALLOW_ADMIN_IDENTITY
- 10.
- dacs.conf(5)
- 11.
- dacs.acls(5)
- 12.
- isprint(3)
- 13.
- OpenID
- 15.
- dacs_signout(8)
- 16.
- dacs.exprs(5)
- 17.
- www.dss.ca
- 18.
- LICENSE
10/22/2012 | DACS 1.4.27b |