.\" 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_current_credentials
.\"    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_CURRENT_CREDENT" "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_current_credentials \- display \fBDACS\fR credentials
.SH "SYNOPSIS"
.HP \w'\fBdacs_current_credentials\fR\ 'u
\fBdacs_current_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
The
\fBdacs_current_credentials\fR
web service provides information about the credentials that accompany the request and the identities described by those credentials\&. It can be used to determine whether credentials are valid, confirm who they belong to, find out which roles are associated with the credentials, and so on\&.
.PP
If
\m[blue]\fBuser activity\fR\m[]\&\s-2\u[2]\d\s+2
data is available,
\fBdacs_current_credentials\fR
can also return information for the identity associated with each valid set of credentials, including the time of the last sign on and a description of any sign\-on that is still "active" (i\&.e\&., has not expired and was not signed off)\&. This information can be useful for detecting unauthorized account access, regardless of the authentication method used, and other potentially problematic activity\&.
.PP
The
\m[blue]\fB\fIFORMAT\fR argument\fR\m[]\&\s-2\u[3]\d\s+2
determines the type of output, with the default being HTML, using the style sheet
\m[blue]\fBdacs_current_credentials\&.css\fR\m[]\&\s-2\u[4]\d\s+2\&. 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, which supplies additional information\&. The
JSON
format (\m[blue]\fBRFC 7159\fR\m[]\&\s-2\u[6]\d\s+2) is also recognized\&. The
previous_auth
and
active_auth
elements appear only when user activity tracking data is accessible\&. The
previous_auth
element is empty if there are not two or more records of authentication activity for the associated identity\&. For a given identity, an
active_auth
element is present for each authentication event for which there is no corresponding sign off event, other than the most recent one, and for which the issued credentials have not expired \- these are "active sessions"\&. Reauthentication as the same identity does not create a sign off event, however, and signing off (e\&.g\&., via
\m[blue]\fBdacs_signout(8)\fR\m[]\&\s-2\u[7]\d\s+2) does not necessarily mean that a user agent has destroyed credentials (though that is normally the case)\&. Also, a user can unilaterally destroy credentials (e\&.g\&., by terminating a browser session or removing cookies manually), so not all active sessions necessarily exist\&.
.SH "OPTIONS"
.SS "Web Service Arguments"
.PP
\fBdacs_current_credentials\fR
accepts the following arguments in addition to the
\m[blue]\fBstandard CGI arguments\fR\m[]\&\s-2\u[8]\d\s+2\&.
.PP
\fIDETAIL\fR
.RS 4
If "yes", this optional argument requests additional information\&. It is recognized only in conjunction with XML format output\&. By default, this argument can only be used by a
\fBDACS\fR
administrator (see
\m[blue]\fBdacs_admin()\fR\m[]\&\s-2\u[9]\d\s+2)\&. The activity tracking information is returned only if detail is requested\&.
.RE
.SH "EXAMPLE"
.PP
After
\m[blue]\fBauthenticating\fR\m[]\&\s-2\u[10]\d\s+2
as
DSS::INFOCARDS:bob,
\m[blue]\fBinvoke dacs_current_credentials (HTML)\fR\m[]\&\s-2\u[11]\d\s+2
to view the identity (or identities) stored as a cookie in your browser\&. Information about the credentials can also be
\m[blue]\fBreturned as XML\fR\m[]\&\s-2\u[12]\d\s+2\&.
.SH "FILES"
.PP
\m[blue]\fBdacs_current_credentials\&.css\fR\m[]\&\s-2\u[4]\d\s+2
.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[13]\d\s+2,
\m[blue]\fBdacs_signout(8)\fR\m[]\&\s-2\u[7]\d\s+2
.SH "AUTHOR"
.PP
Distributed Systems Software (\m[blue]\fBwww\&.dss\&.ca\fR\m[]\&\s-2\u[14]\d\s+2)
.SH "COPYING"
.PP
Copyright \(co 2003\-2015 Distributed Systems Software\&. See the
\m[blue]\fBLICENSE\fR\m[]\&\s-2\u[15]\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
user activity
.RS 4
\%http://dacs.dss.ca/man/dacs.1.html#tracking_user_activity
.RE
.IP " 3." 4
\fIFORMAT\fR argument
.RS 4
\%http://dacs.dss.ca/man/dacs.services.8.html#FORMAT
.RE
.IP " 4." 4
dacs_current_credentials.css
.RS 4
\%http://dacs.dss.ca/man//css/dacs_current_credentials.css
.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
RFC 7159
.RS 4
\%https://tools.ietf.org/html/rfc7159
.RE
.IP " 7." 4
dacs_signout(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_signout.8.html
.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
dacs_admin()
.RS 4
\%http://dacs.dss.ca/man/dacs.exprs.5.html#dacs_admin
.RE
.IP "10." 4
authenticating
.RS 4
\%https://dacs.dss.ca/cgi-bin/dacs/dacs_authenticate?USERNAME=bob&PASSWORD=foozle&DACS_JURISDICTION=INFOCARDS&AUXILIARY=&DACS_BROWSER=1&COOKIE_SYNTAX=COOKIE_NETSCAPE
.RE
.IP "11." 4
invoke dacs_current_credentials (HTML)
.RS 4
\%https://dacs.dss.ca/cgi-bin/dacs/dacs_current_credentials?FORMAT=HTML
.RE
.IP "12." 4
returned as XML
.RS 4
\%https://dacs.dss.ca/cgi-bin/dacs/dacs_current_credentials?FORMAT=XML&DETAIL=yes
.RE
.IP "13." 4
dacs_authenticate(8)
.RS 4
\%http://dacs.dss.ca/man/dacs_authenticate.8.html
.RE
.IP "14." 4
www.dss.ca
.RS 4
\%http://www.dss.ca
.RE
.IP "15." 4
LICENSE
.RS 4
\%http://dacs.dss.ca/man/../misc/LICENSE
.RE