autologin

AUTOLOGIN(8)                DACS Web Services Manual                AUTOLOGIN(8)



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) invokes 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
           This web service is deprecated in favour of the RFC 2617[2]
           capability built-in to DACS. For details, please refer to the HTTP
           Authentication[4] section in dacs_acs(8)[5].

           Security
           autologin is not installed by default when DACS is built, in part
           because it can be a bit tricky to configure correctly and securely.
           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 automatically 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 other than by ending the browser session or
       clearing browser history appropriately. This makes it inconvenient for a
       user to reauthenticate with respect to DACS using this technique.

DIAGNOSTICS
       The program exits 0 if successful, 1 if an error occurred.

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

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

COPYING
       Copyright © 2003-2014 Distributed Systems Software. See the LICENSE[11]
       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. dacs_autologin_ssl(8)
           http://dacs.dss.ca/man/dacs_autologin_ssl.8.html

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

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

       10. www.dss.ca
           http://www.dss.ca

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



DACS 1.4.40                        02/19/2019                       AUTOLOGIN(8)