SPLoggingConfig

Logging

Shibboleth logging information is generated by the Apache components and shibd. The configuration for both is located in Log4J configuration files pointed to by Shibboleth broad-level information (shibboleth.logger), information from the web environment (native.logger), and information resulting from attribute queries (shibd.logger). These files are all pointed to by elements of shibboleth.xml and located by default at /opt/shibboleth/etc/shibboleth/ .

Each logging configuration file contains a set of properties that defines the behavior of the logging mechanism. Most important for most deployments is the level of detail the logs will record, ranging from the most detailed DEBUG down through INFO, WARN, ERROR, and OFF. This is specified in the various category properties in these configuration files.

Error Handling

Shibboleth supports the dynamic generation of information in error pages referenced by the Errors element in shibboleth.xml. The SP implementation employs a simple template language to insert special tags into the generated HTML. The parser will read the error template looking for any tag that looks like:

<shibmlp tag-name>

Shibboleth will replace tag-name with the appropriate markup tag either from the table below or by looking for a matching XML attribute in the Errors element:

`requestURL`	The URL associated with the request.
`errorType`	The type of error.
`errorText`	The actual error message.
`errorDesc`	A textual description of the error intended for human consumption.
`originContactName`	The contact name for the !IdP provided by that site's metadata.
`originContactEmail`	The contact email address for the !IdP provided by that site's metadata.
`originErrorURL`	The URL of an error handling page for the !IdP provided by that site's metadata.

To improve the appearance of error messages, a simple, limited form of conditional checking is supported so that the presence of absence of data to substitute into a particular tag-name can trigger the inclusion or exclusion of markup. Conditionals look like:

<shibmlpif tag-name> arbitrary markup </shibmlpif>
<shibmlpifnot tag-name> arbitrary markup </shibmlpifnot>

Respectively, these special tags include or skip the markup between the tags if the specified tag-name has an associated value available to be substituted for it. These conditionals cannot be nested: a shibmlpif tag cannot appear inside another shibmlpif tag, due to the simplicity of the substitution engine.

Sample error templates for different kinds of errors are included in the Shibboleth distribution, and can be triggered by anything that will cause Shibboleth to be unable to accept an incoming session, obtain attributes, make an authorization decision, etc., including bad configuration settings, signature verification or certificate validation failures, or a skewed clock between sites.

You should edit these templates, provide or remove style sheets and images, and otherwise customize these templates to suit the (good) user experience you want your users to have when errors occur. The defaults are not likely to meet the needs of any site.