RealMe SAML exception handling

For most of the common problems encountered in the RealMe® services, the web application handles the alternative process flow – for example, forgotten password or password expiry. For exceptions that cannot be handled by a process within the RealMe service, the user is redirected back to the agency with a SAML v2.0 status code. Use of the Messaging Test Site (MTS) is required to generate the SAML exception codes.

An agency's online service must interpret the SAML exception codes and display an appropriately worded message to the user.

Agencies can choose the method of presenting RealMe related messages and the wording style. The exception must be labelled with 'RealMe', but 'alert' or 'message' may be more appropriate than 'error', as the user may not have done anything incorrect. The message must not be a dead end and the user should be able to navigate to an appropriate online service web page and be provided with an opportunity to attempt to login again.

The RealMe implementation team will expect to see a demonstration of the online service handling of SAML exceptions, or at least screen shots from the pre-production environment.

Developers may utilise the content of StatusMessage, but it is recommended that programming flow is based on StatusCode in case the content of StatusMessage is changed.

List of RealMe SAML exceptions

Login exception messages

AuthnFailed

urn:oasis:names:tc:SAML:2.0:status:AuthnFailed

Triggered by user - selection of the Return to agency link or choosing to Cancel from a flow or automated session timeout after 15 minutes of user inactivity on any login service page.
Display a user exit message or optionally return the user to the agency login start page without a message.
Recommended text (if displayed), is You have chosen to leave RealMe, without help desk details.

UnknownPrincipal

urn:oasis:names:tc:SAML:2.0:status:UnknownPrincipal

Only applies when the agency has a separate flow for the returning user, using SAML AllowCreate FALSE.
Triggered by user - incorrect selection of the registered customer flow by a first time user.
Always display an explanatory message describing the correct process.
An agency needs to supply specific customised message text for the specific online service registration process.

Technical errors

urn:oasis:names:tc:SAML:2.0:status:RequestDenied
urn:oasis:names:tc:SAML:2.0:status:Requestor
urn:oasis:names:tc:SAML:2.0:status:Responder

Applies to the listed exception codes or any other saml-core-2.0-os standard errors that might be passed.
Triggered by system - misconfiguration by the agency or application failure at RealMe.
Always display an exception message message.
Recommended text is RealMe reported a serious application error with the message [SAML StatusCode value]. Please try again later. If the problem persists, please contact RealMe Help Desk on 0800 664 774.

Assertion exception messages

AuthnFailed

urn:oasis:names:tc:SAML:2.0:status:AuthnFailed

Triggered by user - selection of the Return to agency link or choosing to Cancel from a flow, or automated session timeout after 15 minutes of user inactivity on any login service page. For assertion, AuthnFailed is also returned when identity or other attributes cannot be released - the user did not consent to sharing, verification is incomplete, or the status is not active such as expired or cancelled.
Display a user exit message and return the user to the start to allow retry or optionally redirect to an alternative flow.
Recommended text (if displayed), is You have chosen to leave RealMe, without help desk details.

UnknownPrincipal

urn:oasis:names:tc:SAML:2.0:status:UnknownPrincipal

Triggered by user - the user's login has never been used with a RealMe verified account.
Always display an explanatory message describing the correct process.
An agency needs to supply a customised message text for this condition - typically the user will be directed to a manual process if online proof cannot be provided.
Presentation of the message should reflect the organisation's prioritisation of online verification via RealMe, the alternative non-online option, and encouraging a prerequisite verified identity application.

Technical errors

urn:oasis:names:tc:SAML:2.0:status:RequestDenied
urn:oasis:names:tc:SAML:2.0:status:Requestor
urn:oasis:names:tc:SAML:2.0:status:Responder

Applies to the listed exception codes or any other saml-core-2.0-os standard errors that might be passed.
Triggered by system - misconfiguration by the agency or application failure at RealMe.
Always display an exception message message.
Recommended text is RealMe reported a serious application error with the message [SAML StatusCode value]. Please try again later. If the problem persists, please contact RealMe Help Desk on 0800 664 774.