Provided by: dacs_1.4.28b-3ubuntu2_amd64 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