Child pages
  • Error Handling WG Notes - 20 February 2020

Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.



  1. Consideration of the proposal from ACAMP -
  2. Working Document
  3. Review of possible error states
  4. Discussion on what other information may be needed


Consideration of the proposal from ACAMP -

  • Best Practice around Error Handling

    titleFrom ACAMP Notes

    Best Practice around Error Handling

    Service Providers have needs from authentication, could be any number from, for example, the following:

    • A successful authentication
    • Specific attributes (e.g. eppn, email, name, affiliation, entitlements)
    • Minimal assurance (e.g. RAF Medium, SWAMID Identity Assurance 2)
    • MFA authentication (e.g. Refeds MFA, SWAMID Person-Proofed Multi-Factor)
    • Step-up authentication (forceAuthn)

    In case any of this fail during authentication, Service Providers often have nothing they can do about it, except for asking the user to retry the authentication. There needs to be a way for Service Providers to point the user in the right direction if the authentication is not complete, from the perspective of the Service Provider.

    The errorURL is meant to be used for this. The defined expected information that should be presented to the user at the errorURL is however somewhat narrow in regard of this:


    An IdP’s metadata MUST include the errorURL attribute on its <md:IDPSSODescriptor> element. The content of the errorURL attribute MUST be an https URL resolving to an HTML page.

    The errorURL HTML page should be suitable for referral by SPs if they receive insufficient attributes from the IdP to successfully authenticate or authorize the user’s access. The page should provide information targeted at the end user explaining how to contact the operator of the IdP to request addition of the necessary attributes to the assertions.


    If a successful authentication response lacks sufficient or appropriate SAML Attributes (including subject identifiers) for successful SP operation, the SP MUST display a meaningful status message to the user. This message MUST direct the user to appropriate support resources offered by the SP or, alternatively, to the errorURL attribute in an IdP’s metadata.

    There are many reasons an SP may be unable or choose not to provide service to a user based on an given authentication response. IdPs failing to release the necessary SAML Attributes is the most prevalent interoperability issue encountered in larger, general purpose federations, which is why this scenario is singled out here.

    We need a best-practice for the information expected at the errorURL and a way to point users to specific, common, parts of the errorURL.

    • We should not leave errorURL in unless we had more specific language about how to guide people on what to do. The language that’s in there now pre-date what was discussed at ACAMP; it was not really modified based on current level of interest. 

    • One group in the room advocated using a back-channel protocol for error reporting rather than front-channel. What, if anything, would be gained by that? What do we need to know about that possible path forward?

      • It would (probably) be more complicated to do something via back-channel. 

      • You can give a lot more information via a back-channel than via a URL, and that’s a privacy concern

    • The things we could point to in the OIDC protocol as comparison points do not seem appropriate comparisons. Would like to have someone more familiar with OAuth and OIDC to chime in on this. 

    • Can we focus on what the application can figure out as an error state, that the SP or IdP doesn’t actually have to know?

    • What happens if an IdP cannot handle an authN context class, and it just returns that info. Encryption signing errors would be another example. SAML has some ways to handle those errors in the protocol, but it’s not for the end-user. 

      • It’s not a problem if we also include conditions that are captured in the protocol which we have status codes for. Let’s carve out a condition for the AuthN context issue, such that if the IdP sends the error, if the SP wants to point the user back to the IdP with that information, they can. 


titleAdapted from ACAMP notes

Syntax of errorURL

errorURL is added in the IDPSSODescriptor tag:

<md:IDPSSODescriptor errorURL="">

There is only one errorURL per IdP. The ID could be used as a query-string to the errorURL, or more generic, at TAG in the errorURL can be replaced by any of the ID:s in the definitions above. Examples:


I.e. it is up to the IdP to optionally include the TAG in the errorURL. IdP:s are expected to handle unknown (new) TAG values appropriately. TAG includes only [A-Z0-9_].

For example, if a user has logged in to an SP from KAU and the SP is with missing attributes, it should point the user to the url



errorURL [Optional]

Optional URI attribute that specifies a location to direct a user for problem resolution and additional support related to this role.


  • MISSING_ATTRIBUTES (could be a scope issue)