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.

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

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`^2.6	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 configuration file

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

redirectErrors(absolute URL, relative URL supported in V2.5+)
- 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) (defaults to sessionError.html)
- Path to a template to use for general processing errors.

metadata(local pathname) (defaults to 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.

ssl(local pathname) (defaults to sslError.html)
- Path to a template to use for blocking non-SSL requests that cannot be redirected, if the redirectToSSL property is supplied by the request mapper.

localLogout(local pathname) (defaults to localLogout.html)
- Path to a template to use when completing a local logout operation and no other "return" location is known.
partialLogout(local pathname) (defaults to partialLogout.html)
- Path to a template to use when a non-local logout attempt finishes with an incomplete or erroneous status.

globalLogout(local pathname) (defaults to 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.

Extension Attributes

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