DACS_SIGNOUT(8) DACS Web Services and CGI DACS_SIGNOUT(8)

NAME

dacs_signout — DACS signout service

SYNOPSIS

dacs_signout [dacsoptions]

DESCRIPTION

This web service is part of the DACS suite.

The dacs_signout web service is invoked from a web browser to cause one or more sets of DACS credentials for the current federation, 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 dacs_authenticate(8) or any other DACS authentication method. A DACS-enabled portal will typically provide users with a link or web page form to invoke this service.

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).

Should copies of the selected credentials exist outside of the browser, they may still be valid; only the browser's copies are destroyed.

The SIGNOUT_HANDLER 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 FORMAT does not select a variety of XML output or JSON output). If XML output is selected, a document conforming to dacs_current_credentials.dtd is returned. If JSON output is selected, a document conforming to dacs_current_credentials.rnc is returned.

Explicitly signing off using this web service is generally unnecessary because DACS credentials will either become invalid when their lifetime is reached (see AUTH_CREDENTIALS_DEFAULT_LIFETIME_SECS) or will be automatically deleted when the user's browser session terminates (or a session with a trusted servlet ends). A user can also sign off by deleting his browser's DACS cookies. Middleware can simply discard cookies.

As DACS credentials are relative to a particular federation of DACS servers, only those credentials that are associated with the federation of the DACS 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.

OpenID Connect Logout

Important

Since this protocol support is new, changes to configuration, operation, and capabilities should be expected in future releases. Directive descriptions may identify additional limitations. Refer to the local_oidc_authenticate module for general information about OIDC support.

If credentials were obtained through the OpenID Connect Core 1.0 (OIDC) protocol using local_oidc_authenticate, signing off (equivalently: "logging off" or "logging out") is handled differently from other cases. When selected, the flow of control is unique and configuration directives must be placed in the jurisdiction's Auth clause for the local_oidc_authenticate module. That clause must have an id attribute with the value "oidc".

Currently, three OIDC related directives are required by dacs_signout: OIDC_CLIENT_ID, OIDC_END_SESSION_ENDPOINT, and OIDC_POST_LOGOUT_REDIRECT_URI.

Signing out from the DACS federation can be initiated by the OpenID Provider (OP). Signing off from the OP can be initiated by a DACS jurisdiction. OIDC RP-Initiated Logout 1.0 and Front-Channel Logout 1.0 are supported.

In default operation, selection of DACS oidc credentials triggers RP-Initiated Logout: normal DACS credential selection and deletion occur, followed by redirection to the configured OIDC end_session_endpoint specified by the OIDC_END_SESSION_ENDPOINT directive. Under normal circumstances, this redirection causes a Front-Channel Logout at the OP. Any DACS handler directives are ignored.

If both iss and sid parameters are present, however, it is assumed that the current request originates from the OP, and Front-Channel Logout is the default operation instead. This also causes normal DACS credential selection and deletion to occur, but following that the program simply exits.

If one of the following recognized OIDC_LOGOUT CGI parameters is present (case-insensitive), the default behaviour is overridden.

frontchannel

This explicitly selects Front-Channel Logout as described above.

rpinitiated

This explicitly selects RP-Initiated Logout as described above.

oponly

This suppresses DACS credential deletion and initiates logout at the OP using RP-Initiated Logout as described above. Afterward, the user may continue to have DACS credentials.

dacsonly

Only DACS credential selection and deletion is done, including honouring an applicable handler. No OIDC operations are performed. Afterward, the user may continue to be signed on at the OP.

Any unrecognized OIDC_LOGOUT parameter value causes reversion to the default behaviour.

Web Service Arguments

In addition to the standard CGI arguments, dacs_signout understands the following CGI arguments:

DACS_USERNAME

If present, all credentials associated with this username will be deleted. If not provided, the username in the credentials is immaterial.

DACS_JURISDICTION

If present, all credentials associated with this jurisdiction (given as its JURISDICTION_NAME) will be deleted. If not provided, the jurisdiction in the credentials is immaterial.

DACS_SIGNOUT_HANDLER

If permitted by the SIGNOUT_HANDLER directive and HTML output has been selected, redirect the user's 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 DACS. When not explicitly permitted by the SIGNOUT_HANDLER directive, this parameter is ignored.

COOKIE_SYNTAX

This optional parameter is as described for the dacs_authenticate(8) service.

OIDC_LOGOUT

As described above.

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 DACS cookies associated with the federation that receives the service request will be deleted.

The name matching method can be configured through the NAME_COMPARE directive.

Note

DACS 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 user tracking capability, which can record all of a user's requests for DACS-wrapped services within a federation. By simply comparing the current time with the time stamp of the user's last service request, the user's idle time can be determined. If the idle time exceeds a configured maximum, dacs_acs(8) would consider the user's credentials to be invalid (effectively expired) and take appropriate action. A straightforward implementation would be a relatively simple enhancement to DACS; 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.

EXAMPLES

To signout from all identities in the EXAMPLE federation, a user would simply invoke a URL like: 

https://dss.example.com/cgi-bin/dacs/dacs_signout

To signout only from the identity EXAMPLE::FEDROOT:bobo, a URL like the following might be invoked: 

https://fedroot.example.com/cgi-bin/dacs/dacs_signout?\
DACS_USERNAME=bobo&DACS_JURISDICTION=FEDROOT

To signout from only those identities in the EXAMPLE federation having a username component bobo, invoke a URL like: 

https://fedroot.example.com/cgi-bin/dacs/dacs_signout?DACS_USERNAME=bobo

This would signoff from EXAMPLE::FEDROOT:bobo and EXAMPLE::DSS:bobo, for instance.

DIAGNOSTICS

The program exits 0 if everything was fine, 1 if an error occurred.

SEE ALSO

dacs_authenticate(8), dacs_current_credentials(8), dacs_auth_agent(8), dacs_auth_transfer(8), dacs_select_credentials(8), dacsauth(1), dacscred(1)

RP-Initiated Logout 1.0, Front-Channel Logout 1.0.

The DACS distribution includes an example of a "log off" web page: html/examples/signout.html.

BUGS

It might be useful for the non-HTML formats to provide configured or requested signout handler URLs.

Back-Channel Logout is not supported.

AUTHOR

Distributed Systems Software (www.dss.ca)

COPYING

Copyright © 2003-2025 Distributed Systems Software. See the LICENSE file that accompanies the distribution for licensing information.

DACS Version 1.5.0 9-Apr-2025 DACS_SIGNOUT(8)

Table of Contents
Font:
 −− Set ++

$Id: dacs_signout.8.xml 3393 2025-04-08 18:54:34Z brachman $