.\" 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_signout
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets v1.79.1 <http://docbook.sf.net/>
.\"      Date: 02/19/2019
.\"    Manual: DACS Web Services Manual
.\"    Source: DACS 1.4.40
.\"  Language: English
.\"
.TH "DACS_SIGNOUT" "8" "02/19/2019" "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_signout \- \fBDACS\fR signout service
.SH "SYNOPSIS"
.HP \w'\fBdacs_signout\fR\ 'u
\fBdacs_signout\fR [\fI\m[blue]\fBdacsoptions\fR\m[]\&\s-2\u[1]\d\s+2\fR]
.SH "DESCRIPTION"
.PP
This web service is part of the
\fBDACS\fR
suite\&.
.PP
The
\fBdacs_signout\fR
web service is invoked from a web browser to cause one or more sets of
\fBDACS\fR
credentials
\fIfor the \fR\fI\m[blue]\fBcurrent federation\fR\m[]\&\s-2\u[2]\d\s+2\fR, stored as HTTP cookies, to be removed from the browser\&. This is done by replacing one or more existing cookies with cookies that have expired\&. The effect is that the user agent signs out (logs off) identities previously obtained through
\m[blue]\fBdacs_authenticate(8)\fR\m[]\&\s-2\u[3]\d\s+2
or any other
\fBDACS\fR
authentication method\&. A
\fBDACS\fR\-enabled portal will typically provide users with a link or web page form to invoke this service\&.
.PP
By default, all credentials are removed, but credentials can be selected for deletion based on a particular username (who the user was authenticated as) or a particular jurisdiction (the jurisdiction that performed that authentication)\&.
.PP
Should copies of the selected credentials exist outside of the browser, they may still be valid; only the browser\*(Aqs copies are destroyed\&.
.PP
The
\m[blue]\fBSIGNOUT_HANDLER\fR\m[]\&\s-2\u[4]\d\s+2
directive can optionally be used to specify where the user should be redirected before this service terminates, provided HTML output is being produced (i\&.e\&., the
\fIFORMAT\fR
does not select a variety of XML output or JSON output)\&. If XML output is selected, a document conforming to
\m[blue]\fBdacs_current_credentials\&.dtd\fR\m[]\&\s-2\u[5]\d\s+2
is returned\&. If JSON output is selected, a document conforming to
\m[blue]\fBdacs_current_credentials\&.rnc\fR\m[]\&\s-2\u[6]\d\s+2
is returned\&.
.PP
Explicitly signing off using this web service is generally unnecessary because
\fBDACS\fR
credentials will either become invalid when their lifetime is reached (see
\m[blue]\fBAUTH_CREDENTIALS_DEFAULT_LIFETIME_SECS\fR\m[]\&\s-2\u[7]\d\s+2) or will be automatically deleted when the user\*(Aqs browser session terminates (or a session with a trusted servlet ends)\&. A user can also sign off by deleting his browser\*(Aqs
\fBDACS\fR
cookies\&. Middleware can simply discard cookies\&.
.PP
As
\fBDACS\fR
credentials are relative to a particular federation of
\fBDACS\fR
servers, only those credentials that are associated with the federation of the
\fBDACS\fR
server that receives the service request will be affected by this service\&. This implies that a user who wants to explicitly sign out must do so for each federation in which he or she is currently authenticated\&.
.SS "Web Service Arguments"
.PP
In addition to the
\m[blue]\fBstandard CGI arguments\fR\m[]\&\s-2\u[8]\d\s+2,
\fBdacs_signout\fR
understands the following CGI arguments:
.PP
\fIDACS_USERNAME\fR
.RS 4
If present, all credentials associated with this username will be deleted\&. If not provided, the username in the credentials is immaterial\&.
.RE
.PP
\fIDACS_JURISDICTION\fR
.RS 4
If present, all credentials associated with this jurisdiction (given as its
\m[blue]\fBJURISDICTION_NAME\fR\m[]\&\s-2\u[9]\d\s+2) will be deleted\&. If not provided, the jurisdiction in the credentials is immaterial\&.
.RE
.PP
\fIDACS_SIGNOUT_HANDLER\fR
.RS 4
If permitted by the
\m[blue]\fBSIGNOUT_HANDLER\fR\m[]\&\s-2\u[4]\d\s+2
directive and HTML output has been selected, redirect the user\*(Aqs browser to the URL specified by this parameter, which may contain a properly escaped query string\&. Whether the
GET
method is used depends on the context of the original request (and keep in mind that
GET
parameters may be visible and logged)\&. This URL is not validated by
\fBDACS\fR\&. When not explicitly permitted by the
\m[blue]\fBSIGNOUT_HANDLER\fR\m[]\&\s-2\u[4]\d\s+2
directive, this parameter is ignored\&.
.RE
.PP
\fICOOKIE_SYNTAX\fR
.RS 4
This optional parameter is as described for the
\m[blue]\fBdacs_authenticate(8)\fR\m[]\&\s-2\u[3]\d\s+2
service\&.
.RE
.PP
The optional parameters are used to delete only those credentials that match a particular username or jurisdiction (or both)\&. If neither parameter is specified in the service request, all
\fBDACS\fR
cookies associated with the federation that receives the service request will be deleted\&.
.PP
The name matching method can be configured through the
\m[blue]\fBNAME_COMPARE\fR\m[]\&\s-2\u[10]\d\s+2
directive\&.
.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
\fBDACS\fR
does not currently provide an inactivity timeout feature, but it may appear in a future release\&. One way to add it would be to take advantage of the
\m[blue]\fBuser tracking\fR\m[]\&\s-2\u[11]\d\s+2
capability, which can record all of a user\*(Aqs requests for
\fBDACS\fR\-wrapped services within a federation\&. By simply comparing the current time with the time stamp of the user\*(Aqs last service request, the user\*(Aqs idle time can be determined\&. If the idle time exceeds a configured maximum,
\m[blue]\fBdacs_acs(8)\fR\m[]\&\s-2\u[12]\d\s+2
would consider the user\*(Aqs credentials to be invalid (effectively expired) and take appropriate action\&. A straightforward implementation would be a relatively simple enhancement to
\fBDACS\fR; its main drawback, for those that enable it, is the extra performance hit incurred from user tracking and having to compute idle time during access control processing \- the significance of this cost will depend on your platforms, the configuration of your federation, and user activity patterns\&.
.sp .5v
.RE
.SH "EXAMPLES"
.PP
To signout from
\fIall\fR
identities in the
EXAMPLE
federation, a user would simply invoke a URL like:
.sp
.if n \{\
.RS 4
.\}
.nf
https://dss\&.example\&.com/cgi\-bin/dacs/dacs_signout
.fi
.if n \{\
.RE
.\}
.PP
To signout only from the identity
EXAMPLE::FEDROOT:bobo, a URL like the following might be invoked:
.sp
.if n \{\
.RS 4
.\}
.nf
https://fedroot\&.example\&.com/cgi\-bin/dacs/dacs_signout?\e
DACS_USERNAME=bobo&DACS_JURISDICTION=FEDROOT
.fi
.if n \{\
.RE
.\}
.PP
To signout from only those identities in the
EXAMPLE
federation having a username component
bobo, invoke a URL like:
.sp
.if n \{\
.RS 4
.\}
.nf
https://fedroot\&.example\&.com/cgi\-bin/dacs/dacs_signout?DACS_USERNAME=bobo
.fi
.if n \{\
.RE
.\}
.sp
This would signoff from
EXAMPLE::FEDROOT:bobo
and
EXAMPLE::DSS:bobo, for instance\&.
.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[3]\d\s+2,
\m[blue]\fBdacs_current_credentials(8)\fR\m[]\&\s-2\u[13]\d\s+2,
\m[blue]\fBdacs_auth_agent(8)\fR\m[]\&\s-2\u[14]\d\s+2,
\m[blue]\fBdacs_auth_transfer(8)\fR\m[]\&\s-2\u[15]\d\s+2,
\m[blue]\fBdacs_select_credentials(8)\fR\m[]\&\s-2\u[16]\d\s+2,
\m[blue]\fBdacsauth(1)\fR\m[]\&\s-2\u[17]\d\s+2,
\m[blue]\fBdacscred(1)\fR\m[]\&\s-2\u[18]\d\s+2
.PP
The
\fBDACS\fR
distribution includes an example of a "log off" web page:
\m[blue]\fBhtml/examples/signout\&.html\fR\m[]\&\s-2\u[19]\d\s+2\&.
.SH "BUGS"

It might be useful for the non\-HTML formats to provide configured or
requested signout handler URLs\&.
.SH "AUTHOR"
.PP
Distributed Systems Software (\m[blue]\fBwww\&.dss\&.ca\fR\m[]\&\s-2\u[20]\d\s+2)
.SH "COPYING"
.PP
Copyright \(co 2003\-2012 Distributed Systems Software\&. See the
\m[blue]\fBLICENSE\fR\m[]\&\s-2\u[21]\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
current federation
.RS 4
\%http://dacs.dss.ca/man/dacs.1.html#current_federation
.RE
.IP " 3." 4
dacs_authenticate(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_authenticate.8.html
.RE
.IP " 4." 4
SIGNOUT_HANDLER
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html#SIGNOUT_HANDLER
.RE
.IP " 5." 4
dacs_current_credentials.dtd
.RS 4
\%http://dacs.dss.ca/man/../dtd-xsd/dacs_current_credentials.dtd
.RE
.IP " 6." 4
dacs_current_credentials.rnc
.RS 4
\%http://dacs.dss.ca/man/../dtd-xsd/dacs_current_credentials.rnc
.RE
.IP " 7." 4
AUTH_CREDENTIALS_DEFAULT_LIFETIME_SECS
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html#AUTH_CREDENTIALS_DEFAULT_LIFETIME_SECS
.RE
.IP " 8." 4
standard CGI arguments
.RS 4
\%http://dacs.dss.ca/man/dacs.services.8.html#standard_cgi_args
.RE
.IP " 9." 4
JURISDICTION_NAME
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html#JURISDICTION_NAME
.RE
.IP "10." 4
NAME_COMPARE
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html#NAME_COMPARE
.RE
.IP "11." 4
user tracking
.RS 4
\%http://dacs.dss.ca/man/dacs.1.html#tracking_user_activity
.RE
.IP "12." 4
dacs_acs(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_acs.8.html
.RE
.IP "13." 4
dacs_current_credentials(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_current_credentials.8.html
.RE
.IP "14." 4
dacs_auth_agent(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_auth_agent.8.html
.RE
.IP "15." 4
dacs_auth_transfer(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_auth_transfer.8.html
.RE
.IP "16." 4
dacs_select_credentials(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_select_credentials.8.html
.RE
.IP "17." 4
dacsauth(1)
.RS 4
\%http://dacs.dss.ca/man/dacsauth.1.html
.RE
.IP "18." 4
dacscred(1)
.RS 4
\%http://dacs.dss.ca/man/dacscred.1.html
.RE
.IP "19." 4
html/examples/signout.html
.RS 4
\%http://dacs.dss.ca/man//examples/signout.html
.RE
.IP "20." 4
www.dss.ca
.RS 4
\%http://www.dss.ca
.RE
.IP "21." 4
LICENSE
.RS 4
\%http://dacs.dss.ca/man/../misc/LICENSE
.RE