Errors

The <Errors> element is used to configure error-handling behavior when problems occur during the processing of SSO or logout messages, internal session management, or attribute processing.

If an error is encountered by the SP when in control of the response to the user's browser, there are two general kinds of error handling directly supported within the software.

1 Template Generation
- 1.1 Internal Parameters
2 Redirection
- 2.1 Example
  - 2.1.1 shibboleth2.xml
3 Additional Thoughts
4 Configuration Reference
- 4.1 Attributes
- 4.2 Extension Attributes

Template Generation

With template generation, the default option, an error page is returned by Shibboleth to the browser. These error pages are created using HTML templates (generally located in the Shibboleth configuration directory) and populated dynamically with specific information about the error that occurred. The <Errors> element can override the filenames of these templates and supplies some other pieces of information useful in generating the responses.

The generation process uses a simple template language implemented inside the software, based on a small set of supported tags:

<shibmlp tagname />
- Substitutes the value of the parameter named tagname. Parameters can come from XML attributes inside the <Errors> element, data attached to the exception that occured, the request's query string, and a few well-defined parameters.

<shibmlpif tagname> ... </shibmlpif>
- Outputs the enclosed content if and only if the parameter named tagname exists.

<shibmlpifnot tagname> ... </shibmlpifnot>
- Outputs the enclosed content if and only if the parameter named tagname does not exist.

Please be aware that in pre-3.2.1 versions or with the externalParameters setting enabled, tags can be populated using information supplied by the browser. While the information is HTML encoded in the template, please be wary of making yourself vulnerable to XSS attacks or simple phishing attempts.

Internal Parameters

Tags which may be available for use by templates include:

requestURL	The URL associated with the request.
errorType	The general type of error.
errorText	The actual error message.
entityID	Name of identity provider, if known.
now	Current date and time.
statusCode	SAML status code causing error, sent by identity provider.
statusCode2	SAML sub-status code causing error, sent by identity provider.
statusMessage	SAML status message, sent by identity provider.
RelayState	Original URL the user was attempting to access or value of target parameter passed to SessionInitiator.
contactName	A support contact name for the IdP provided by that site's metadata.
contactEmail	A contact email address for the IdP contact provided by that site's metadata.
errorURL	The URL of an error handling page for the IdP provided by that site's metadata.
eventType	A constant identifying the type of activity connected with the error (e.g. Login, Logout)

Redirection

With redirection, the error is handled by redirecting the browser to a designated location with a query string containing information about the error that occurred. It is the responsibilty of that location to do something useful with that information. In some cases, this might even mean hiding the problem.

The redirection query string will typically include parameters similar to the information listed above.

Redirection can be used for most runtime errors the SP deals with, but it does not support the access control denial condition. That's only handled either by a 403 status or a template, depending on the access property.

Example

Assume the SP is configured with the following <Errors> element.

shibboleth2.xml

...
    <Errors supportContact="help@example.org"
            redirectErrors="http://example.org/error" />
...

Upon a Shibboleth error, the user's browser would be redirected to the following URL. (Note that line breaks have been added for readability.)

http://example.org/error?now=Tue Jan 31 11:32:41 2012
    &requestURL=https://example.org/Shibboleth.sso/SAML2/POST
    &errorType=opensaml::FatalProfileException
    &errorText=SAML response contained an error.
    &RelayState=https://example.org/secure/getattrs
    &entityID=urn:mace:incommon:idp.protectnetwork.org
    &statusCode=urn:oasis:names:tc:SAML:2.0:status:Responder
    &statusCode2=urn:oasis:names:tc:SAML:2.0:status:AuthnFailed

Additional Thoughts

In addition to the handling of errors in the course of SAML processing, SP deployments are often expected to delegate a certain amount of error handling to applications, particularly detection of missing or unacceptable user/attribute information or violations of local policy based on the information received.

Traditional SSO systems often guarantee to applications that a user identity (e.g., REMOTE_USER) will be available, and often provide nothing else of significance. In contrast, the SP guarantees nothing except for a few built-in generic pieces of information about the source of authentication. Neither user identity, nor any of the additional attributes that might be supported, can be assumed present.

Applications relying on "active" protection that cannot deal with variability should be protected by authorization policy (see AccessControl), coupled with a customized web server 403 response page, or an explicit access error template) to explain to the user that their IdP failed to supply the necessary information. Often this is a privacy issue (a failure to release the information to the SP) and not a security failure, so simply denying access outright with no explanation is usually undesirable.

Often it's best if applications can do this checking themselves, because the experience can be more friendly and integrated with the rest of the application.

When "lazy" or "passive" protection is used, often the case with packaged applications, the access control features of the SP are usually insufficient. In such case, for the time being, you may want to consider interposing a custom script between the user's return to the SP and the intended "target" resource. This script could check for the required information and react appropriately, rather than forwarding control to an application that doesn't have the necessary support for signaling what happened to the user.

As an example, consider an integration strategy in which the application initiates SSO upon access to a particular URL by redirecting the client to:

/Shibboleth.sso/Login?target=https%3a%2f%2fsp.example.org%2fapp%2fresource.jsp

Instead, this could be turned into:

/Shibboleth.sso/Login?target=%2fcgi-bin%2fvalidate.cgi%3freturn%3dhttps%3a%2f%2fsp.example.org%2fapp%2fresource.jsp

In this example, the target has been rerouted to a parameter passed to a new CGI script, in this case /cgi-bin/validate.cgi. This script can check the user's session for required information, and either return an error or forward the user on to the original URL. (A script like this should validate that the URL to forward to is "safe" to avoid XSS threats and other problems.) An example of such a script is attached.

To make this work safely in the face of complex URLs, another script may be needed to sit between the application and the SP session initiator to doubly-encode the target resource into the "return" parameter to the validation script. An example is also attached.

Configuration Reference

The filenames of the error templates to use are defaulted based on the kind of error, but can be overridden using the <Errors> element as follows.

Attributes

Name	Type	Default	Description

Name	Type	Default	Description
redirectErrors	Basolure or relative URL		Controls the type of error handling used (see above). If set, the URL is used as the destination for a redirection of the browser with a query string containing information about the error.
session	local pathname	sessionError.html	Path to a template to use for general processing errors.
metadata	local pathname	metadataError.html	Path to a template to use for metadata-related errors.
access	local pathname		Path to a template to use for authorization failures. When omitted, a generic 403 status will be returned when possible, which can be customized by the web server in the normal manner.
ssl	local pathname	sslError.html	Path to a template to use for blocking non-SSL requests that cannot be redirected, if the `redirectToSSL` property is supplied as a content setting.
localLogout	local pathname	localLogout.html	Path to a template to use when completing a local logout operation and no other "return" location is known.
partialLogout	local pathname	partialLogout.html	Path to a template to use when a non-local logout attempt finishes with an incomplete or erroneous status. Note that most IdPs will never display this to the user so relying on it for anything now is generally a waste of time.
globalLogout	local pathname	globalLogout.html	Path to a template to use when completing a global logout operation and no other "return" location is known. Global logout implies identity provider involvement using a single logout protocol. Note that most IdPs will never display this to the user so relying on it for anything now is generally a waste of time.
externalParameters ^3.2.1	Boolean	false	Flag introduced to block the processing of query string parameters for replacement/override of template replacement values. Enabling this is not advised but restores this ability.

Extension Attributes

Any attribute not listed above will be loaded and used as a parameter during template generation.

Service Provider 3