Ubuntu Manpage: autologin - Convert an Apache identity to a DACS identity

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.

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)

NAME

SYNOPSIS

DESCRIPTION

OPTIONS

EXAMPLE

NOTES

DIAGNOSTICS

SEE ALSO

AUTHOR

COPYING

NOTES