Provided by: dacs_1.4.28b-3ubuntu2_i386 bug

NAME

       autologin - Convert an Apache identity to a DACS identity

SYNOPSIS

       autologin [dacsoptions[1]]

DESCRIPTION

       This program is part of the DACS suite.

       The autologin CGI program, in conjunction with appropriate Apache and
       DACS configuration, is used to automatically convert an identity
       already established by Apache into a DACS identity. After standard HTTP
       Basic or Digest Authentication (RFC 2617[2]) has been performed
       successfully, autologin causes DACS credentials to be generated and
       returned. This capability lets DACS leverage any of Apache's existing
       authentication methods through simple configuration.

       A user that has completed Basic or Digest Authentication (following a
       401 Authorization Required response from the web server) accesses
       autologin.  autologin generates credentials by constructing a request
       to dacs_authenticate(8)[3]. The value of the REMOTE_USER environment
       variable, as set by Apache, is used by dacs_authenticate to derive the
       DACS username.

           Note
           autologin is not installed by default when DACS is built, in part
           because it can be a bit tricky to configure correctly and securely.
           The more recent RFC 2617[2] capability built-in to DACS is
           recommended instead. Please refer to the section on HTTP
           Authentication[4].

           Security
           Because this program is run during authentication processing, its
           file permissions must be set to prevent replacement or alteration
           by users other than a DACS administrator.

OPTIONS

       Only the standard dacsoptions[1] command line arguments are recognized.

   Web Service Arguments
       autologin understands the following CGI arguments. All arguments are
       required unless otherwise indicated.

       DACS_CONF
           The path to the DACS configuration file that should be used to
           locate jurisdiction configuration information needed by
           dacs_authenticate.

       DACS_ERROR_URL
           When autologin is invoked as a result of DACS event handling,
           DACS_ERROR_URL is automatically passed by dacs_acs(8)[5] and
           represents the original URL to which access was denied. In typical
           use, autologin is configured as the handler for a dacs_acs 902
           error code (NO_AUTH, "Authentication by DACS is required").
           autologin then invokes dacs_authenticate. If DACS authentication is
           successful, dacs_authenticate ordinarily issues a browser redirect
           to the value of DACS_ERROR_URL and a cookie bearing the credentials
           are set in the browser (but see the NOREDIRECT argument).

       NOREDIRECT
           If this optional argument is present (its value is immaterial),
           autologin instructs dacs_authenticate to not issue a browser
           redirect to the value of DACS_ERROR_URL.

       DACS_JURISDICTION
           When autologin is invoked as a result of DACS event handling,
           DACS_JURISDICTION is set by DACS to the name of the jurisdiction
           that received the request. By default, autologin generates
           credentials for the jurisdiction at which dacs_authenticate is
           invoked (specifically, DACS_JURISDICTION). This can be overridden
           by the DACS_SET_JURISDICTION parameter.

       DACS_SET_JURISDICTION
           This optional argument explicitly names the jurisdiction in which
           autologin should generate credentials.  DACS_SET_JURISDICTION
           overrides the value, if any, of DACS_JURISDICTION and must be the
           same as the jurisdiction in which autologin is deployed.

       JURISDICTION_URI
           This is the URI identifying the jurisdiction in the DACS
           configuration file corresponding to the value specified in a
           DACS_JURISDICTION or DACS_SET_JURISDICTION argument. This argument
           is optional since the jurisdiction name can be used for this
           purpose.

       just_dump_stdin
           This optional argument is useful for debugging. If the value of
           QUERY_STRING is exactly jump_dump_stdin, then the program will
           simply copy its standard input to the standard output as
           text/plain.

EXAMPLE

       A typical use of autologin is to support coexistence on the same Web
       site of DACS-wrapped content, services. legacy applications, or content
       deployed under HTTP Basic or Digest authentication. The following
       example illustrates configuration of Apache and DACS for the deployment
       under HTTP Basic authentication of a Web log application, Blogo.  Blogo
       will be deployed within a DACS jurisdiction METALOGIC. The URI space of
       interest will be example.com/metalogic/*.

       In the Apache configuration file httpd.conf, a Location is defined for
       the Blogo application under Basic authentication:

           <Location /metalogic/blogo>
             AuthType Basic
             AuthName "FedDev"
             AuthUserFile /local/etc/auth-file
             Require valid-user
           # Note: For Apache 2.4, instead use:
           # Require dacs-authz
           </Location>

       A Location under Basic authentication also is defined where the
       autologin utility is deployed:

           <Location /metalogic/dacs-native>
             AuthType Basic
             AuthName "FedDev"
             AuthUserFile /local/etc/auth-file
             Require valid-user
           # Note: For Apache 2.4, instead use:
           # Require dacs-authz
           </Location>

       At the same time, other content in METALOGIC is protected by DACS:

           <Location /metalogic/dev>
             Allow from all
             AuthType DACS
             AuthDACS dacs-acs
             Require valid-user
           # Note: For Apache 2.4, instead use:
           # Require dacs-authz
           </Location>

           Note
           Basic authentication cannot be specified in a subdirectory of a
           directory or location that has been configured for DACS access
           control. As above, DACS and Basic authentication must be configured
           in separate locations.

       In the DACS configuration file, dacs.conf, jurisdiction METALOGIC is
       configured as follows:

           <Jurisdiction uri="example.com/metalogic">

           JURISDICTION_NAME "METALOGIC"

           ACS_ERROR_HANDLER "902 https://example.com/metalogic/dacs-native/autologin\
           ?DACS_CONF=${Conf::DACS_CONF}&amp;JURISDICTION_URI=example.com/metalogic"

           <!-- Authenticate using Apache Basic/Digest Auth. -->
           <Auth id="native">
           URL "https://example.com/metalogic/dacs/local_native_authenticate"
           STYLE "native"
           CONTROL "sufficient"
           </Auth>

           </Jurisdiction>

           Note
           The native style of authentication must be configured when
           autologin is being used as described. See dacs_authenticate(8)[6].

       The preceding configuration results in the following behaviour. A user
       accessing Blogo directly (https://example.com/metalogic/blogo) is
       challenged to enter a valid username and password (with respect to the
       Apache accounts in /local/etc/auth-file). If the user subsequently
       accesses DACS content requiring DACS authentication but no DACS
       credentials are present:

       ·   The 902 event handler is invoked, resulting in a browser redirect
           to autologin.

       ·   The REMOTE_USER environment variable is present in the environment
           as a result of successful Basic authentication.

       ·   autologin runs dacs_authenticate (as a command, not as a web
           service).

       ·   dacs_authenticate then invokes local_native_authenticate, which
           uses the value of REMOTE_USER as the USERNAME argument.

       ·   If authentication succeeds, DACS credentials for REMOTE_USER in
           jurisdiction METALOGIC are generated. These credentials are
           returned to the browser within a cookie and the browser is
           redirected to the value of DACS_ERROR_URL (recall that
           DACS_ERROR_URL was passed to autologin by dacs_acs when the 902
           handler was invoked and is forwarded to dacs_authenticate).

       If the user accesses DACS content without first visiting the Blogo
       application, the 902 event handler fires, resulting in a browser
       redirect to autologin. Since autologin is itself behind Basic
       authentication, the user will be prompted for a username and password.
       Once Basic authentication succeeds, autologin is invoked with
       REMOTE_USER set (and therefore so is dacs_authenticate) and the process
       described above is repeated.

       autologin may also be used as the target of an explicit authentication
       link. For example:

           <a href="https://example.com/metalogic/dacs-native/autologin?\
           DACS_CONF=/local/dacs/federations/example.com/dacs.conf&\
           DACS_SET_JURISDICTION=METALOGIC&\
           JURISDICTION_URI=example.com/metalogic&\
           DACS_ERROR_URL=https://example.com">Login</a>

       Following the link above results first in a Basic authentication
       challenge and then sets DACS credentials in jurisdiction METALOGIC.

NOTES

       autologin cannot generate credentials in a jurisdiction other than the
       one in which autologin is deployed.

       The behaviour of browsers with respect to the HTTP 401 Authorization
       status code may have undesired consequences. For example, browsers
       continually send username and password in any matching request. If a
       user does not exit the browser, this can result in DACS credentials
       automatically being regenerated long after their configured lifetime
       has expired.  RFC 2617[2] provides no way for the server to "signout" a
       user, and neither do many browsers (Firefox[7] is an exception), other
       than by ending the browser session. This makes it inconvenient for a
       user to reauthenticate with respect to DACS using this technique.

DIAGNOSTICS

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

SEE ALSO

       dacs_authenticate(8)[3] (in particular, the native authentication
       style), dacs_autologin_ssl(8)[8], dacs_acs(8)[5], dacs.conf(5)[9]

AUTHOR

       Metalogic Software Corp.[10] and Distributed Systems Software
       (www.dss.ca[11])

COPYING

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

NOTES

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

        2. RFC 2617
           http://www.rfc-editor.org/rfc/rfc2617.txt

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

        4. HTTP Authentication
           http://dacs.dss.ca/man/dacs_acs.8.html#http_authentication

        5. dacs_acs(8)
           http://dacs.dss.ca/man/dacs_acs.8.html

        6. dacs_authenticate(8)
           http://dacs.dss.ca/man/dacs_authenticate.8.html#local_native_authenticate

        7. Firefox
           http://www.mozilla.com/firefox

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

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

       10. Metalogic Software Corp.
           http://fedroot.com/admin/about-metalogic.shtml

       11. www.dss.ca
           http://www.dss.ca

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