...

Vid federerad inloggning med SAML så finns en konstruktion funktion för att möjliggöra för tjänster att hänvisa användare som har fatala brister i sin inloggning hindrande inloggningsproblem tillbaka till hjälpsidor hos användarens inloggningstjänstorganisation. Identitetsutfärdare Organisationer kan lägga in en särskild uppgift om "errorURL" i sin metadata metadatan för sin identitetsutfärdare (IdP) med en länk till organisationens hjälpsidor.

Utökad hantering av errorURL

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.

Från och med 16 mars 2021 måste alla identitetsutfärdare (IdP) registrerade i SWAMID ha en errorURL registrerad i sin IdPs metadata. Det finns två alternativ till errorURL:

• Organisationen som står bakom identitetsutfärdaren skapar en egen errorURL-sida lokalt, SWAMID rekommenderar en dynamisk webbsida motsvarande referensimplementationen enligt beskrivning under Sätta upp eget stöd för errorURL.
• SWAMID lägger in den federationsgemensamma errorURL:en i identitetsutfärdarens metadata, se Använda SWAMIDs federationsgemensamma stöd för errorURL.

Utökad hantering av errorURL

Se Under 2020 så utökades hanteringen av errorURL med ett tillägg som möjliggör för tjänster att hänvisa användare till olika sidor beroende på kategori av fel som uppstått vid inloggning, SAML V2.0 Metadata Deployment Profile for errorURL Version 1.0fö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 identetsutfärdareidentitetsutfä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 så 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.

...

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örutom För att möjliggöra ännu tydligare information till användaren finns förutom ERRORURL_CODE så finns ä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 - ett transaktionsid 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)

...

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

...

Där kan då identitetsutfärdaren beskriva för användaren hur den kan bekräfta sin identitet, exempelvis med besöksadress till en helpdesk eller hänvisning till online-identifiering av användarekonton hos identitetsutfärdaren.

...

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 identitetsutfärdare (IdP)

Sätta upp eget stöd för errorURL

SWAMID har byggt en exempelimplementation referensimplementation av den utökade hanteringen av errorURL. Denna finns implementerad utvecklad i PHP, JSP, .NET Core samt statiska HTML-sidor. Implementationen är fri att använda och modifiera efter identitetsutfärdares egna behov.

Exempelimplementatonen återfinns på https://github.com/SUNET/swamid-errorurl.

En

...

dynamisk sida

En dynamisk sida har möjlighet att avgöra vilken tjänst som efterfrågades och vilken kontext som skickades med. Det möjliggör också att ytterligare information som kan underlätta vid felsökning hos identitetsutfärdaren finns med i en eventuell supportförfrågan till identitetsutfärdaren från användarenVid utelämnande av strängen ERRORURL_CODE i en errorURL så finns ingen sträng att ersätta för tjänster. På så vis hänvisas användare vid alla kategorier av fel till samma sida.

Exempel:

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

...

?errorurl_code=ERRORURL_CODE&errorurl_ts=ERRORURL_TS&errorurl_rp=ERRORURL_RP&errorurl_tid=ERRORURL_TID&errorurl_ctx=ERRORURL_CTX

Fem statiska sidor

Då det finns fyra felkategorier så räcker det med fem statiska webbsidor för att tillhandahålla information för de fyra felkategorierna. Den femte sidan är då en omodifierad errorURL där tjänsten inte bytt ut strängen ERRORURL_CODE mot någon felkategori, och bör innehålla information om alla kategorier av fel eller länkar till respektive felsida.

...

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

En

...

statisk sida

Vid utelämnande av strängen ERRORURL_CODE i en errorURL finns ingen sträng att ersätta för tjänster. På så vis hänvisas användare vid alla kategorier av fel till samma sidaEn dynamisk sida har möjlighet att avgöra vilken tjänst som efterfrågades och vilken kontext som skickades med. Det möjliggör också att ytterligare information som kan underlätta vid felsökning hos identitetsutfärdaren finns med i en eventuell supportförfrågan till identitetsutfärdaren från användaren.

Exempel:

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

En federationscentral tjänst för errorURL

Om en identitetsutfärdare inte har möjlighet till en egen errorURL så kan federationen tillhandahålla en central tjänst som flera identitetsutfärdare kan använda som errorURL. Möjlighet till egen anpassning för identitetsutfärdare blir då mindre.

Implementation av errorURL för tjänster

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 så 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 så 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.

.html

Detta kan vara det enda alternativet för tjänsteleverantörer som inte kan välja namn på webbsidor.

Använda SWAMIDs federationsgemensamma stöd för errorURL

...

Arbete pågår inom SWAMID att se till att samtliga identitetsutfärdare har en definierad errorURL i sin metadata. För att underlätta övergången så finns en central tjänst federationsgemensam errorURL som identitetsutfärdare som inte har någon egen errorURL kan använda.

Informationen i den centrala tjänsten är generell och ingen möjlighet till egen anpassning finns. Det enda som skiljer mellan olika identitetsutfärdares errorURL i den centrala tjänsten är att namn på identitetsutfärdare och e-postadress för supportkontakt som hämtas ur identitetsutfärdarens I den gemensamma errorURL:en finns generell information om olika inloggningsproblem och tänkbara lösningar, samt hänvisning till den e-postadress som finns registrerat som identitetsutfärdarens supportfunktion i dess metadata.

SWAMIDs centrala gemensamma errorURL går att testa på https://error.swamid.se/test/. Där finns även en länk till aktuell errorURL för respektive IdP i SWAMID. IdP:er som inte har någon egen errorURL har där en länk till den centrala gemensamma errorURL:en, anpassad för den specifika identitetstutfärdaren.

...

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 så används en konvension kring ERRORURL_CTX i SWAMID. Tjänster rekommenderas att lägga till dessa kontext 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 centrala federationsgemensamma errorURL-tjänsten :en i SWAMID.