Shib Troubleshooting Guide

This guide assumes that you have a Shibboleth Identity Provider which has worked in the past, and a support problem with access to one of the resources protected by one of the SPs with which you have a trust relationship has come up.

Diagnosing where a Shibboleth access error comes from

This is basically a question of eliminating possibilities by checking access to other resources. Note that when testing access, it is important to create a new Shibboleth session each time. This can be done by closing and restarting the web browser being used for testing, or by removing all cookies which come from the Service Provider and the Identity Provider.

Errors and how to fix them

Once the error can be reproduced, it is possible to work on its cause. The principal diagnostic tool is the Shibboleth logfile, which can be found at the location listed in the idp.xml configuration file in the Logging section. In many cases it is useful to be able to find out the corresponding errors from the SP end of the transaction, and other information (such as the httpd log files) may well also be helpful. The default configuration is to have two logs, the transaction and error logs, and the reporting level in each log file collection can be set in this configuration file (in particular, it may be useful to change the level of the error file from WARN to DEBUG in order to obtain more information - but it is then important to change it back to WARN later).

Log files are rotated daily, with ten days' worth being kept. The transaction log entries have the simple format "date time message", but are generally not very informative. The error log, on the other hand, contains useful information about unsuccessful access attempts; here each line has the format "date time level [shib-component] transactionID - message". A successful access looks like this:

2005-10-13 11:30:42,583 Authentication assertion issued to provider (https://lse .ac.uk/shibboleth/target/1) on behalf of principal (mcleish). Name Identifier: (_e4b1bd8519dea297403bcc919f70974d). Name Identifier Format: (urn:mace:shibboleth :1.0:nameIdentifier).
2005-10-13 11:30:43,695 Attribute assertion issued to provider (https://lse.ac.u k/shibboleth/target/1) on behalf of principal (mcleish).

In this transaction, the first four lines show the Shibboleth session being established, with the SP the user hopes to access being checked against the metadata as one which is trusted. The remaining lines show the processing of the attribute request from the SP, which shows which attributes have been obtained from the directory and how many are then released to the SP. Note the phrase "on behalf of principal (mcleish).": this identifies the individual who is accessing the SP and can be used for audit trail purposes if this is needed.

The corresponding web server access log entries (subsidiary requests for images and CSS files omitted) are as follows.

81.104.210.102 - - [14/Oct/2005:14:54:53 +0100] "GET /shibboleth-idp/SSO?target=cookie&shire=https%3A%2F%2Fgabriel.lse.ac.uk%2FShibboleth.sso%2FSAML%2FPOST&providerId=https%3A%2F%2Flse.ac.uk%2Fshibboleth%2Ftarget%2F1&time=1129298092 HTTP/1.1" 401 401
81.104.210.102 - mcleish [14/Oct/2005:14:54:54 +0100] "GET /shibboleth-idp/SSO?target=cookie&shire=https%3A%2F%2Fgabriel.lse.ac.uk%2FShibboleth.sso%2FSAML%2FPOST&providerId=https%3A%2F%2Flse.ac.uk%2Fshibboleth%2Ftarget%2F1&time=1129298092 HTTP/1.1" 200 10843
158.143.192.141 - - [14/Oct/2005:14:54:56 +0100] "POST /shibboleth-idp/AA HTTP/1.1" 200 2510

Note that some or all of these entries may not appear in the main httpd logs, depending on the web server configuration. Although it may look as though these httpd log entries are not very informative, there are times when errors only appear here (because the request never get passed through to the Shibboleth installation); in particular, errors in validating the certificate presented by the SP on accessing the AA or where the authentication module is unable to access the LDAP server to authenticate a user.

Errors encountered in operation and their solutions

This is a list of errors encountered once the installation phase is over, and how they have been solved.

Errors encountered in operation and their solutions

Error	Cause	Solution
SPs accessible but no attributes passed (this may mean that some SPs lock users out); HTTP log reports that SP certificates used to access AA cannot be verified	Updates to mod_ssl have changed permission on directory holding the CA certificates used so that they are no longer accessible	Make directory readable again; more permanently, ensure that the permissions of the directory are correctly set whenever a mod_ssl update is made
Resources protected by single SP inaccessible	Metadata update failed and SP medadata changed	Update metadata (see ShibMetadata )
LexisNexis? continues to be inaccessible even trying classic Athens rather than the gateway	Shibboleth error message from gateway continues to be seen	Athens gateway sets cookie which specifies that user is accessing Athens protected systems using DA; this then prevents acessing resources using classic Athens until the cookie is cleared (by closing the browser and ending the session)

Making configuration changes

Most of the changes that an administrator may need to make will be described in the installation instructions . However, there are some which may need a little further explanation, at least for testing the changes.

If a configuration file has been edited and left containing illegal XML, this will result in the error message "Service IDP is inaccessible" with little other information. There will be log entries in the HTTP logs, but there may not be any in Shibboleth's own logs or the Tomcat logs. This can be fixed by fixing the XML, though this can be hard to do and it may be easier to revert to the old versions of the configuration files (there is apparently no way to identify the file at fault) and redo the editing.

Changing the login box text

The box that appears on login contains text that can be configured, and other text which is an artifact of the web browser used to access the system, so care needs to be taken about what text is configured. Here are some of the common browsers and how the configured text "Simple" is displayed when accessing the URL http://testserver . In each case, this is followed by boxes for username (or user name) and password.

Changing the login box text

Browser	Text displayed
Firefox	Enter username and password for ‘Simple' at http://testserver
Internet Explorer	Simple
Opera	Server http://testserver Message Simple

Configuration is carried out by changing the information in the relevant httpd configuration file, the one which describes the directory's access protection (which may be a .htaccess file in the directory itself). The text itself is contained in the AuthName directive. Changes in the main configuration files may require httpd restarting to register. To test changes, access any resource that uses the Identity Provider for authorisation, and you should see the new text appear in the login box.

Local contacts for infrastructure dependencies

See LseDependencies .

Simon McLeish - 14 October 2005