...
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.
| Table of Contents |
|---|
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.
| Note |
|---|
Please be aware that in pre-3.2.1 versions or with the |
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.
...
Assume the SP is configured with the following <Errors> element.
shibboleth2.xml
| Code Block | ||||
|---|---|---|---|---|
| ||||
...
<Errors supportContact="help@example.org"
redirectErrors="http://example.org/error" />
... |
...
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 |
|---|---|---|---|
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 |
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.