.\" Copyright (c) 2003-2012
.\" Distributed Systems Software.  All rights reserved.
.\" See the file LICENSE for redistribution information.
.\" $Id: copyright-nr 2564 2012-03-02 00:17:08Z brachman $
'\" t
.\"     Title: autologin
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 08/23/2020
.\"    Manual: DACS Web Services Manual
.\"    Source: DACS 1.4.40
.\"  Language: English
.\"
.TH "AUTOLOGIN" "8" "08/23/2020" "DACS 1.4.40" "DACS Web Services Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
autologin \- Convert an Apache identity to a \fBDACS\fR identity
.SH "SYNOPSIS"
.HP \w'\fBautologin\fR\ 'u
\fBautologin\fR [\fI\m[blue]\fBdacsoptions\fR\m[]\&\s-2\u[1]\d\s+2\fR]
.SH "DESCRIPTION"
.PP
This program is part of the
\fBDACS\fR
suite\&.
.PP
The
\fBautologin\fR
CGI program, in conjunction with appropriate
\fBApache\fR
and
\fBDACS\fR
configuration, is used to automatically convert an identity already established by
\fBApache\fR
into a
\fBDACS\fR
identity\&. After standard HTTP Basic or Digest Authentication (\m[blue]\fBRFC 2617\fR\m[]\&\s-2\u[2]\d\s+2) has been performed successfully,
\fBautologin\fR
causes
\fBDACS\fR
credentials to be generated and returned\&. This capability lets
\fBDACS\fR
leverage any of
\fBApache\*(Aqs\fR
existing authentication methods through simple configuration\&.
.PP
A user that has completed Basic or Digest Authentication (following a
401 Authorization Required
response from the web server) invokes
\fBautologin\fR\&.
\fBautologin\fR
generates credentials by constructing a request to
\m[blue]\fBdacs_authenticate(8)\fR\m[]\&\s-2\u[3]\d\s+2\&. The value of the
\fBREMOTE_USER\fR
environment variable, as set by
\fBApache\fR, is used by
\fBdacs_authenticate\fR
to derive the
\fBDACS\fR
username\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.PP
This web service is deprecated in favour of the
\m[blue]\fBRFC 2617\fR\m[]\&\s-2\u[2]\d\s+2
capability built\-in to
\fBDACS\fR\&. For details, please refer to the
\m[blue]\fBHTTP Authentication\fR\m[]\&\s-2\u[4]\d\s+2
section in
\m[blue]\fBdacs_acs(8)\fR\m[]\&\s-2\u[5]\d\s+2\&.
.sp .5v
.RE
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBSecurity\fR
.ps -1
.br
.PP
\fBautologin\fR
is not installed by default when
\fBDACS\fR
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
\fBDACS\fR
administrator\&.
.sp .5v
.RE
.SH "OPTIONS"
.PP
Only the standard
\m[blue]\fB\fIdacsoptions\fR\fR\m[]\&\s-2\u[1]\d\s+2
command line arguments are recognized\&.
.SS "Web Service Arguments"
.PP
\fBautologin\fR
understands the following CGI arguments\&. All arguments are required unless otherwise indicated\&.
.PP
\fIDACS_CONF\fR
.RS 4
The path to the
\fBDACS\fR
configuration file that should be used to locate jurisdiction configuration information needed by
\fBdacs_authenticate\fR\&.
.RE
.PP
\fIDACS_ERROR_URL\fR
.RS 4
When
\fBautologin\fR
is invoked as a result of
\fBDACS\fR
event handling,
\fIDACS_ERROR_URL\fR
is automatically passed by
\m[blue]\fBdacs_acs(8)\fR\m[]\&\s-2\u[5]\d\s+2
and represents the original URL to which access was denied\&. In typical use,
\fBautologin\fR
is configured as the handler for a
\fBdacs_acs\fR
\fB902\fR
error code (NO_AUTH, "Authentication by DACS is required")\&.
\fBautologin\fR
then invokes
\fBdacs_authenticate\fR\&. If
\fBDACS\fR
authentication is successful,
\fBdacs_authenticate\fR
ordinarily issues a browser redirect to the value of
\fIDACS_ERROR_URL\fR
and a cookie bearing the credentials are set in the browser (but see the
\fINOREDIRECT\fR
argument)\&.
.RE
.PP
\fINOREDIRECT\fR
.RS 4
If this optional argument is present (its value is immaterial),
\fBautologin\fR
instructs
\fBdacs_authenticate\fR
to
\fInot\fR
issue a browser redirect to the value of
\fIDACS_ERROR_URL\fR\&.
.RE
.PP
\fIDACS_JURISDICTION\fR
.RS 4
When
\fBautologin\fR
is invoked as a result of
\fBDACS\fR
event handling,
\fIDACS_JURISDICTION\fR
is automatically set by
\fBDACS\fR
to the name of the jurisdiction that received the request\&. By default,
\fBautologin\fR
generates credentials for the jurisdiction at which
\fBdacs_authenticate\fR
is invoked (specifically,
\fIDACS_JURISDICTION\fR)\&. This can be overridden by the
\fIDACS_SET_JURISDICTION\fR
parameter\&.
.RE
.PP
\fIDACS_SET_JURISDICTION\fR
.RS 4
This optional argument explicitly names the jurisdiction in which
\fBautologin\fR
should generate credentials\&.
\fIDACS_SET_JURISDICTION\fR
overrides the value, if any, of
\fIDACS_JURISDICTION\fR
and
\fImust be the same as the jurisdiction in which \fR\fI\fBautologin\fR\fR\fI is deployed\fR\&.
.RE
.PP
\fIJURISDICTION_URI\fR
.RS 4
This is the URI identifying the jurisdiction in the
\fBDACS\fR
configuration file corresponding to the value specified in a
\fIDACS_JURISDICTION\fR
or
\fIDACS_SET_JURISDICTION\fR
argument\&. This argument is optional since the jurisdiction name can be used for this purpose\&.
.RE
.PP
\fIjust_dump_stdin\fR
.RS 4
This optional argument is useful for debugging\&. If the value of
\fBQUERY_STRING\fR
is exactly
jump_dump_stdin, then the program will simply copy its standard input to the standard output as
text/plain\&.
.RE
.SH "EXAMPLE"
.PP
A typical use of
\fBautologin\fR
is to support coexistence on the same Web site of
\fBDACS\fR\-wrapped content, services\&. legacy applications, or content deployed under HTTP Basic or Digest Authentication\&. The following example illustrates configuration of
\fBApache\fR
and
\fBDACS\fR
for the deployment under HTTP Basic Authentication of a web log application,
\fBBlogo\fR\&.
\fBBlogo\fR
will be deployed within a
\fBDACS\fR
jurisdiction
METALOGIC\&. The URI space of interest will be
example\&.com/metalogic/*\&.
.PP
In the
\fBApache\fR
configuration file
httpd\&.conf, a
Location
is defined for the
\fBBlogo\fR
application under Basic Authentication:
.sp
.if n \{\
.RS 4
.\}
.nf
<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>
.fi
.if n \{\
.RE
.\}
.PP
A
Location
under Basic Authentication also is defined where the
\fBautologin\fR
utility is deployed:
.sp
.if n \{\
.RS 4
.\}
.nf
<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>
.fi
.if n \{\
.RE
.\}
.PP
At the same time, other content in
METALOGIC
is protected by
\fBDACS\fR:
.sp
.if n \{\
.RS 4
.\}
.nf
<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>
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.PP
Basic Authentication cannot be specified in a subdirectory of a directory or location that has been configured for
\fBDACS\fR
access control\&. As above,
\fBDACS\fR
and Basic Authentication must be configured in separate locations\&.
.sp .5v
.RE
.PP
In the
\fBDACS\fR
configuration file,
dacs\&.conf, jurisdiction
METALOGIC
is configured as follows:
.sp
.if n \{\
.RS 4
.\}
.nf
<Jurisdiction uri="example\&.com/metalogic">

JURISDICTION_NAME "METALOGIC"

ACS_ERROR_HANDLER "902 https://example\&.com/metalogic/dacs\-native/autologin\e
?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>
.fi
.if n \{\
.RE
.\}
.sp
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.PP
The
native
style of authentication
\fImust\fR
be configured when
\fBautologin\fR
is being used as described\&. See
\m[blue]\fBdacs_authenticate(8)\fR\m[]\&\s-2\u[6]\d\s+2\&.
.sp .5v
.RE
.PP
The preceding configuration results in the following behaviour\&. A user accessing
\fBBlogo\fR
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
\fBDACS\fR
content requiring
\fBDACS\fR
authentication but no
\fBDACS\fR
credentials are present:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
The
\fB902\fR
event handler is invoked, resulting in a browser redirect to
\fBautologin\fR\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
The
\fBREMOTE_USER\fR
environment variable is present in the environment as a result of successful Basic Authentication\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBautologin\fR
runs
\fBdacs_authenticate\fR
(as a command, not as a web service)\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBdacs_authenticate\fR
then invokes
\fBlocal_native_authenticate\fR, which uses the value of
\fBREMOTE_USER\fR
as the
\fIUSERNAME\fR
argument\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
If authentication succeeds,
\fBDACS\fR
credentials for
\fBREMOTE_USER\fR
in jurisdiction
METALOGIC
are generated\&. These credentials are returned to the browser within a cookie and the browser is redirected to the value of
\fIDACS_ERROR_URL\fR
(recall that
\fIDACS_ERROR_URL\fR
was passed to
\fBautologin\fR
by
\fBdacs_acs\fR
when the
\fB902\fR
handler was invoked and is forwarded to
\fBdacs_authenticate\fR)\&.
.RE
.PP
If the user accesses
\fBDACS\fR
content without first visiting the
\fBBlogo\fR
application, the
\fB902\fR
event handler fires, resulting in a browser redirect to
\fBautologin\fR\&. Since
\fBautologin\fR
is itself behind Basic Authentication, the user will be prompted for a username and password\&. Once Basic Authentication succeeds,
\fBautologin\fR
is invoked with
\fBREMOTE_USER\fR
set (and therefore so is
\fBdacs_authenticate\fR) and the process described above is repeated\&.
.PP
\fBautologin\fR
may also be used as the target of an explicit authentication link\&. For example:
.sp
.if n \{\
.RS 4
.\}
.nf
<a href="https://example\&.com/metalogic/dacs\-native/autologin?\e
DACS_CONF=/local/dacs/federations/example\&.com/dacs\&.conf&\e
DACS_SET_JURISDICTION=METALOGIC&\e
JURISDICTION_URI=example\&.com/metalogic&\e
DACS_ERROR_URL=https://example\&.com">Login</a>
.fi
.if n \{\
.RE
.\}
.sp
Following the link above results first in a Basic Authentication challenge and then sets
\fBDACS\fR
credentials in jurisdiction
METALOGIC\&.
.SH "NOTES"
.PP
\fBautologin\fR
cannot generate credentials in a jurisdiction other than the one in which
\fBautologin\fR
is deployed\&.
.PP
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
\fBDACS\fR
credentials automatically being regenerated long after their configured lifetime has expired\&.
\m[blue]\fBRFC 2617\fR\m[]\&\s-2\u[2]\d\s+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
\fBDACS\fR
using this technique\&.
.SH "DIAGNOSTICS"
.PP
The program exits
0
if successful,
1
if an error occurred\&.
.SH "SEE ALSO"
.PP
\m[blue]\fBdacs_authenticate(8)\fR\m[]\&\s-2\u[3]\d\s+2
(in particular, the
native
authentication style),
\m[blue]\fBdacs_autologin_ssl(8)\fR\m[]\&\s-2\u[7]\d\s+2,
\m[blue]\fBdacs_acs(8)\fR\m[]\&\s-2\u[5]\d\s+2,
\m[blue]\fBdacs\&.conf(5)\fR\m[]\&\s-2\u[8]\d\s+2
.SH "AUTHOR"
.PP
\m[blue]\fBMetalogic Software Corp\&.\fR\m[]\&\s-2\u[9]\d\s+2
and Distributed Systems Software (\m[blue]\fBwww\&.dss\&.ca\fR\m[]\&\s-2\u[10]\d\s+2)
.SH "COPYING"
.PP
Copyright \(co 2003\-2014 Distributed Systems Software\&. See the
\m[blue]\fBLICENSE\fR\m[]\&\s-2\u[11]\d\s+2
file that accompanies the distribution for licensing information\&.
.SH "NOTES"
.IP " 1." 4
dacsoptions
.RS 4
\%http://dacs.dss.ca/man/dacs.1.html#dacsoptions
.RE
.IP " 2." 4
RFC 2617
.RS 4
\%http://www.rfc-editor.org/rfc/rfc2617.txt
.RE
.IP " 3." 4
dacs_authenticate(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_authenticate.8.html
.RE
.IP " 4." 4
HTTP Authentication
.RS 4
\%http://dacs.dss.ca/man/dacs_acs.8.html#http_authentication
.RE
.IP " 5." 4
dacs_acs(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_acs.8.html
.RE
.IP " 6." 4
dacs_authenticate(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_authenticate.8.html#local_native_authenticate
.RE
.IP " 7." 4
dacs_autologin_ssl(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_autologin_ssl.8.html
.RE
.IP " 8." 4
dacs.conf(5)
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html
.RE
.IP " 9." 4
Metalogic Software Corp.
.RS 4
\%http://fedroot.com/admin/about-metalogic.shtml
.RE
.IP "10." 4
www.dss.ca
.RS 4
\%http://www.dss.ca
.RE
.IP "11." 4
LICENSE
.RS 4
\%http://dacs.dss.ca/man/../misc/LICENSE
.RE