InCommon Federated Error Handling Service

The goal of Federated Error Handling is to provide a better user experience in the case where an IdP provides an SP with insufficient information to make an access control decision.

The InCommon Federation now operates a centralized Federated Error Handling Service that SPs can use to generate simple but effective error pages for the end user. Such a page displays the public error handling URL for a given IdP. Alternatively, the Service will determine the error handling URL and return it to the SP for further processing, so that the SP can roll its own error handler.

The InCommon Error Handling Service is deployed on the same infrastructure that hosts InCommon metadata and the InCommon Discovery Service. All of these services are available 24x7 with manual failover to a redundant hot spare in the event of an outage.

Requesting the Service

The URL prefix to the Error Handling Service is:

https://ds.incommon.org/FEH/sp-error.html...

The full URL includes a query string as follows:

Any given request must contain exactly one of the return or sp_entityID parameters in the query string. The idp_entityID parameter should be included as well, otherwise the result will be completely predictable (and not very useful).

Case 1. If both the return and idp_entityID parameters are included in the query string, the Service will determine the error handling URL (errorURL) of the given IdP and then redirect the client to the given return URL with the errorURL attached. If the IdP has no errorURL in metadata, the client is simply redirected to the return URL without any additional information.

Example 1: https://ds.incommon.org/FEH/sp-error.html?return=http%3A%2F%2Fincommon.org%2F%3Ffoo%3Dbar&idp_entityID=urn%3Amace%3Aincommon%3Aosu.edu

Case 2. If both the sp_entityID and idp_entityID parameters are included in the query string, the Service constructs a simple SP-branded error page from user interface elements in SP metadata. A link to the IdP’s error handling URL is included in the body of the error page and the user is encouraged to visit this IdP page for further information about the error that just occurred.

Example 2: https://ds.incommon.org/FEH/sp-error.html?sp_entityID=https%3A%2F%2Fcilogon.org%2Fshibboleth&idp_entityID=urn%3Amace%3Aincommon%3Aosu.edu

Visit the Federated Error Handling (FEH) Service home page to determine test URLs for arbitrary parameter values.

Service Integration

TBD