dacs_auth_agent

DACS_AUTH_AGENT(8)          DACS Web Services Manual          DACS_AUTH_AGENT(8)



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.

SEE ALSO
       dacs_authenticate(8)[2], dacs_auth_transfer(8)[3],
       dacs_current_credentials(8)[14], dacs_signout(8)[15], dacs.exprs(5)[16],
       dacscred(1)[4], dacscookie(1)[5].

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

COPYING
       Copyright © 2003-2018 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)
           https://www.freebsd.org/cgi/man.cgi?query=su&apropos=0&sektion=1&manpath=FreeBSD+10.3-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)
           https://www.freebsd.org/cgi/man.cgi?query=isprint&apropos=0&sektion=3&manpath=FreeBSD+10.3-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



DACS 1.4.40                        02/19/2019                 DACS_AUTH_AGENT(8)