.\" 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_select_credentials
.\"    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_SELECT_CREDENTI" "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_select_credentials \- temporarily disable \fBDACS\fR credentials
.SH "SYNOPSIS"
.HP \w'\fBdacs_select_credentials\fR\ 'u
\fBdacs_select_credentials\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
A user may concurrently possess more than one set of
\fBDACS\fR
credentials during a session, with each representing a different identity\&. Zero or more credentials may be submitted with a request for a
\fBDACS\fR\-wrapped web service\&. It is sometimes desirable or necessary for a user to switch between identities, or to be considered unauthenticated\&. Middleware (software situated between a user agent and a
\fBDACS\fR\-capable web server) and more sophisticated user agents might provide this functionality simply by sending some
\fBDACS\fR
HTTP cookies and not sending others, under user control\&. With standard browsers or in other situations where this functionality is not available, achieving this by repeatedly authenticating and signing off (or by manually deleting cookies) would be inconvenient at best\&.
.PP
The
\fBdacs_select_credentials\fR
web service can be used to temporarily disable credentials, leaving the remaining credentials selected for access control purposes\&. The user agent continues to send all
\fBDACS\fR
HTTP cookies as usual, but
\m[blue]\fBdacs_acs(8)\fR\m[]\&\s-2\u[2]\d\s+2
will ignore disabled identities before deciding to grant or deny access\&. This feature can be used to work around the maximum number of identities that
\fBDACS\fR
allows to be associated with a request \- determined by the
\m[blue]\fBACS_CREDENTIALS_LIMIT\fR\m[]\&\s-2\u[3]\d\s+2
directive \- or for administrative, testing, or other reasons\&. There are similarities between
\fBdacs_select_credentials\fR
and
\m[blue]\fBsu(1)\fR\m[]\&\s-2\u[4]\d\s+2\&.
.PP
A selected identity is handled normally, but a disabled identity is "hidden"; it is not considered for access control purposes and is not reported by
\m[blue]\fBdacs_current_credentials(8)\fR\m[]\&\s-2\u[5]\d\s+2\&. A disabled identity may be re\-enabled by
\fBdacs_select_credentials\fR, however, and
\m[blue]\fBdacs_signout(8)\fR\m[]\&\s-2\u[6]\d\s+2
will work with disabled identities\&. All identities are considered for the purposes of revoking access, however, and in other situations described below\&.
.PP
The selected credentials are identified by a cryptographically protected cookie that is issued by
\fBdacs_select_credentials\fR\&. The HTTP cookie name has the following format:
.sp
.if n \{\
.RS 4
.\}
.nf
DACS:\fIFederation\-Name\fR::::SELECTED
.fi
.if n \{\
.RE
.\}
.sp
where
\fIFederation\-Name\fR
is the official name assigned to the federation for which the cookie is valid (see
\m[blue]\fBCOOKIE_NAME_TERMINATORS\fR\m[]\&\s-2\u[7]\d\s+2)\&. This cookie confers no identity or access control rights to its possessor\&. If this cookie is deleted, or just not sent with a request, all credentials accompanying the request are used for access control\&. If
\m[blue]\fBdacs_signout(8)\fR\m[]\&\s-2\u[6]\d\s+2
asks the browser to delete all credentials (i\&.e\&., no more credentials exist that
\fBdacs_signout\fR
is aware of), it will also ask the browser to delete the selected credentials cookie\&.
.PP
The
\fIFORMAT\fR
argument (see
\m[blue]\fBdacs(1)\fR\m[]\&\s-2\u[8]\d\s+2) determines the type of output, with the default being HTML, using the style sheet
\m[blue]\fBdacs_select_credentials\&.css\fR\m[]\&\s-2\u[9]\d\s+2\&. If XML output is selected, a document conforming to
\m[blue]\fBdacs_select_credentials\&.dtd\fR\m[]\&\s-2\u[10]\d\s+2
is returned\&. The
JSON
format (\m[blue]\fBRFC 7159\fR\m[]\&\s-2\u[11]\d\s+2) is also recognized\&.
.SH "OPTIONS"
.SS "Web Service Arguments"
.PP
\fBdacs_select_credentials\fR
accepts the following arguments in addition to the
\m[blue]\fBstandard CGI arguments\fR\m[]\&\s-2\u[12]\d\s+2\&.
.PP
\fIOPERATION\fR
.RS 4
This parameter is required and must be one of (case\-insensitively):
.PP
SELECT
.RS 4
This operation replaces the current set of selected credentials, if any, with the set that match the
\fIDACS_USERNAME\fR
and
\fIDACS_JURISDICTION\fR
arguments\&. It is an error if no credentials match the arguments\&.
.RE
.PP
DESELECT
.RS 4
This operation disables the specified enabled credentials\&. If no credentials remain selected, the user is effectively unauthenticated as if by the
\fISELECT_UNAUTH\fR
operation\&. Non\-matching arguments are ignored\&.
.RE
.PP
ADD
.RS 4
The
\fIADD\fR
operation adds the specified disabled credentials to the set of enabled credentials\&.
.RE
.PP
LIST
.RS 4
This operation lists the selection status\&.
.RE
.PP
CLEAR
.RS 4
This operation results in no selection, with all credentials available again\&.
.RE
.PP
SELECT_UNAUTH
.RS 4
This operation makes the user effectively unauthenticated; all credentials are disabled\&.
.RE
.PP
DESELECT_UNAUTH
.RS 4
This operation reverses
\fISELECT_UNAUTH\fR, resulting in there being no selection and all credentials are again available\&. It is an error if the user is not effectively unauthenticated when the operation is invoked\&.
.RE
.sp
.RE
.PP
\fIDACS_USERNAME\fR
.RS 4
This argument specifies a username to match against existing credentials for the
SELECT,
DESELECT, and
ADD
operations\&. Exact string matching is used\&. If this argument is absent, all usernames will be selected\&.
.RE
.PP
\fIDACS_JURISDICTION\fR
.RS 4
This argument specifies a jurisdiction name to match against existing credentials for the
SELECT,
DESELECT, and
ADD
operations\&. Exact string matching is used\&. If this argument is absent, all jurisdictions will be selected\&.
.RE
.PP
\fICOOKIE_SYNTAX\fR
.RS 4
This parameter has the same semantics as with the
\m[blue]\fBdacs_authenticate(8)\fR\m[]\&\s-2\u[13]\d\s+2
service\&.
.RE
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBTip\fR
.ps -1
.br
.PP
The
\m[blue]\fBdacs_authenticate(8)\fR\m[]\&\s-2\u[14]\d\s+2
web service takes an optional argument,
\fIOPERATION\fR, that can have the value
SELECT\&. If authentication succeeds and this argument is present, the resulting credentials are selected as described above\&.
.sp .5v
.RE
.SH "FILES"
.PP
\m[blue]\fBdacs_select_credentials\&.css\fR\m[]\&\s-2\u[9]\d\s+2
.SH "DIAGNOSTICS"
.PP
The program exits
0
if everything was fine,
1
if an error occurred\&.
.SH "BUGS"
.PP
It might be useful to be able to temporarily suppress one or more specific roles of a given identity\&.
.SH "SEE ALSO"
.PP
\m[blue]\fBdacs_authenticate(8)\fR\m[]\&\s-2\u[14]\d\s+2,
\m[blue]\fBdacs_signout(8)\fR\m[]\&\s-2\u[6]\d\s+2
.SH "AUTHOR"
.PP
Distributed Systems Software (\m[blue]\fBwww\&.dss\&.ca\fR\m[]\&\s-2\u[15]\d\s+2)
.SH "COPYING"
.PP
Copyright \(co 2003\-2018 Distributed Systems Software\&. See the
\m[blue]\fBLICENSE\fR\m[]\&\s-2\u[16]\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_acs(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_acs.8.html
.RE
.IP " 3." 4
ACS_CREDENTIALS_LIMIT
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html#ACS_CREDENTIALS_LIMIT
.RE
.IP " 4." 4
su(1)
.RS 4
\%https://www.freebsd.org/cgi/man.cgi?query=su&apropos=0&sektion=1&manpath=FreeBSD+10.3-RELEASE&format=html
.RE
.IP " 5." 4
dacs_current_credentials(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_current_credentials.8.html
.RE
.IP " 6." 4
dacs_signout(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_signout.8.html
.RE
.IP " 7." 4
COOKIE_NAME_TERMINATORS
.RS 4
\%http://dacs.dss.ca/man/dacs.conf.5.html#COOKIE_NAME_TERMINATORS
.RE
.IP " 8." 4
dacs(1)
.RS 4
\%http://dacs.dss.ca/man/dacs.1.html
.RE
.IP " 9." 4
dacs_select_credentials.css
.RS 4
\%http://dacs.dss.ca/man//css/dacs_select_credentials.css
.RE
.IP "10." 4
dacs_select_credentials.dtd
.RS 4
\%http://dacs.dss.ca/man/../dtd-xsd/dacs_select_credentials.dtd
.RE
.IP "11." 4
RFC 7159
.RS 4
\%https://tools.ietf.org/html/rfc7159
.RE
.IP "12." 4
standard CGI arguments
.RS 4
\%http://dacs.dss.ca/man/dacs.services.8.html#standard_cgi_args
.RE
.IP "13." 4
dacs_authenticate(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_authenticate.8.html#COOKIE_SYNTAX
.RE
.IP "14." 4
dacs_authenticate(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_authenticate.8.html
.RE
.IP "15." 4
www.dss.ca
.RS 4
\%http://www.dss.ca
.RE
.IP "16." 4
LICENSE
.RS 4
\%http://dacs.dss.ca/man/../misc/LICENSE
.RE