Purpose:
This document describes the federation's generic error page for use with the errorURL parameter in SAML metadata. It offers a fallback mechanism for failed logins and helps SPs and IdPs troubleshoot authentication and authorization issues.

Note: This implementation is meant as a reference or backup. Identity Providers are encouraged to implement their own branded error page to provide clearer, institution-specific guidance to users.

Table of Contents

Overview

The error page:

  • Shows localized error messages (Swedish by default, English toggle)

  • Accepts context parameters from SPs to provide technical detail

  • Presents users with understandable instructions

  • Offers an expandable technical diagnostics section

  • Complies with the REFEDS ErrorURL v1 specification


Sending personally identifiable information in the parameters is not allowed.


Implementations

The generic errorURL handler is available for Skolfederation production and test environments. Find the federation specific errorURL implementations below.

FederationerrorURL (for including in IdPSSODescriptor errorURL attribute)
Skolfederation production environmenthttps://fed.skolfederation.se/prod/error/error.html?code=ERRORURL_CODE&ts=ERRORURL_TS&rp=ERRORURL_RP&tid=ERRORURL_TID&ctx=ERRORURL_CTX
Skolfederation test environmenthttps://fed.skolfederation.se/trial/error/error.html?code=ERRORURL_CODE&ts=ERRORURL_TS&rp=ERRORURL_RP&tid=ERRORURL_TID&ctx=ERRORURL_CTX

URL Format

https://<federation-operator>/error.html?code=...&ts=...&ctx=...&rp=...

All parameters should be URL-encoded.

ParameterRequiredDescription
codeYesError code (see below)
tsOptionalUnix epoch timestamp
ctxOptionalContext-specific message for diagnostics
rpOptionalSP entityID (displayed in diagnostics)
tid OptionalTransaction or session identifiers

Language and Localization

  • The interface defaults to Swedish

  • A button allows toggling to English

  • Parameter content (e.g. ctx) is shown verbatim

Error Codes

CodeDescriptionExample Cause
IDENTIFICATION_FAILURERequired user attributes are missingMissing mail or givenName
AUTHENTICATION_FAILUREAuthentication strength did not meet SP's requirementsMissing 2FA
AUTHORIZATION_FAILUREUser is not authorized to access the serviceMissing role or affiliation
OTHER_ERROROther technical or session-related errorTimeout or metadata issues
UNKNOWNCode was missing or invalidFallback scenario

ctx Parameter (Contextual Information)

According to section 2.3.4 of the REFEDS specification:

  • IDENTIFICATION_FAILURE: List of missing attributes or entity category URIs

  • AUTHENTICATION_FAILURE: List of required authentication context/classref values

  • AUTHORIZATION_FAILURE: Short policy description of why access was denied

  • OTHER_ERROR: Brief technical description useful for troubleshooting

This value is shown beneath the main message when present.

Expandable Technical Diagnostics

An expandable section shows:

  • All received URL parameters

  • If ts is present:

    • Raw epoch format (e.g. 1717580800)

    • ISO 8601 UTC timestamp (e.g. 2024-06-05T08:26:40.000Z)

  • Copy-to-clipboard support

This section is meant for IT support or helpdesk use.

SP Implementation Guidelines

When an error occurs, the SP SHOULD present its own error page to the user. If the specific error condition falls into one of the categories for which this profile is appropriate, the SP MAY process the IdPs errorURL value from its metadata, as described above, and provide a link to the decorated URL.
  • Always provide a meaningful error page at your service provider implementation first hand.

  • Always supply mandatory code parameter. All other parameters are optional, but strongly recommended when applicable.

  • Replace the placeholders in the errorURL parameters (ERRORURL_CODE, ERRORURL_TS, and so on) with actual values.

  • Sending user-identifying data in any parameters is not allowed.

  • Provide fallback helpdesk contact or guidance to users

IdP Implementation Guidelines

Include the corresponding federation value for errorURL in the IDPSSODescriptor to make the generic errorURL available for usage by Service Providers.

Metadata example: Skolfederation production environment

<IDPSSODescriptor ... errorURL="https://fed.skolfederation.se/prod/error/error.html?code=ERRORURL_CODE&amp;ts=ERRORURL_TS&amp;rp=ERRORURL_RP&amp;tid=ERRORURL_TID&amp;ctx=ERRORURL_CTX">

  • Use this page as a fallback only (e.g. while setting up or if a local errorURL cannot be set up for some reason)

  • Monitor and log the ctx, rp, and ts parameters for issue resolution

Example

https://fed.skolfederation.se/prod/error/error.html?code=IDENTIFICATION_FAILURE&ts=1717580800&ctx=eduPersonPrincipalName&rp=https%3A%2F%2Fsp.example.se


Output:

  • Main message: "Required attributes to identify or personalize your session are missing."

  • Context: "Missing attributes: eduPersonPrincipalName"

  • Technical section:

code = IDENTIFICATION_FAILURE
ts = 1717580800 (2024-06-05T08:26:40.000Z)
ctx = eduPersonPrincipalName
rp = https://sp.example.se



  • No labels
Write a comment…