Tjänstespecifikation

1(47) Tjänstespecifikation för Anvisningstjänst som del av Svensk e-legitimation

2(47) INNEHÅLLSFÖRTECKNING 1 INLEDNING... 4 1.1 Tjänsten i sitt sammanhang... 4 1.2 Syfte... 4 1.3 Mål... 4 1.4 Förväntade effekter... 4 1.5 Styrande förutsättningar... 4 1.6 Avgränsningar... 5 2 FUNKTIONELL BESKRIVNING... 6 2.1 Sammanfattning... 6 2.2 Arkitektur och ingående funktioner... 7 2.2.1 Central anvisning... 8 2.2.2 Lokalt integrerad anvisning... 9 2.3 Beskrivning av funktioner... 11 2.3.1 JavaScript för anvisning... 11 2.3.2 Anvisningsfeed... 11 2.3.3 Funktion för hantering av användarstatus... 13 2.3.4 Webbsida med gränssnitt för val av legitimeringstjänst... 14 3 BESKRIVNING AV GRÄNSSNITT... 15 3.1 Tekniska gränssnitt... 15 3.1.1 Standarder och profiler... 15 3.1.2 Gränssnitt för integration med Anvisningstjänsten... 15 3.1.3 JavaScript API... 17 3.2 Grafiska gränssnitt... 19 3.2.1 Gränssnitt vid visning av alla valbara legitimeringstjänster... 19 3.2.2 Gränssnitt med föreslaget förval... 21 3.2.3 Gränssnitt vid Single Sign On... 23 3.2.4 Hantering av tillitsnivåer och kategorier... 24 3.2.5 Informationsspridning... 26 4 FUNKTIONELLA KRAV... 27 4.1 Anvisningstjänstens funktioner... 27 4.1.1 Protokollstöd enligt IdpDisco... 27 4.1.2 JavaScript för anvisning... 27 4.1.3 Anvisningsfeed... 29 4.1.4 Hantering av användarstatus... 29 4.2 Anvisningstjänstens användargränssnitt... 30 5 ICKE FUNKTIONELLA KRAV... 31 5.1 Säkerhets- och tillgänglighetskrav... 31 5.1.1 Verifiering av metadata... 31 5.1.2 Krav på administration och kontroll... 31 5.1.3 Loggar... 31 5.1.4 Administration och konfigurering... 32

3(47) 5.1.5 Krypterad kommunikation... 32 5.1.6 Tillförlitlig tid... 32 5.1.7 Tillgänglighet... 33 5.2 Integrationsdokumentation... 33 6 KRAV PÅ UTVECKLING... 34 6.1 Uppdateringar av funktionalitet och felrättningar... 34 6.1.1 Bakåtkompatibla uppdateringar... 34 6.1.2 Bakåtinkompatibla förändringar... 34 6.2 Framtida metoder för anvisning... 35 6.2.1 Account Chooser... 35 7 INFORMATIONSMODELL... 36 7.1 Legitimeringstjänster (Identity Providers)... 36 7.2 E-tjänster (Service Providers)... 37 8 ANVÄNDNINGSFALL OCH SEKVENSDIAGRAM... 38 8.1 Användare autentiseras mot e-tjänst... 38 8.1.1 Användare avbryter val av legitimeringstjänst... 40 8.2 Anvisningstjänstens roll vid Single Sign On... 41 8.2.1 Generell Single Sign On... 41 8.2.2 Single Sign On med passiv Anvisningstjänst... 43 8.2.3 E-tjänsten kräver autentisering av användaren... 44 8.2.4 Sömlös inloggning mellan e-tjänster... 45 9 REFERENSER... 46 9.1 Normativa referenser... 46

4(47) 1 INLEDNING 1.1 TJÄNSTEN I SITT SAMMANHANG En Anvisningstjänst, eller Discovery Service, har som sitt syfte att avlasta de enskilda e-tjänsterna (Service Providers, SP) inom federationen från att själva implementera stöd för hur användare väljer legitimeringstjänst (Identity Provider, IdP) för autentisering. Genom att en Anvisningstjänst finns tillgänglig inom federationen kan e-tjänster styra sina användare dit för val av legitimeringsmetod (eller legitimeringstjänst). Anvisningstjänsten interagerar med användaren som gör sitt val och användaren, tillsammans med dennes val, styrs tillbaka till e-tjänsten som nu vet till vilken legitimeringstjänst användaren ska skickas för legitimering. 1.2 SYFTE Syftet med Anvisningstjänsten är att tillhandahålla en enkel och robust infrastrukturkomponent för tillhandahållare av e-tjänster och dess slutanvändare för val av legitimeringstjänst vid inloggning mot e-tjänst. 1.3 MÅL Målet med Anvisningstjänsten är att den alltid är tillgänglig och att dess svarstider medverkar till en positiv användarupplevelse. Anvisningstjänsten är enkel att integrera emot för e-tjänster och den kräver lite administration. 1.4 FÖRVÄNTADE EFFEKTER Anvisningstjänsten skapar förutsättningar för att slutanvändaren får ett bättre stöd i valet av e-legitimation i e-tjänster och ger en säker kommunikation över Internet. Vidare bidrar tjänsten till en effektivare utveckling av e-tjänster. 1.5 STYRANDE FÖRUTSÄTTNINGAR Anvisningstjänsten läser från metadatatjänsten och extraherar relevant data. Fastställda format avseende metadata och en samverkan vid förändring krävs. Visuella gränssnitt som exponeras av Anvisningstjänsten för val av legitimeringsmetod skall utformas i samverkan med E-legitimationsnämnden. Centrala begrepp är användbarhet, tillgänglighet och enkelhet. För att underlätta för användare som utför val skall Anvisningstjänsten spara användares tidigare val av legitimeringsmetod genom skrivning av webbläsar-cookies, och därmed kunna erbjuda förenklade valsidor. Anvisningstjänsten skall betjäna användare som ansluter via såväl vanliga webbläsare som mobila enheter.

5(47) Anvisningstjänsten för Svensk e-legitimation är en vital punkt inom federationen då i princip alla e-legitimationsinloggningar som utförs behöver någon form av anvisning. Tjänsten skall dimensioneras och säkras därefter. Anvisningstjänstens arkitektur skall utformas på ett sådant sätt att e-tjänster inom federationen har möjlighet att använda komponenter från Anvisningstjänsten för att lokalt integrera anvisning i e-tjänsten (se 2.2.2, Lokalt integrerad anvisning ). 1.6 AVGRÄNSNINGAR Anvisningstjänsten innefattar inte komponenter och anpassningar som utförs hos e-tjänster för att implementera anvisning. Lokalt integrerad anvisning ingår därför inte i Anvisningstjänsten. Däremot ingår i Anvisningstjänsten att tillhandahålla centrala funktioner och gränssnitt för att möjliggöra lokalt integrerad anvisning. I detta dokument finns informativa avsnitt där lokalt integrerad anvisning hos e-tjänster beskrivs.

6(47) 2 FUNKTIONELL BESKRIVNING 2.1 SAMMANFATTNING Anvisningstjänsten betjänar federationens e-tjänster med ett centralt stöd för hur användare utför val av legitimeringstjänst. Nedanstående sekvensdiagram illustrerar det enkla protokoll som används för att åstadkomma anvisning. Användare (webbläsare) e-tjänst (SP) Anvisningstjänst (DS) Begäran om anvisning genom HTTP redirect till DS Användaren väljer legitimeringstjänst (IdP) Resultat av anvisning returneras till SP genom HTTP redirect Figur 1: Sekvensdiagram som illustrerar hur e-tjänst begär anvisning. Anvisningstjänsten ansvarar för att sammanställa en vy för användaren där alla valbara legitimeringstjänster visas. Denna information läses från federationens metadataregister och filtreras baserat på e-tjänstens krav på legitimering, användarens egenskaper och legitimeringstjänsternas egenskaper. Anvisningstjänsten skall hantera användarnas val över tid med syfte att underlätta valsituationen för användare, d.v.s., en användares tidigare val av legitimeringstjänst skall framhävas så att användaren endast behöver bekräfta sitt tidigare val. Anvisningstjänsten skall också hantera användares val av legitimeringstjänst inom en webbläsarsession för att understödja Single Sign On mellan federationens e-tjänster. Användandet av en central tjänst för anvisning innebär att federationens aktörer använder ett och samma gränssnitt då användare väljer legitimeringstjänst. Syftet är att användare alltid skall förstå att de utför en e-legitimationsinloggning och inte behöva lära sig flera olika sätt att autentisera sig mot offentliga e-tjänster. Det centrala gränssnittet ger också möjlighet att på ett

7(47) centralt ställe sammanställa information rörande användandet av e-legitimationer, något som i dagsläget är spritt hos alla e-tjänster som erbjuder e-legitimationsinloggning. En central tjänst introducerar en punkt i federationen, som om den inte fungerar korrekt påverkar möjligheter till inloggning mot alla e-tjänster som är beroende av anvisning. Det ställer ett antal icke-funktionella krav på Anvisningstjänsten vad gäller tillgänglighet och svarstider för att säkerställa den centrala tjänstens stabilitet inom federationen. Anvisningstjänsten skall konstrueras på ett sådant sätt att e-tjänster kan ärva in information från den centrala tjänsten för att utföra lokalt integrerad anvisning och därmed undvika ett beroende till en central tjänst. Detta beskrivs i kapitlet 2.2.2 nedan. 2.2 ARKITEKTUR OCH INGÅENDE FUNKTIONER Inom federationen för Svensk e-legitimation kan e-tjänster åstadkomma anvisning på två olika sätt: Central anvisning En e-tjänst som använder central anvisning skickar sina användare till Anvisningstjänsten för val av legitimeringstjänst. Då användaren utfört sitt val returneras denna till e-tjänsten för fortsatt hantering av inloggningen. I detta fall används protokollet som beskrivs i [idp-disco]. Lokalt integrerad anvisning Genom integrering av funktioner från Anvisningstjänsten genererar e-tjänsten en lokal sida för anvisning med samma utseende och interna logik för anvisning som den centrala tjänsten. Skillnaden mot den centrala lösningen ligger främst i hur integrationen utförs (JavaScript-anrop istället för HTTP-redirect enligt [idp-disco]). För att kunna åstadkomma stöd för ovanstående metoder skall Anvisningstjänsten delas upp i delkomponenter som levererar funktioner som kan användas för både central och lokalt integrerad anvisning. Dessa funktioner är: JavaScript för anvisning En funktion som används i webbläsaren för att generera ett användargränssnitt för val av legitimeringstjänst. Funktionen har också som sin uppgift att, baserat på e-tjänsters och legitimeringstjänsters egenskaper, filtrera vallistan för användaren. Anvisningsfeed Funktion som läser data från federationens metadata, verifierar denna och gör den tillgänglig för Anvisningstjänstens logik. En eller flera speglingar av denna funktion skall göras tillgängliga för att säkerställa tillgängligheten för anvisning. Central funktion för hantering av användarstatus En central funktion där webbläsare/javascript kan spara och läsa användarstatus till/från användarnas webbläsare genom att styra dessa mot den centrala statusfunktionens domänadress. Användarstatus är användares förvalda och aktuella legitimeringstjänster. Webbsida med gränssnitt för val av legitimeringstjänst Den webbsida som användaren laddar hem till sin webbläsare som innefattar ett användargränssnitt för val

- + Anvisningstjänst för svensk e-legitimation Avbryt Även e-legitimationer från SEB och Skatteverket Hem Ange språk Hjälp Kontakt - + Välkommen till Myndigheten Logga in Leveransavtal 8(47) av legitimeringstjänst. Denna sida tillhör Anvisningstjänsten. E-tjänster som använder lokalt integrerad anvisning ansvarar själva för denna funktion 1. Givet dessa funktioner kan central och lokalt integrerad anvisning illustreras enligt nedan. 2.2.1 Central anvisning + e-tjänst https://anvisning.eid.se Anvisningstjänsten för svensk e-legitimation Ange den e-legitimation du önskar använda för att legitimera dig Myndigheten + BankID Telia e-legitimation Informationssidan Här finns en massa information som inte kräver inloggning. Anvisningsfeed Mobilt BankID Hjälp mig ta reda på vilken e-legitimation jag har... Steria e-legitimation Allmän information där Myndigheten sprider sitt budskap. Logga in till Mina Sidor Kom ihåg mitt val Klicka på knappen för att logga in till mina sidor med din e-legitimation. JavaScript för Anvisning Vad är en e-legitimation? Har du tekniska problem med din e-legitimation? Skaffa en e-legitimation Tjänst för Användarstatus HTTP redirect till Anvisningstjänst enligt IdpDisco-protokollet. Användaren loggar in mot e-tjänsten. Anvisningstjänsten Figur 2: E-tjänst som använder central anvisning. Användare Bilden ovan illustrerar hur Anvisningstjänstens funktioner används för att bygga upp en central anvisning. Användaren loggar in mot e-tjänsten och styrs då till Anvisningstjänsten via en HTTP-redirect enligt protokollet beskrivet i [idp-disco]. I exemplet ovan exponerar Anvisningstjänsten URL:en https://anvisning.eid.se som adress för central anvisning. Anvisningstjänsten bygger upp HTML-sidan som användaren utför sitt val från genom att ladda och anropa funktioner i JavaScript för Anvisning. Detta JavaScript anropar i sin tur Anvisningstjänstens funktioner för Anvisningsfeed för att kunna läsa metadata rörande e- tjänsten och de legitimeringstjänster som skall presenteras, samt funktionen för Användarstatus vilken används för att läsa och uppdatera användarens förvalda (och aktuella) legitimeringstjänst. All logik rörande vilka legitimeringstjänster som skall presenteras i gränssnittet utförs av JavaScript för Anvisning och exekveras sålunda i användarens webbläsare istället för på servern, vilket medför att Anvisningstjänsten kan betjäna anrop snabbare och med mindre processorkraft. 1 Dock är det möjligt för dessa e-tjänster att använda samma stildefinitioner (CSS:er) som används av Anvisningstjänsten.

- + Anvisningstjänst för svensk e-legitimation Avbryt Även e-legitimationer från SEB och Skatteverket Hem Ange språk Hjälp Kontakt - + Välkommen till Myndigheten Logga in Leveransavtal 9(47) 2.2.2 Lokalt integrerad anvisning https://anvisning.eid.se e-tjänst https://www.myndigheten.se/anvisning + https://www.myndigheten.se/loggain Anvisningstjänsten för svensk e-legitimation + Anvisningsfeed Proxy för Anvisningsfeed Ange den e-legitimation du önskar använda för att legitimera dig BankID Telia e-legitimation Myndigheten Informationssidan Här finns en massa information som inte kräver inloggning. Mobilt BankID Steria e-legitimation Allmän information där Myndigheten sprider sitt budskap. JavaScript för Anvisning Cachat JavaScript för Anvisning Hjälp mig ta reda på vilken e-legitimation jag har... Kom ihåg mitt val Vad är en e-legitimation? Skaffa en e-legitimation Har du tekniska problem med din e-legitimation? Logga in till Mina Sidor Klicka på knappen för att logga in till mina sidor med din e-legitimation. Logga in Tjänst för Användarstatus Anvisningstjänsten Styrs till lokalt genererad sida för anvisning. Användaren loggar in mot e-tjänsten. Spegling av Anvisningsfeed Figur 3: Anvisning genom lokal integration hos e-tjänst. Detta avsnitt illustrerar hur Anvisningstjänstens funktioner används för att åstadkomma lokalt integrerad anvisning. Detta är ett informativt avsnitt och omfattar inte krav på Anvisningstjänsten. En hos e-tjänsten lokalt integrerad anvisning innebär att användaren inte styrs till en central tjänst för anvisning utan att e-tjänsten själv ansvarar för att konstruera sidan vari användaren utför sitt val (i exemplet ovan på adressen https://www.myndigheten.se/anvisning). För detta syfte använder e-tjänsten de funktioner som exponeras av Anvisningstjänsten ingen egen logik för anvisning implementeras. För att e-tjänsten skall kunna använda Anvisningstjänstens funktioner krävs följande: Vid lokalt integrerad anvisning använder e-tjänsten Anvisningstjänsten funktioner enligt följande: E-tjänsten konfigurerar en proxy för hämtning av anvisningsdata från Anvisningstjänstens funktion Anvisningsfeed. Data från Anvisningsfeed används av JavaScript för Anvisning då dess logik bygger upp valsidan. För att säkerställa att funktionen JavaScript för Anvisning alltid har tillgång till anvisningsdata kan e-tjänsten välja mellan följande metoder: - Konfigurera JavaScriptet att gå till en spegling av Anvisningstjänstens metadata om dess master inte är tillgänglig. Detta förfarande innebär att en mycket enkel proxy för hämtning av metadata kan användas, t.ex. Apache ProxyPass.

Hem Ange språk Hjälp Kontakt Leveransavtal 10(47) - Implementera en mer avancerad proxy som också har möjlighet att mellanlagra (cacha) nedladdat metadata. I detta fall kan e-tjänstens proxy-funktion leverera metadata även då den centrala funktionen för Anvisningsfeed inte är tillgänglig. E-tjänsten använder sig av samma JavaScript som Anvisningstjänsten det enda som skiljer är dess konfiguration. Detta JavaScript laddas ned periodiskt till e-tjänsten för att undvika ett direkt beroende till Anvisningstjänsten. E-tjänsten använder en egen webbsida som laddar JavaScript för Anvisning och tar hand om resultatet av användarens val. För detta kan e-tjänsten välja att skapa en fristående webbsida inom tjänstens webb och utför integrering genom att inkludera Anvisningstjänstens JavaScript på e-tjänstens sida, t.ex. https://www.myndigheten.se/anvisning. - + Anvisningstjänst för svensk e-legitimation + Anvisningstjänsten för svensk e-legitimation Ange den e-legitimation du önskar använda för att legitimera dig BankID Telia e-legitimation Även e-legitimationer från SEB och Skatteverket Mobilt BankID Steria e-legitimation Hjälp mig ta reda på vilken e-legitimation jag har... Avbryt Kom ihåg mitt val Vad är en e-legitimation? Skaffa en e-legitimation Har du tekniska problem med din e-legitimation? E-tjänsten kan också inkludera anvisning som en del av en av e-tjänstens sidor för att bättre integrera med e-tjänstens inloggningsflöde. - + Välkommen till Myndigheten + Myndigheten Logga in Ange den e-legitimation du önskar använda för att legitimera dig BankID Telia e-legitimation Även e-legitimationer från SEB och Skatteverket Mobilt BankID Steria e-legitimation Hjälp mig ta reda på vilken e-legitimation jag har... Avbryt Kom ihåg mitt val Det enda beroende till Anvisningstjänsten som kvarstår efter att e-tjänsten konstruerat sin miljö enligt ovan är beroendet till den centrala funktionen för hantering av användarstatus. Om denna funktion inte är tillgänglig kan e-tjänsten inte läsa eller uppdatera användarens förvalda legitimeringstjänst, men det innebär inte att användaren inte kan legitimera sig, bara

11(47) att användarens förval inte kan presenteras. Att funktionen för hantering av användarstatus inte kan exekvera lokalt beror på webbläsares krav på Same Origin Policy 2. 2.3 BESKRIVNING AV FUNKTIONER 2.3.1 JavaScript för anvisning Anvisningstjänsten är en central tjänst inom federationen för Svensk e-legitimation och är inblandad i princip samtliga inloggningar som utförs med e-legitimationer till e-tjänster inom federationen. Detta innebär att Anvisningstjänsten skall kunna hantera många samtidiga anrop och dessutom ha korta svarstider. Ett sätt att dramatiskt minska bördan på tjänsten är att låta användarnas webbläsare göra en stor del av arbetet. Därför skall logiken för anvisning utföras av ett JavaScript som exekverar på klienten. En annan fördel med att placera Anvisningstjänstens logik i ett JavaScript är, som redan nämnts, att en sådan uppdelning medger att samma bakomliggande teknik kan användas av både en central tjänst och för lokalt integrerad anvisning hos e-tjänster. Detta JavaScript skall ombesörja följande: Hämta relevant metadata i JSON- eller XML-format från Anvisningsfeed. Hämta relevant information angående användares förvalda (och aktuella) val av legitimeringstjänster från webbläsaren med stöd av den centrala funktionen för hantering av användarstatus, eller med andra ord, läsa användarnas webbläsarcookies 3 för förval och aktuellt val. Utföra selektering (filtrering) av valbara legitimeringstjänster enligt de krav och egenskaper som gäller för e-tjänsten och legitimeringstjänsterna. Skapa grafiskt gränssnitt för val av legitimeringstjänst (generera HTML). Ta emot information om användarens val av legitimeringstjänst. Uppdatera användarstatus rörande utfört val av legitimeringstjänst med stöd av den centrala funktionen för hantering av användarstatus (skriva webbläsarcookies). Tillhandahålla information om användarens valda legitimeringstjänst. Detta JavaScript tillhandahåller alltså såväl grafiskt gränssnitt som funktioner för val av legitimeringstjänst när det infogas och aktiveras inom en webbsida (se 2.3.4, Webbsida med gränssnitt för val av legitimeringstjänst, nedan). 2.3.2 Anvisningsfeed Metadatatjänstens funktion för publicering [spec-metadata] är källan till metadata för Anvisningstjänsten. Funktionen för Anvisningsfeed utför följande steg: 2 Same Origin Policy är en säkerhetspolicy som begränsar en webbläsare till att endast hämta data från samma domän som den webbsida, som hämtar information, själv hämtades från. En webbsida från example.com kan endast hämta data från example.com. 3 För webbläsare som stödjer funktionen Web Storage skall denna metod användas i stället för webbläsarcookies.

12(47) Läser metadata från metadatatjänstens funktion för publicering. Säkerställer metadatans autenticitet genom att verifiera dess signatur. Extraherar relevant data för anvisningstjänstens logik (se kapitel 7,

13(47) Informationsmodell ). Sammanställer dessa data i ett väldefinierat format och gör den tillgänglig för konsumering (av JavaScript för anvisning ). Ovanstående steg utförs periodiskt för att garantera att funktionen exponerar aktuell metadata för anvisning. De data som levereras från funktionen Anvisningsfeed läses endast av JavaScriptet som hanterar anvisningslogiken, vilket innebär att dess format inte behöver definieras och dokumenteras för extern konsumtion. Formatet skall vara anpassat så att det lämpar sig för HTTP cachning hos e-tjänster som integrerar anvisning lokalt (se 2.2.2, Lokalt integrerad anvisning ). Funktionen för Anvisningsfeed skall speglas i ytterligare minst en instans. Denna instans skall installeras på en domän separerad från Anvisningstjänsten. Detta möjliggör att e-tjänster som lokalt integrerar anvisning kan använda speglade instanser som fall-back och därmed undvika ett Single Point of Failure. Det skall också finnas en process/funktion för att forcera nedladdning av data från Metadatatjänsten vid akut ändring av metadata. 2.3.3 Funktion för hantering av användarstatus Anvisningstjänsten skall kunna spara och läsa användares förvalda och aktuella legitimeringstjänster. Med aktuell legitimeringstjänst avses den legitimeringstjänst som användaren använder i befintlig webbläsarsession, och denna funktion används av Anvisningstjänsten för att understödja Single Sign On mellan e-tjänster. Hantering av ovanstående implementeras med webbläsarcookies, eller med funktionen LocalStorage om webbläsaren stödjer denna funktion. Oavsett vilken e-tjänst användaren loggar in mot, och oavsett om en central eller en hos e-tjänsten integrerad anvisning används, skall anvisningslogiken hantera förvald och aktuell legitimeringstjänst. Denna funktion skall göras till en fristående komponent inom Anvisningstjänsten så att den kan användas av både Anvisningstjänsten och av de e-tjänster som integrerar anvisning lokalt. Funktionen för hantering av användarstatus används av funktionen JavaScript för anvisning i följande situationer: Då HTML för val av legitimeringstjänst genereras utför JavaScriptet anrop till funktionen för att först ta reda på om ett aktuellt val av legitimeringstjänst är lagrat i användarens webbläsare, d.v.s., om en legitimeringstjänst redan valts för aktuell webbläsarsession. Om inget aktuellt val existerar utför JavaScriptet ett nytt anrop till funktionen. Denna gång för att läsa användarens förvalda legitimeringstjänst(er).

14(47) Då användaren utför ett val av legitimeringstjänst och indikerar att detta val ska sparas som en förvald legitimeringstjänst sker följande: - Om inget tidigare förval existerar skapas ett förval genom ett anrop till funktionen för hantering av användarstatus. - Om ett tidigare förval existerade och det nya valet skiljer sig från detta uppdateras användarens förval genom ett anrop till funktionen för användarstatus. I alla fall då användaren utför ett val skrivs webbläsarcookien för aktuellt val genom ett anrop till funktionen för användarstatus. Anvisningstjänstens gränssnitt erbjuder användaren möjligheter att rensa tidigare förval (se kapitel 3.2.2, Gränssnitt med föreslaget förval ). Då detta sker utförs ett anrop till funktionen för hantering av användarstatus för att rensa användarens förval. Notera: För Anvisningstjänsten kan läsning och skrivning av förvalda och aktuella legitimeringstjänster hanteras direkt i JavaScriptet om funktionen för hantering av användarstatus exekverar på samma domän som Anvisningstjänsten. I detta fall kan sedvanliga funktioner för läsning och skrivning av webbläsar-cookies användas. För att undvika att Anvisningstjänsten och integrerade lösningar för anvisning hanterar användarstatus på olika sätt skall funktionen för hantering av användarstatus exponera JavaScript-funktioner för läsning och skrivning av status för användande av Anvisningstjänsten. 2.3.4 Webbsida med gränssnitt för val av legitimeringstjänst Den webbsida med gränssnitt för val av legitimeringstjänst som presenteras för användarna ska alltid se likadan ut, och detta utseende styrs av den HTML-kod som Anvisningstjänstens JavaScript genererar. Dock skiljer sig infogandet av JavaScript/HTML beroende på om anvisning utförs av Anvisningstjänsten eller om den integreras lokalt hos en e-tjänst. Sättet användare dirigeras för anvisning och hur resultat av val hanteras skiljer sig också åt mellan de två varianterna. Detta beskrivs i detalj i kapitel 3.1, Tekniska gränssnitt, nedan. Webbsidan har sitt eget JavaScript för att aktivera anvisning via ett anrop till en funktion i JavaScript för anvisning och att hantera dess returnerade val. Webbsidans funktion är att: Skapa sidans grundläggande gränssnittsstruktur: - Övrig information och länkar på sidan som inte tillhandahålls av JavaScriptet som genererar HTML-kod för anvisning. - Färg och stil (CSS). - Placering på sidan för användargränssnittet för val av legitimeringstjänst. Aktivera användargränssnittet som tillhandahålls av JavaScriptet. Tillhandahålla en resultatfunktion som tar emot information om vald e- legitimation och använder denna för att antingen returnera informationen inom ramen för Discovery-protokollet (central anvisning), eller för att vidarebefordra användaren till relevant inloggningstjänst (lokalt integrerad anvisning).

15(47) 3 BESKRIVNING AV GRÄNSSNITT 3.1 TEKNISKA GRÄNSSNITT Detta avsnitt behandlar de gränssnitt som exponeras av Anvisningstjänsten. 3.1.1 Standarder och profiler Anvisningstjänsten tillämpar ett antal standarder och profiler. För fullständiga referenser se kapitel 9. Protokoll och profil för anvisning enligt en http-redirect modell, [idp-disco], utgör basen för integration med Anvisningstjänsten. Standard för SAML metadata [saml-metadata] utgör basstandard för all metadata. Denna information konsumeras av Anvisningstjänsten. SAML extension standard för användargränssnittsdata [saml-meta-mdui] specificerar en extension för lagring av användargränssnittsdata i SAML metadata. Denna information konsumeras av anvisningslogiken då användargränssnitt konstrueras. Interoperabilitetsprofil e-gov 2.0 [saml-egov20] är en SAML interoperabilitetsprofil från Kantara. Denna profil är tillämplig i alla delar som rör anvisning. Interoperabel Web SSO profil [saml2-int] specificerar en SAML deployment profil som är tillämplig för denna tjänstespecifikation i alla delar som rör anvisning. The Entity Category SAML Entity Metadata Attribute Type [entity-category] specificerar ett SAML attribut för Entity Category. Denna information konsumeras av anvisningslogiken då filtrering av legitimeringstjänster utförs. 3.1.2 Gränssnitt för integration med Anvisningstjänsten Gränssnittet för integration med Anvisningstjänsten specificeras i [idp-disco]. Protokollet för anvisning används för att en Service Provider (e-tjänst) skall kunna associera en användare med en Identity Provider (legitimeringstjänst) för legitimering. Anvisningsprotokollet innefattar tre steg och två normativa meddelandeutbyten. 1. E-tjänsten dirigerar (HTTP-redirect) användarens webbläsare till Anvisningstjänsten. I denna begäran skickas också styrande parametrar med. 2. Anvisningstjänsten interagerar med användaren för att etablera ett val av legitimeringstjänst. 3. Anvisningstjänsten dirigerar användarens webbläsare tillbaka till e-tjänsten med en parameter innehållande en identifierare för den valda legitimeringstjänsten. Om parametern utelämnas gjordes inget val.

16(47) Användare (webbläsare) e-tjänst (SP) Anvisningstjänst (DS) Begäran om anvisning genom HTTP redirect till DS Användaren väljer legitimeringstjänst (IdP) Resultat av anvisning returneras till SP genom HTTP redirect Figur 4: Illustration av anvisningsprotokoll enligt [idp-disco]. 3.1.2.1 HTTP-begäran till Anvisningstjänsten Protokollets första steg innebär att e-tjänsten dirigerar användarens webbläsare till Anvisningstjänsten med en HTTP GET-begäran. Följande parameter SKALL skickas med i query-strängen (URL-kodad): entityid Den unika identifieraren för den e-tjänst hos vilken användaren autentiserar sig. Denne identifierare är e-tjänstens entityid i federationens metadata. Följande parametrar är inte obligatoriska men kan skickas i begäran: return policy returnidparam ispassive En URL som specificerar den adress till vilken Anvisningstjänsten ska styra tillbaka webbläsaren efter det att användaren utfört sitt val. Om denna URL inte anges används elementet <idpdisc:discoveryresponse> från e-tjänstens egenskaper i federationens metadata. En parameter som anges av anropande e-tjänst för att ange enligt vilken policy Anvisningstjänsten ska utföra anvisning. Om ingen policy anges antas värdet urn:oasis:names:tc:saml:profiles:sso:idp-discoveryprotocol:single. I nuläget finns inga andra policy-värden definierade, men Anvisningstjänsten skall vara förberedd för att hantera även andra värden. Anger parameternamnet på den parameter som skall innehålla returvärdet innehållande den valda legitimeringstjänsten. Om inget värde anges används parameternamnet entityid. Anger om Anvisningstjänsten tillåts visa ett grafiskt gränssnitt för val av legitimeringstjänst, eller om tjänsten skall försöka härleda

17(47) filter legitimeringstjänst utan att kräva ett val av användaren. Om inget värde anges antas värdet false vilket innebär att Anvisningstjänsten tillåts interagera med användaren via det grafiska gränssnittet. Parametern filter utökar protokollet som beskrivs i [idp-disco] med funktionalitet för att påverka hur filtrering av legitimeringstjänster sker. Om denna parameter specificeras anger dess värde kriterier för att göra legitimeringstjänster valbara i gränssnittet. Till exempel kan en viss tillitsnivå specificeras vilket innebär att endast legitimeringstjänster som uppfyller denna nivå (eller högre) får visas som valbara legitimeringstjänster. Notera: Formatet för värden till parametern filter kommer att definieras i dokumentet [sv-eidprof]. 3.1.2.2 Dirigering tillbaka till e-tjänst Efter att användaren utfört sitt val av legitimeringstjänst skall webbläsaren dirigeras tillbaka till e-tjänsten. Anvisningstjänsten dirigerar webbläsaren till den URL som angavs som värde till return-parametern (se ovan), eller om detta värde inte angavs i begäran till den URL som anges som e-tjänstens standard-url i federationens metadata. Den legitimeringstjänst som valdes av användaren representeras med en unik identifierare (som anges i federationens metadata) och skickas tillbaka som värde till parametern entityid. Om returnidparam angavs i e-tjänstens begäran om anvisning används istället värdet av denna parameter som parameternamn. Om användaren inte utför ett val, eller om Anvisningstjänsten av någon annan anledning inte kan returnera ett val, skall Anvisningstjänsten styra tillbaka användarens webbläsare till e-tjänsten utan parameter för vald legitimeringstjänst. 3.1.3 JavaScript API Då lokalt integrerad anvisning implementeras av e-tjänsten används inte det protokoll som beskrivs i [idp-disco] utan integrering sker genom ett anrop till nedanstående funktion som exponeras från JavaScript för anvisning. Då funktionen anropas genereras HTML-kod för anvisning som inkluderas på angiven plats på e-tjänstens webbsida. Användarens valda legitimeringstjänst överförs till e-tjänsten via ett anrop till den angivna callback-funktionen. function dodiscovery(discoverysettings) Följande namn-värde-par ingår i objektet DiscoverySettings: entityid Den unika identifieraren för e-tjänsten vilken integrerar anvisningen. Denna identifierare är e-tjänstens entityid i federationens metadata. Denna parameter har samma innebörd som anges i protokollet som

18(47) includediv dsproxies uiconfig resultcallback beskrivs i [idp-disco]. Detta värde måste anges. Pekare till ett HTML div-element inom vilket gränssnittet för val av legitimeringstjänst skall placeras på e-tjänstens webbsida. Detta värde måste anges utom i de fall då ispassive=true tilldelas uiconfig (se nedan). En array av en eller flera adresser till e-tjänstens instanser av Proxy för anvisningsdata (se 2.2.2, Lokalt integrerad anvisning ). Detta värde måste anges. Ett objekt av namn-värde par som används för att styra hur gränssnittet för anvisning utformas. Om detta värde inte anges används standardinställningar. Se nedan för möjliga värden. En JavaScript-funktion som tar emot identifieraren för vald legitimeringstjänst (entityid) och använder detta för att legitimera användaren. Om inget val utfördes anropas funktionen med ett nullvärde. Detta värde måste anges. Möjliga namn-värde properties kan tillkomma. Eventuella tillägg ska godkännas av E-legitimationsnämnden. Möjliga namn-värde-par som kan ingå i objektet som tilldelas uiconfig ovan är: ispassive Anger om dodiscovery skall generera HTML-kod för ett grafiskt gränssnitt för val av legitimeringstjänst, eller om funktionen skall försöka härleda legitimeringstjänst utan att kräva ett val av användaren. Motsvarar parametern med samma namn i [idp-disco]. Om inget värde anges antas false. filter Motsvarar parametern med samma namn som beskrivs i 3.1.2.1. Fler namn-värde-par för uiconfig kan komma att definieras. 3.1.3.1 Felhantering Felaktigt utförda anrop, eller misslyckad exekvering, kan leda till att dodiscovery kastar ett JavaScript-exception. Kapitel 4.1.2.4 specificerar vid vilka tillfällen fel kan, och får, rapporteras. Grundkriteriet är att inga aktiviteter som användaren utför får leda till att en exception kastas från funktionen, endast felaktiga anrop eller underliggande systemfel får rapporteras. Exceptions som kastas från dodiscovery skall vara ett JavaScript-objekt innehållande följande namn-värde-par. errorcode description En numerisk felkod. En textuell beskrivning av felet. Denna text skall inte visas för slutanvändaren utan kan användas för intern felrapportering och felsökning.

19(47) De felkoder som definieras skall dokumenteras i Anvisningstjänstens API-dokumentation. 3.2 GRAFISKA GRÄNSSNITT Anvisningstjänstens gränssnitt skall utformas enligt följande kriterier: Det ska tydligt framgå att användaren dirigerats till en tjänst som är en del av federationen för Svensk e-legitimation. Gränssnittet skall vara enkelt och snabbt att använda, både för erfarna användare av e-legitimationer och användare som kan behöva förklaringar och hjälp för att utföra sina val. Gränssnittet skall utformas baserat på en användares status och tidigare val. Anvisningstjänsten skall hantera enheter såsom datorer, läsplattor och mobiltelefoner, och måste därför kunna detektera vilken webbläsare och operativsystem en användare använder. Detta kapitel visar ett antal exempel på hur Anvisningstjänstens gränssnitt kan utformas vid olika typfall. Dessa typfall styrs av användarens tidigare val, om användaren redan legitimerat sig under sessionen och utifrån de tillitsnivåer som uppfylls av olika e-legitimationer. Utformningen av användargränssnitt för Anvisningstjänsten skall göras i samverkan med gränssnittsexperter och E-legitimationsnämnden. Terminologi och begrepp som används i gränssnittet skall utformas i enlighet med E-legitimationsnämndens anvisningar. Den information för val av legitimeringslösning som presenteras av Anvisningstjänsten kan aldrig mellanlagras ( cachas ) i webbläsaren då den aldrig är statisk utan är beroende av användarens status och anropande tjänsts krav. I de exempel som illustrerar Anvisningstjänstens grafiska gränssnitt uppmanas användarna välja e-legitimation istället för legitimeringstjänst, vilket vore det korrekta. Detta är ett exempel på att Anvisningstjänstens grafiska gränssnitt skall anpassas så att detta är pedagogiskt för slutanvändarna. 3.2.1 Gränssnitt vid visning av alla valbara legitimeringstjänster Första gången en användare styrs till Anvisningstjänsten skall samtliga legitimeringstjänster/e-legitimationer som uppfyller e-tjänstens krav 4 vara valbara. I dessa fall har användarens webbläsare inte skickat med cookies som innehåller förvalda eller redan använda e-legitimationer. Bilden nedan illustrerar vilken information som skall exponeras för användaren. Användaren ska tydligt uppfatta att denne dirigerats till Anvisningstjänsten för Svensk e-legitimation. 4 E-tjänstens krav på val av legitimeringstjänst anges i metadata där bland annat begärda tillitsnivåer och kategorier anges.

20(47) En lista över tillgängliga e-legitimationer (eller legitimeringstjänster) ska presenteras. Också med ikoner och beskrivningar (vilket läses från federationens metadata). För användare som är osäkra finns stöd. I exemplet nedan kan användaren klicka på Hjälp mig ta reda på vilken e-legitimation jag har. En sådan sida kan söka assistera användaren, till exempel via frågor eller försök att ladda olika insticksprogram för webbläsaren. I de fall där användaren inte önskar fortsätta sin legitimering finns en Avbryt-knapp. I detta fall utförs inget val utan användaren skall skickas tillbaks till e-tjänsten utan vald legitimeringstjänst. I de allra flesta fall önskar förmodligen användaren att valet som görs ska kommas ihåg av Anvisningstjänsten. I de fall där så inte är fallet (t.ex., vid en lånad dator) kan användaren avmarkera att valet ska sparas. Anvisningstjänsten bör också erbjuda ytterligare information kring e-legitimationer (kapitel 3.2.5, Informationsspridning ). - + Anvisningstjänst för Svensk e-legitimation + Hem Ange språk Hjälp Kontakt Anvisningstjänsten för Svensk e-legitimation Ange den e-legitimation du önskar använda för att legitimera dig BankID Telia e-legitimation Även e-legitimationer från SEB och Skatteverket Mobilt BankID Steria e-legitimation Hjälp mig ta reda på vilken e-legitimation jag har... Avbryt Kom ihåg mitt val Vad är en e-legitimation? Skaffa en e-legitimation Har du tekniska problem med din e-legitimation? Figur 5: Exempel på gränssnitt som visar val av samtliga möjliga legitimeringstjänster. En motsvarande sida anpassad för en för en mobil enhet skulle kunna se ut enligt bilden nedan.