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

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.
  • 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.
Timeout
urn:nzl:govt:ict:stds:authn:deployment:RealMe SAML:2.0:status:Timeout
  • Triggered by user - automated session timeout after 15 minutes of user inactivity on any login service page.
  • Always display a timeout message. Simple example [PNG, 4.3 KB].
  • Recommended text is Your RealMe session has timed out – please try again, 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.
NoAvailableIDP
urn:oasis:names:tc:SAML:2.0:status:NoAvailableIDP
  • Only applies when the agency has a moderate strength login.
  • Triggered by system - there is a problem with a credential provider subsystem (SMS, token, Authenticator).
  • Always display a second factor exception message. Simple example [PNG, 8.1 KB].
  • Recommended text is RealMe reported that the TXT service, Google Authenticator or the RealMe token service is not available. You may try again later. If the problem persists, please contact RealMe Help Desk on 0800 664 774.
InternalError
urn:nzl:govt:ict:stds:authn:deployment:RealMe:SAML:2.0:status:InternalError
  • Triggered by system - an unexpected problem occurred with the RealMe login service web application.
  • Always display an internal error message.
  • Recommended text is RealMe was unable to process your request due to a RealMe internal error. Please try again. If the problem persists, please contact RealMe Help Desk on 0800 664 774.
Technical errors
urn:oasis:names:tc:SAML:2.0:status:RequestDenied
urn:oasis:names:tc:SAML:2.0:status:UnsupportedBinding
urn:oasis:names:tc:SAML:2.0:status:RequestUnsupported
urn:oasis:names:tc:SAML:2.0:status:NoPassive
  • 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.
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. 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.
Timeout
urn:nzl:govt:ict:stds:authn:deployment:RealMe:SAML:2.0:status:Timeout
  • Triggered by user - automated session timeout after 15 minutes of user inactivity on any assertion service or login service page.
  • Always display a timeout message. Simple example [PNG, 3.7 KB].
  • Recommended text is Your RealMe session has timed out – please try again, 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.
NoAvailableIDP
urn:oasis:names:tc:SAML:2.0:status:NoAvailableIDP
  • Triggered by system - there is a problem with a credential provider subsystem (SMS, token, Authenticator), during the moderate strength authentication for the RealMe assertion service.
  • Always display a second factor exception message. Simple example [PNG, 8 KB].
  • Recommended text is RealMe reported that the TXT service, Google Authenticator or the RealMe token service is not available. You may try again later. If the problem persists, please contact RealMe Help Desk on 0800 664 774.
InternalError
urn:nzl:govt:ict:stds:authn:deployment:RealMe:SAML:2.0:status:InternalError
  • Triggered by system - an unexpected problem occurred with the RealMe assertion service web application, the login service or an attribute provider service.
  • Always display an internal error message.
  • Recommended text is RealMe was unable to process your request due to a RealMe internal error. Please try again. If the problem persists, please contact RealMe Help Desk on 0800 664 774.
Technical errors
urn:oasis:names:tc:SAML:2.0:status:RequestDenied
urn:oasis:names:tc:SAML:2.0:status:UnsupportedBinding
urn:oasis:names:tc:SAML:2.0:status:RequestUnsupported
urn:oasis:names:tc:SAML:2.0:status:NoPassive
  • 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.