Generic ErrorURL Page – Reference Implementation

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.

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

URL Format

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

All parameters should be URL-encoded.

Parameter	Required	Description
`code`	Yes	Error code (see below)
`ts`	Optional	Unix epoch timestamp
`ctx`	Optional	Context-specific message for diagnostics
`rp`	Optional	SP entityID (displayed in diagnostics)
`tid`, `sid`	Optional	Transaction 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

Code	Description	Example Cause
`IDENTIFICATION_FAILURE`	Required user attributes are missing	Missing `mail` or `givenName`
`AUTHENTICATION_FAILURE`	Authentication strength did not meet SP's requirements	Missing 2FA
`AUTHORIZATION_FAILURE`	User is not authorized to access the service	Missing role or affiliation
`OTHER_ERROR`	Other technical or session-related error	Timeout or metadata issues
`UNKNOWN`	Code was missing or invalid	Fallback 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 (e.g., time, loa2)
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

SPs should:

Include the errorURL element in their metadata
Always supply:
- code
- ts (recommended)
- ctx (when meaningful)
Avoid sending user-identifying data in any parameters
Provide fallback helpdesk contact or guidance to users

IdP Implementation Guidelines

IdPs should:

Implement a branded errorURL page and register it in metadata
Use this page as a fallback only (e.g. while setting up or for SPs lacking one)
Monitor and log the ctx, rp, and ts parameters for issue resolution

Example

https://federation.example.org/error.html?code=IDENTIFICATION_FAILURE&ts=1717580800&ctx=mail%20givenName&rp=https%3A%2F%2Fsp.example.se

Output:

Main message: "Required attributes to identify or personalize your session are missing."
Context: "Missing attributes: mail givenName"
Technical section:

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

Page tree