Vid federerad inloggning med SAML finns en funktion för att möjliggöra för tjänster att hänvisa användare som har hindrande inloggningsproblem tillbaka till hjälpsidor hos användarens organisation. Samtliga identitetsutfärdare (IdP) i SWAMID har en "errorURL" i metadatan med information om hur användare ska lösa hindrande inloggningsrelaterade problem. Tidigare har bara en generell webbadress kunnat konfigureras som "errorURL" för en identitetsutfärdare som då behöver täcka alla olika typer av fel. Under 2020 kompletterades detta med en utökning som gör att tjänster kan hänvisa användare till mer specifika informationssidor hos användarens organisation vid olika typer av fel för att bättre kunna hjälpa användaren att lösa hindrande inloggningsproblem.

Utökad hantering av errorURL

Se SAML V2.0 Metadata Deployment Profile for errorURL Version 1.0 för definitionen av den utökade hanteringen av errorURL.

Felen som omfattas av errorURL-hanteringen är endast de fel som användaren förväntas kunna lösa själv eller med hjälp av sin identitetsutfärdare. Det finns fyra olika felkatagorier:

• IDENTIFICATION_FAILURE - Attribut som behövs för att identifiera användaren eller för att kunna personanpassa tjänsten saknas, exempelvis unika identifierare, namn eller e-post
• AUTHENTICATION_FAILURE - Kvalitén på autentiseringen uppfyller inte kraven som tjänsten har, exempelvis krav på tvåfaktorsautentisering
• AUTHORIZATION_FAILURE - Användaren saknar behörigheter i tjänsten, och användaren förväntas kunna åtgärda detta själv eller genom kommunikation med sin identitetsutfärdare, exempelvis för låg tillitsnivå (Assurance Level), saknad association till identitetsutfärdaren (affiliation) eller saknade entitlements (roller i tjänsten som överförs från identitetsutfärdaren vid inloggning)
• OTHER_ERROR - Annat fel som användaren förväntas kunna åtgärda själv eller med hjälp av sin identitetsutfärdare

Vid användning av tillägget till errorURL konstrueras URL:en med ett antal specifika strängar som tjänster kan byta ut till olika värden beroende på fel som uppstår vid inloggning. Den viktigaste av dessa är strängen "ERRORURL_CODE" som byts ut mot "IDENTIFICATION_FAILURE", "AUTHENTICATION_FAILURE" eller någon av de andra felkategorierna.

En errorURL för en identitetsutfärdare skulle exempelvis kunna vara

https://saml-error.example.com/ERRORURL_CODE.html

Vid fel i kategorin IDENTIFICATION_FAILURE skulle då länken som tjänsten ger till användaren bli

https://saml-error.example.com/IDENTIFICATION_FAILURE.html

På denna adress kan identitetsutfärdaren beskriva hur användare som får ett fel av denna kategori bör agera för att lösa just den typen av problem.

För att möjliggöra ännu tydligare information till användaren finns förutom ERRORURL_CODE även dessa strängar som tjänsten kan ge lämpliga värden:

• ERRORURL_TS - tid då felet inträffade (unix time eller sekunder sedan 1970-01-01)

• ERRORURL_RP - entityID för tjänsten

• ERRORURL_TID - en transaktionsidentifierare i tjänsten (för användning i kommunikation i tjänsten om det uppkomna felet, för den specifika användaren)

• ERRORURL_CTX - mer specificerad kontext för felet (t.ex. vilka attribut som saknas, vilken behörighet som saknas eller något annat som underlättar felsökandet för eventuell support hos identitetsutgivutfärdaren)

Dessa ytterligare attribut kan användas i en dynamisk implementation av errorURL för att ytterligare förbättra informationen till användare som får problem vid inloggning i tjänster. En mer dynamisk errorURL för en identitetsutfärdare skulle kunna vara

https://saml-error.example.com/?errorurl_code=ERRORURL_CODE&errorurl_ts=ERRORURL_TS&errorurl_rp=ERRORURL_RP&errorurl_tid=ERRORURL_TID&errorurl_ctx=ERRORURL_CTX

Om exempelvis en tjänst som kräver att användare uppfyller tillitsnivån SWAMID AL2 får en inloggning på tillitsnivå SWAMID AL1 kan tjänsten hänvisa användaren till

https://saml-error.example.com/?errorurl_code=AUTHORIZATION_FAILURE&errorurl_ts=1607969220&errorurl_rp=https://www.student.ladok.se/student-sp&errorurl_tid=error-5fd7a9c448086&errorurl_ctx=http%3A%2F%2Fwww.swamid.se%2Fpolicy%2Fassurance%2Fal2

Där kan då identitetsutfärdaren beskriva för användaren hur denne löser det uppkomna problemet, t.ex. bekräfta sin identitet för att uppnå tillräcklig nivå inkl. detaljerad information om hur användare gör det.

Aktivera stöd för errorURL i en tjänst (SP)

För att tjänster ska kunna utnyttja errorURL:en för användares identitetsutfärdare behöver detta läsas ut ur identitetsutfärdarens metadata. Detta hanteras olika i olika SAML Service Providers.

Läsa ut errorURL via Shibboleth Service Provider

För att läsa ut errorURL för en användares identitetsutfärdare i Shibboleth Service Provider behöver tillägget Metadata Attribute Extraction aktiveras i konfigurationen. Instruktioner finns under rubriken Activate Metadata Attribute Extraction for Identity Provider metadata på 3.3 Configure Shibboleth SP - Check for Identity Assurance or REFEDS SIRTFI.

När detta är gjort finns errorURL:en (i förekommande fall) tillgänglig i HTTP-headern/miljövariabeln Meta-errorURL.

Länka till identitetsutfärdarens errorURL vid fel

Läs noga igenom profilen SAML V2.0 Metadata Deployment Profile for errorURL Version 1.0, där beskrivs i vilka fall som errorURL:en kan användas och hur. Se även beskrivningen under Utökad hantering av errorURL ovan.

Försök beskriva felet så utförligt som möjligt ur tjänstens synvinkel för att hjälpa användaren att åtgärda det.

SWAMID-specifik användning av ERRORURL_CTX

För att ytterligare förbättra möjligheten till relevant information till användare vid olika fel används en konvension kring ERRORURL_CTX i SWAMID. Tjänster rekommenderas att lägga till dessa strängar till eventuell annan ERRORURL_CTX vid respektive fel, och identitetsutfärdare rekommenderas att hantera dessa speciellt:

Dessa komplement är implementerade i exempelimplementationen och i den federationsgemensamma errorURL:en i SWAMID.

Exempel på felsidor vid vanliga inloggningsproblem i en tjänst