Error Handling

Federation software in most cases comes equipped with a default error handling experience that is limited in scope:

• The look and feel of error pages may be generic and lack visual coherency with the site's "standard" page design.

• Error messages may be overly technical and lack context, or fail to direct users toward appropriate resolution strategies.

• Appropriate contact information may be missing.

In short, out of the box error handling is functional and helpful for debugging, but is typically lacking in providing a professional and appropriate experience for users of an IdP or SP.

Before moving to a production state, deployers should take steps to address these deficiencies. Obvious steps include:

• Apply your site's overall "look and feel", including style sheets, logos, color scheme, etc.

• Direct users towards appropriate points of contact to report problems, along with instructions for doing so. Note that these will rarely be the same as Contacts in Metadata, with the exception of attribute release issues. SPs should take care to "own" their services. Federation is not an excuse to offload application support to partners; your service will never be well-supported by help desk staff who know nothing about its features, requirements, or diagnostic aids.

• Use relative links to embedded content; make sure all access paths into error pages produce appropriate results without broken image icons or missing style sheets.

A less obvious, but important, step is to explore different error conditions in your federating software and/or application; consider what problems are likely to recur in production and how users ought to be advised to proceed. For example, consider how bookmarks of various kinds, or the use of the back button, influences the user experience. Turn those otherwise useless messages into a straightforward warning about these features.

The hand-off between SPs and IdPs within a federation can result in user confusion when errors occur. See Federated Error Handling for ways to address this.

Finally, translate overly technical messages into customized responses in plain language that lead users to solutions; most software will provide the capability to do this. Even if error message testing breaks after upgrades, a deployment is no worse off for having improved the experience in the meantime.