Error handling
This chapter describes how errors MUST be handled in the network, in order to inform and serve both users and participants sufficiently.
Status codes
For error handling, conformity regarding the interpretation of the status codes as used in the <Response> element is critical. Only the following top-level status codes MAY be used:
urn:oasis:names:tc:SAML:2.0:status:Requester | This status code is used for errors caused by the initiator of the SAML request. For example, because an assurance level is requested which is not supported by the recipient, or because the request message has expired. |
|---|---|
urn:oasis:names:tc:SAML:2.0:status:Responder | This status code is used for errors caused by the recipient of the SAML request. For example, because of technical failure or because the recipient does not support requested (optional) functionality. |
Only the following second-level status codes MAY be used:
urn:oasis:names:tc:SAML:2.0:status:AuthnFailed | This status code is used when an user cannot be authenticated for example because invalid credentials have been provided or the cancel button has been used. |
|---|---|
urn:oasis:names:tc:SAML:2.0:status:RequestUnsupported | This status code is used when a message is correctly formatted by the requester, and understood by the recipient, but that functionality is requested which is not supported by the recipient. |
urn:oasis:names:tc:SAML:2.0:status:UnknownPrincipal | This status code is only used by the BSNk in case a pseudoID is queried but not associated. |
Cancelling
During the process of authenticating and authorizing, a user may cancel the process by clicking on the cancel button. Examples:
A user arrives at a Herkenningsmakelaar (HM), but does not yet have an account
A user has selected the wrong Authenticatiedienst (AD) and wishes to retry the selection
A user does not want to authenticate now, and be returned to the Service provider
If a user cancels, the participant MUST direct the user automatically to the latest sender of a SAML request, accompanying a valid SAML response message including valid SAML status codes (urn:oasis:names:tc:SAML:2.0:status:Responder with urn:oasis:names:tc:SAML:2.0:status:AuthnFailed). A <StatusMessage> element MAY be included, containing for example the value "Authentication cancelled".
If a Herkenningsmakelaar receives a cancellation message (from an Authenticatiedienst or Machtigingenregister (MR)), it MUST ask the user to re-select an Authenticatiedienst or cancel.
If a Dienstverlener (DV) receives a cancellation message (from a Herkenningsmakelaar), it MUST indicate to the user that he is not logged in, and MAY offer the user the option to re-authenticate.
Attributes not supported
A participant can receive a message that matches the Interface specifications, but cannot be processed by the recipient. Examples:
The request contains an attribute that cannot be provided by the participant
A participant receiving such a message
MUST show the user a message indicating what went wrong.
MUST show the user information on how to proceed, see Dialoogbeschrijving.
MAY offer the user the option to cancel, in that case the flow continues as stated in Cancelling
Incorrect message (recoverable)
A participant can receive a message that matches the Interface specifications, but cannot be processed by the recipient. Examples:
The request contains an Level of assurance that cannot be provided by the participant
The request contains an EntityConcernedType that cannot be provided by the participant
The recipient MUST direct the user to initiator of the SAML request, accompanying a valid SAML response message including valid SAML status codes (urn:oasis:names:tc:SAML:2.0:status:Responder with urn:oasis:names:tc:SAML:2.0:status:RequestUnsupported). A <StatusMessage> element MUST be included, containing a description of the problem (for example "Level of assurance not supported").
A participant receiving such a response
MUST show the user a message indicating authentication has failed, including the contents of <StatusMessage>.
MUST show the user information on how to proceed, see Dialoogbeschrijving.
If the participant is a Herkenningsmakelaar, it MUST ask the user to re-select an Authenticatiedienst or cancel.
Incorrect message (non-recoverable)
A participant can receive an invalid formatted message. Examples:
Not a valid SAML message
XML does not match XSD
Alternatively, the message can be valid according to SAML specifications, but it does not match the Interface specifications. Examples:
Unknown issuer
Invalid NotValidOnOrAfter
Invalid signature
The request contains invalid ServiceID, attributes or EntityConcernedTypes
The response contains ServiceID, attributes, EntityConcernedTypes or a Level of assurance that does not match the request
Such messages are the result of either a wrong implementation of a participant, or an attempt to hack the system. The user cannot always be sent back to the requester, because the source of the message is unknown and/or cannot be trusted. If the message is a response, it would not make sense to send the user back to the responder.
A participant that receives a message in this category
MUST investigate the nature of the error.
MUST show the user a message indicating a non-recoverable error has occured.
MUST show the user information on how to proceed, see Dialoogbeschrijving.
MUST return a SAML response message with status codes (urn:oasis:names:tc:SAML:2.0:status:Requester and urn:oasis:names:tc:SAML:2.0:status:RequestUnsupported) or an HTTP error in case a binding is used where a synchronuous response is expected and can be returned, like SOAP.
If the participant is a Herkenningsmakelaar, it MUST ask the user to re-select an Authenticatiedienst or cancel.