.\" 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: dacs_autologin_ssl
.\"    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 "DACS_AUTOLOGIN_SSL" "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"
dacs_autologin_ssl \- use an SSL client certificate to automatically obtain \fBDACS\fR credentials
.SH "SYNOPSIS"
.HP \w'\fBdacs_autologin_ssl\fR\ 'u
\fBdacs_autologin_ssl\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
\fBdacs_autologin_ssl\fR
CGI program, in conjunction with appropriate
\fBDACS\fR
configuration and a valid SSL client certificate, can be used for user\-transparent
\fBDACS\fR
authentication\&. A user is not prompted for a username or password, and no user\-visible sign\-on procedure takes place\&.
.PP
At present, the program merely acts as glue to indirectly invoke
\m[blue]\fBdacs_authenticate(8)\fR\m[]\&\s-2\u[2]\d\s+2\&. Any valid X\&.509 certificate can be used for this purpose, including a self\-signed certificate\&. Please refer to the
\m[blue]\fBOpenSSL\fR\m[]\&\s-2\u[3]\d\s+2
documentation for additional information about certificates\&.
.PP
This program can be used to automatically and transparently authenticate a user that has been issued an SSL client certificate\&. When an unauthenticated user is denied access to a
\fBDACS\fR\-wrapped resource, she can be automatically authenticated and redirected back to the resource without any user input or action\&. This assumes that the client certificate is sent automatically by the browser and that no additional user prompting is needed by the authenticating jurisdiction\&. For redirection to the original resource to work properly\&. the original request must have used the
GET
method\&.
.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
cert
style of authentication
\fImust\fR
be configured when
\fBdacs_autologin_ssl\fR
is being used as described\&. See
\m[blue]\fBdacs_authenticate(8)\fR\m[]\&\s-2\u[4]\d\s+2\&.
.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
\fBdasc_autologin_ssl\fR
understands the following CGI arguments\&.
.PP
\fIDACS_ERROR_URL\fR
.RS 4
When
\fBdacs_autologin_ssl\fR
is invoked as a result of
\fBDACS\fR
event handling,
\fIDACS_ERROR_URL\fR
is automatically passed to it 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,
\fBdacs_autologin_ssl\fR
is configured as the handler for a
\fBdacs_acs\fR
\fB902\fR
error code (NO_AUTH, "Authentication by DACS is required")\&.
\fBdacs_autologin_ssl\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)\&. This argument is optional; if not provided, the jurisdiction\*(Aqs configured post\-authentication action will occur\&.
.RE
.PP
\fINOREDIRECT\fR
.RS 4
If this optional argument is present (its value is immaterial),
\fBdacs_autologin_ssl\fR
instructs
\fBdacs_authenticate\fR
to
\fInot\fR
issue a browser redirect to the value of
\fIDACS_ERROR_URL\fR\&.
.RE
.PP
\fIAUTH_JURISDICTION\fR
.RS 4
If this optional argument is present, it gives the name of the jurisdiction at which authentication should take place\&. By default,
\fBdacs_authenticate\fR
is invoked at the same jurisdiction as
\fBdacs_autologin_ssl\fR\&.
.RE
.PP
\fICERT_NAME_ATTR\fR
.RS 4
This optional argument explicitly names the attribute in the certificate from which to set
\fIUSERNAME\fR\&. The default value is
\fISSL_CLIENT_S_DN_CN\fR\&. It is an error if the specified attribute name does not exist\&. Giving the value of
\fICERT_NAME_ATTR\fR
as the empty string results in the empty string being passed as the value of
\fIUSERNAME\fR\&.
.RE
.SH "EXAMPLE"
.PP
A typical use of
\fBdacs_autologin_ssl\fR
is to transparently authenticate a user via his SSL client certificate\&.
.PP
In the
\fBDACS\fR
configuration file,
dacs\&.conf, jurisdiction
EXAMPLE
is configured as follows (this excerpt from a configuration file uses fictitious domain names):
.sp
.if n \{\
.RS 4
.\}
.nf
<Jurisdiction uri="example\&.com">

JURISDICTION_NAME "EXAMPLE"

ACS_ERROR_HANDLER "NO_AUTH https://example\&.com/cgi\-bin/dacs/dacs_autologin_ssl"

<!\-\- Authenticate using an SSL certificate\&. \-\->
<Auth id="cert">
URL "https://example\&.com/cgi\-bin/dacs/local_cert_authenticate"
STYLE "cert"
CONTROL "sufficient"
CERT_CA_PATH "/usr/local/apache2\&.2/conf/ssl\&.crt"
CERT_NAME_ATTR "SSL_CLIENT_S_DN_CN"
</Auth>

</Jurisdiction>
.fi
.if n \{\
.RE
.\}
.PP
Assume the following access control rule applies to the request:
.sp
.if n \{\
.RS 4
.\}
.nf
<acl_rule status="enabled">
  <services>
    <service url_pattern=\*(Aq/foo\&.html\*(Aq/>
  </services>

  <rule order="allow,deny">
    <allow>
      user("auth")
    </allow>
  </rule>
</acl_rule>


.fi
.if n \{\
.RE
.\}
.PP
The preceding configuration results in the following behaviour\&. An unauthenticated user accessing
foo\&.html
(https://example\&.com/foo\&.html) is denied access because the rule governing that web page tests for authentication and no credentials are sent with the request\&. As a result, the
\m[blue]\fBACS_ERROR_HANDLER\fR\m[]\&\s-2\u[6]\d\s+2
directive causes the user to be redirected to
\fBdacs_autologin_ssl\fR, which redirects the user to
\fBdacs_authenticate\fR, passing arguments as necessary\&.
.PP
\fBdacs_authenticate\fR
then invokes
\m[blue]\fBlocal_cert_authenticate\fR\m[]\&\s-2\u[4]\d\s+2, passing it the client\*(Aqs certificate\&. The certificate is validated and a username is extracted from it and mapped to a valid
\fBDACS\fR
username\&.
.PP
If authentication succeeds,
\fBDACS\fR
credentials for the jurisdiction
EXAMPLE
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
\fBdacs_autologin_ssl\fR
by
\fBdacs_acs\fR
when the
\fB902\fR
handler was invoked and was forwarded to
\fBdacs_authenticate\fR)\&. In this example the user is redirected to
https://example\&.com/foo\&.html\&. Given the rule above, this time the user\*(Aqs request for
foo\&.html
will be granted\&.
.PP
\fBdacs_autologin_ssl\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/cgi\-bin/dacs/dacs_autologin_ssl?\e
AUTH_JURISDICTION=EXAMPLE&\e
DACS_ERROR_URL=https://example\&.com/cgi\-bin/dacs/dacs_current_credentials">Login</a>
.fi
.if n \{\
.RE
.\}
.sp
Following the link should result in the user being authenticated and redirected to the specified URL\&.
.SH "DIAGNOSTICS"
.PP
The program exits
0
if everything was fine,
1
if an error occurred\&.
.SH "SEE ALSO"
.PP
\m[blue]\fBdacs_authenticate(8)\fR\m[]\&\s-2\u[2]\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[7]\d\s+2,
\m[blue]\fBautologin(8)\fR\m[]\&\s-2\u[8]\d\s+2
.SH "AUTHOR"
.PP
Distributed Systems Software (\m[blue]\fBwww\&.dss\&.ca\fR\m[]\&\s-2\u[9]\d\s+2)
.SH "COPYING"
.PP
Copyright \(co 2003\-2012 Distributed Systems Software\&. See the
\m[blue]\fBLICENSE\fR\m[]\&\s-2\u[10]\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
dacs_authenticate(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_authenticate.8.html
.RE
.IP " 3." 4
OpenSSL
.RS 4
\%http://www.openssl.org
.RE
.IP " 4." 4
dacs_authenticate(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_authenticate.8.html#local_cert_authenticate
.RE
.IP " 5." 4
dacs_acs(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_acs.8.html
.RE
.IP " 6." 4
ACS_ERROR_HANDLER
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html#ACS_ERROR_HANDLER
.RE
.IP " 7." 4
dacs.conf(5)
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html
.RE
.IP " 8." 4
autologin(8)
.RS 4
\%http://dacs.dss.ca/man/autologin.8.html
.RE
.IP " 9." 4
www.dss.ca
.RS 4
\%http://www.dss.ca
.RE
.IP "10." 4
LICENSE
.RS 4
\%http://dacs.dss.ca/man/../misc/LICENSE
.RE