Användarbeskrivning för Anvisningstjänsten

1 (23) Användarbeskrivning för Anvisningstjänsten

2 (23) INNEHÅLL 1 ALLMÄN BESKRIVNING AV ANVISNINGSTJÄNSTEN... 3 1.1 Skillnad mellan Central och Lokal anvisning... 3 2 INTEGRATION ENLIGT [IDP-DISCO]... 4 2.1 HTTP-begäran till Anvisningstjänsten... 4 3 INTEGRATION ENLIGT MODELLEN FÖR LOKALT INTEGRERAD ANVISNING... 6 3.1 Steg 1 - Inkludering av nödvändiga filer... 6 3.2 Steg 2 Anrop till dodiscovery... 7 3.3 Steg 3 Hantera resultatet... 11 3.4 Steg 4 Anropa getversion... 12 3.5 CSS-filer... 13 3.6 Anvisningsfeed... 13 3.7 DiscoveryError... 13 REFERENSER... 15 APPENDIX A JAVASCRIPT API... 16 1 INTRODUCTION... 16 1.1 Purpose... 16 1.2 Extent... 16 1.3 Definitions, acronyms and abbreviations... 16 2 JAVASCRIPT API... 16 2.1 Namespace... 16 2.2 discosveleg.getversion()... 16 2.3 discosveleg.dodiscovery(discoverysettings)... 17 3 REFERENCES... 19 APPENDIX B EXEMPELKOD INTEGRATION ENLIGT [IDP-DISCO]... 20 APPENDIX C EXEMPELKOD INTEGRATION ENLIGT MODELLEN FÖR LOKALT INTEGRERAD ANVISNING... 22 Versionshantering Version Beskrivning Sign 1.0

3 (23) 1 Allmän beskrivning av Anvisningstjänsten Med hjälp av Anvisningstjänsten ska användare välja vilken e-legitimation de vill använda för en e-tjänst. Valet av e-legitimation kan sparas av Anvisningstjänsten för att göra det lättare för användare som återkommer eller ska välja e- legitimation för en annan e-tjänst. Anvisningstjänsten kan användas antingen via den Centrala Anvisningstjänsten eller integreras lokalt i e-tjänsten. Vid användning av den Centrala Anvisningstjänsten blir användaren dirigerad till sidan för Central Anvisning och kommer där få utföra sitt val av legitimeringstjänst. Användaren dirigeras sedan tillbaka till e-tjänsten med resultatet från den Centrala Anvisningstjänsten. För att använda denna tjänst behövs endast e-tjänstens entityid i federationen. Vid lokal integration initieras Anvisningstjänsten på valfri plats på e-tjänstens webbplats. För detta måste e-tjänsten inkludera filer från Anvisningstjänsten på den webbplats som ska använda Anvisningstjänsten. 1.1 Skillnad mellan Central och Lokal anvisning Vid en central anvisning dirigeras användaren från e-tjänsten till den Centrala Anvisningstjänsten. E-tjänsten skickar med parametrar till Anvisningstjänsten som den behöver för att initiera en anvisning. Användaren får där utföra ett val. Valet skickas sedan till en specificerad adress där e-tjänsten tar emot resultatet. En lokalt integrerad anvisning görs direkt på e-tjänstens sida. E-tjänsten ansvarar här själv för att skapa sidan där användaren utför sitt val genom att använda funktioner som exponeras av Anvisningstjänsten (ingen egen logik för anvisning implementeras). En lokalt integrerad anvisningstjänst kan användas utan något direkt beroende till den centrala Anvisningstjänsten. För att åstadkomma det behöver de filer som används av anvisningstjänsten göras tillgängliga från den miljön där integration sker, se steg 1 för rekommendationer om hur ofta dessa filer bör uppdateras med de senaste uppdateringarna och versionerna.

4 (23) 2 Integration enligt [idp-disco] Integration med den Centrala Anvisningstjänsten utförs enligt SAML Identity Provider Discovery Service Protocol and Profile [2]. Figur 1 visar en översikt av de olika delarna som ingår vid integration enligt [idp-disco]. För exempelkod på integration enligt [idp-disco] se Appendix B Exempelkod integration enligt [idpdisco]. Anvisningstjänsten Anvisningsfeed E-tjänst JavaScript för Anvisning Tjänst för Användarstatus HTTP redirect till Anvisningstjänst enligt IdpDisco-protokollet Användaren loggar in mot e-tjänsten Figur 1: Integration enligt [idp-disco] Användare 2.1 HTTP-begäran till Anvisningstjänsten Vid skapandet av URL till Anvisningstjänsten, används = för att ange vilket värde en parameter har (se Exempel 1). Parametrar och deras värden separeras med tecknet & (se Exempel 2). Exempel 1: https://anvisning.sveleg.se/?entityid=spentityid Exempel 2: https://anvisning.sveleg.se/?entityid=spentityid&ispassive=true För att dirigera användaren till den Centrala Anvisningstjänsten kan t.ex. JavaScript användas (se Exempel 3 och Exempel 4) Exempel 3: var url = https://anvisning.sveleg.se/?entityid=spentityid ; window.location.replace(url);

5 (23) Exempel 4: var url = https://anvisning.sveleg.se/?entityid=spentityid&ispassive=true ; window.location.replace(url); I Exempel 3 och Exempel 4 används window.location.replace(url); för att dirigera användaren till den Centrala Anvisningstjänsten. Efter genomförd anvisning dirigeras användaren till e-tjänstens första <idpdisc:discoveryresponse> (som hämtas från federationens metadata) eller return -parametern om denna har angetts. Om return -parametern anges måste den förekomma under elementet <idpdisco:discoveryresponse> i metadata för den e-tjänsten som anropar den Centrala Anvisningstjänsten. Om ett val görs dirigeras användaren tillbaka till returadressen och parametern entityid eller returnidparam innehåller då entityid för vald legitimeringstjänst. Om användaren inte utför något val dirigerar Anvisningstjänsten användaren tillbaka till returadressen utan parametern entityid eller returnidparam. Ifall egna parametrar önskas skickas med i return URLen får de ej namnges som någon av de parametrar som specificeras i 3.2.1 Obligatoriska parametrar i DiscoverySettings eller 3.2.2 Valfria parametrar i DiscoverySettings.

6 (23) 3 Integration enligt modellen för lokalt integrerad anvisning Detta kapitel beskriver integrationen av lokalt integrerad anvisning samt de obligatoriska och valfria parametrarna som finns. Figur 2 visar en översikt av de olika delar som ingår i lokalt integrerad anvisning. För exempelkod på integration enligt modellen för lokalt integrerad anvisning se Appendix C Exempelkod integration enligt modellen för lokalt integrerad anvisning. Hemsida för e-tjänst https://anvisning.sveleg.se Anvisningsfeed dsproxy för Anvisningsfeed JavaScript för Anvisning Cachat JavaScript för Anvisning Tjänst för användarstatus Figur 2: Lokalt integrerad anvisning 3.1 Steg 1 - Inkludering av nödvändiga filer Fil Filnamn Beskrivning JavaScript för Anvisning anvisning- [version].js Anvisningsfeed discoveryfeed.json JavaScriptet som utför själva logiken för anvisning. Alla funktioner ligger i ett eget namespace, discosveleg. (Se Appendix A JavaScript API för mer information) Innehåller information om e-tjänster och e-legitimationer som är anslutna till federationen. (Se 3.6 Anvisningsfeed för mer information.) CSS-fil Local.css CSS-filen används för att skapa ett användbart gränssnitt så att användaren kan göra sitt val av e-legitimation. (Se 3.5 CSS-filer för mer information.)

7 (23) För att skapa en lokalt integrerad anvisning behövs JavaScript för Anvisning och en CSS-fil. Dessa filer ska cachas lokalt i den miljön som ska göra en lokalt integrerad anvisning. För att undvika att vara helt beroende av sveleg.se måste även Anvisningsfeed cachas (Se 3.6 Anvisningsfeed för beskrivning av anvisningsfeed) i den egna miljön. Anvisningsfeeden uppdateras var tredje minut på sveleg.se, det är rekommenderat att uppdatera kopian i den lokala miljön var tredje minut för att ha den senaste filen. JavaScript för anvisning uppdateras en gång per dag på sveleg.se, det är rekommenderat att uppdatera kopian i den lokala miljön en gång per dag för att säkerställa att den senaste minor- och fix-versionen finns i JavaScript för anvisning. CSS-filer uppdateras var tredje dag på sveleg.se. För att använda den senaste versionen av CSS-filen rekommenderas att uppdatera kopian i den lokala miljön var tredje dag. Anvisning startar genom ett anrop till funktionen discosveleg.dodiscovery (se 3.2 Steg 2 Anrop till dodiscovery för mer information). Både JavaScript för Anvisning och CSS-filen behöver vara inkluderade i html-dokumentet innan funktionsanropet till discosveleg.dodiscovery utförs. Exempel: <link href="lokalcss.css" media="screen,projection" rel="stylesheet" type="text/css"> <script src="anvisningsscript.js"></script> <script> // Se 3.2 Steg 2 Anrop till dodiscovery </script> 3.1.1 jquery JavaScript för Anvisning använder sig av jquery, vilket skapas under ett eget alias (discosvelegjq) för att undvika konflikter med andra versioner av jquery som e- tjänsten använder sig av. Har e-tjänsten redan laddat in jquery med en version som är godkänd för anvisningstjänsten (se federationswebben för godkända versioner) använder JavaScript för Anvisning sig av det redan inladdade jqueryscriptet. 3.2 Steg 2 Anrop till dodiscovery För att starta den lokala anvisningen behöver funktionen dodiscovery anropas. dodiscovery tar ett DiscoverySettings-objekt som inparameter. DiscoverySettings-objektet innehåller de inställningar och den information som dodiscovery behöver för att kunna skapa en lokalt integrerad anvisning. Följande exempel visar hur ett DiscoverySettings-objekt kan se ut och en utförligare

8 (23) beskrivning av de olika parametrarna i DiscoverySettings-objektet finns i 3.2.1 Obligatoriska parametrar i DiscoverySettings och 3.2.2 Valfria parametrar i DiscoverySettings. Exempel: var DiscoverySettings = { entityid :"SPEntityID", includeelement:"givendiscoveryelement", dsproxies: ["https://discovery.feed.url.se/discoveryfeed.json"], uiconfig:{language:"en", resultcallback: discoverycallback, errorcallback: discoveryerrorcallback discosveleg.dodiscovery(discoverysettings); 3.2.1 Obligatoriska parametrar i DiscoverySettings entityid entityid för e-tjänsten som anvisningen inkluderas i, detta entityid måste stämma överens med det entityid som finns i federationens metadata. includeelement includeelement specificerar id för det HTML-element där gränssnittet för val av legitimeringstjänst ska placeras på e-tjänstens webbsida. Utöver själv gränssnittet inkluderas ett inbäddat HTML-dokument (en iframe) vilken används för den centrala funktionen för hantering av användarstatus (hanterar användarens aktuella val och förval). Den centrala funktionen för hantering av användarstatus lagrar aktuellt val och förval med hjälp Web Storage om webbläsaren har stöd för detta, annars lagras de som webbläsarcookies. För kommunikationen mellan JavaScript för Anvisning och den centrala funktionen för hantering av användarstatus används PostMessage. JavaScript för anvisning rensar innehållet i det html-element som har id som stämmer överens med includeelement. Det inre innehållet i det HTML-element som specificeras av includeelement ersätts helt av innehåll genererat av JavaScript för Anvisning. Rekommenderade storleken på HTML-elementet där gränssnittet för val av legitimeringstjänst ska placeras är: Width - 480px Height - 625px

9 (23) Anvisningstjänsten har dock en minimal bredd på 280px och kommer därför att ha bredden 280px även om bredden på elementet är satt till under 280px. Exempel (här skapas en div med id="showdiscovery" som sedan anges som includeelement i DiscoverySettings): <div id="showdiscovery" style="width: 480px; height: 625px;"></div> <script> var DiscoverySettings = { entityid :"SPEntityID", includeelement:"showdiscovery", dsproxies: ["https://discovery.feed.url.se/discoveryfeed.json"], resultcallback: discoverycallback, errorcallback: discoveryerrorcallback discosveleg.dodiscovery(discoverysettings); </script> dsproxies En lista med länkar till anvisningsfeed. För att hålla god tillgänglighet är det rekommenderat att ta med länkar både till det lokalt cachade feedet och även feedet på sveleg.se. Se 3.6 Anvisningsfeed för mer information om anvisningsfeed. resultcallback resultcallback är en callback-funktion som ska ta en parameter. Det är via denna funktion som dodiscovery sedan returnerar resultatet från anvisningen. Om användaren gör ett val av legitimeringstjänst returneras legitimeringstjänstens entityid till resultcallback. Om inget val görs av användaren returnerar dodiscovery null till resultcallback. Se 3.3 Steg 3 Hantera resultatet för mer information om hur resultatet ska hanteras. errorcallback errorcallback är en callback-funktion som ska ta en parameter. Det är till denna funktion som dodiscovery returnerar eventuella felmeddelanden från anvisningen. Funktionsparametern innehåller då ett discoveryerror-objekt. Se 3.3 Steg 3 Hantera resultatet för mer information om hur errorcallback ska hanteras.

10 (23) 3.2.2 Valfria parametrar i DiscoverySettings uiconfig Ett objekt som kan innehålla parametrar för att modifiera hur anvisningstjänsten visas grafiskt och hur den beter sig. Om en parameter inte anges använder anvisningstjänsten standardvärden istället. För närvarande finns fyra parametrar för uiconfig tillgängliga, ispassive, language, showcancelbutton och showhelplinks vilka beskrivs nedan. Fler parametrar för uiconfig kan komma att definieras. uiconfig - ispassive ispassive är en boolesk variabel som kan ha värdet true eller false. Standardvärdet är false. Om ispassive har värdet true kommer användarens val av e-legitimation härledas utan att något gränssnitt visas. Om användaren har gjort ett val av e- legitimation tidigare i samma session returneras entityid för den e-legitimationen som resultat till resultcallback. Om inget tidigare val av e-legitimation har skett inom samma session returneras null till resultcallback. Om ispassive har värdet false kommer ett gränssnitt för val av legitimeringstjänst att presenteras. Exempel: uiconfig = { ispassive: true uiconfig - language Denna parameter kan användas för att ändra språk på Anvisningstjänsten. Om anvisningstjänsten stödjer språket visas fraserna på det angivna språket, om språket inte stödjs kommer svenska att användas. De legitimeringstjänster som har stöd för det angivna språket kommer visas på det angivna språket, om legitimeringstjänsten inte har stöd för språket visas de på svenska. (Se federationswebben för information om vilka språk som stödjs av anvisningstjänsten). Språk anges med två eller tre bokstäver enligt IANA Subtag Registry [1]. Exempel: uiconfig = { language:"sv" uiconfig - showcancelbutton showcancelbutton är en boolesk variabel som kan ha värdet true eller false. Standardvärdet är false. Om showcancelbutton har värdet true kommer kommer

11 (23) en avbryt-knapp visas i gränssnittet. Om showcancelbutton har värdet false kommer ingen avbryt-knapp att visas i gränssnittet. Om användaren klickar på avbryt-knappen kommer null returneras till resultcallback (se 3.3.1 resultcallback). Exempel: uiconfig = { showcancelbutton: true uiconfig - showhelplinks showhelplinks är en boolesk variabel som kan ha värdet true eller false. Standardvärdet är true. Om showhelplinks har värdet true kommer hjälp-länkar att visas längst ner i gränssnittet. Om showhelplinks har värdet false kommer inga hjälp-länkar visas längst ner i gränssnittet. Exempel: uiconfig = { showhelplinks: true 3.3 Steg 3 Hantera resultatet 3.3.1 resultcallback resultcallback-funktionen behöver skapas innan dodiscovery anropas. När användaren har gjort ett val eller väljer att inte göra ett val anropar dodiscovery resultcallback-funktionen. Resultatet skrivs till parametern i funktionen. Ifall inget val görs innehåller parametern null. Om användaren gör ett val innehåller parametern entityid för legitimeringstjänsten för den valda e-legitimationen. Exempel på resultcallback: var discoverycallback = function (result) { if(result == null) { alert("inget val gjordes av användaren."); else { alert("användaren valde: " + result); 3.3.2 errorcallback Callback-funktionen errorcallback behöver skapas innan dodiscovery anropas. Det är till denna funktion som anvisningstjänsten returnerar eventuella fel som uppstår under anvisningen (Se kapitel 3.3.3 för undantag). errorcallbackfunktionen tar en parameter där anvisningstjänsten sätter ett discoveryerror-objekt (se 3.7 DiscoveryError). Om ett fel inträffar anropar dodiscovery enbart

12 (23) errorcallback-funktionen, inget resultat returneras då via resultcallbackfunktionen. Exempel på errorcallback: var errorcallback= function(errorobject) { alert("error code: " + errorobject.errorcode + ". Description: " + errorobject.description); Exempel på lokal anvisning: <div id="showdiscovery" style="width: 480px; height: 625px;"></div> <script> var discoverycallback = function (result) { if(result == null) { alert("inget val gjordes av användaren."); else { alert("användaren valde: " + result); var errorcallback= function(errorobject) { alert("error code: " + errorobject.errorcode + ". Description: " + errorobject.description); var DiscoverySettings = { entityid :"SPEntityID", includeelement:"showdiscovery", dsproxies: ["https://discovery.feed.url.se/discoveryfeed.json"], resultcallback: discoverycallback, errorcallback: discoveryerrorcallback discosveleg.dodiscovery(discoverysettings); </script> 3.3.3 Felhantering I fallet då DiscoverySettings-objektet inte skickas med till dodiscovery kastar dodiscovery ett JavaScript-Exception med ett discoveryerror-objekt. I fallet då errorcallback eller resultcallback inte skickas med i DiscoverySettingsobjektet kastar dodiscovery ett JavaScript-Exception med ett discoveryerrorobjekt. 3.4 Steg 4 Anropa getversion För att kontrollera vilken version av JavaScript för Anvisning som körs kan funktionen discosveleg.getversion() anropas. discosveleg.getversion() returnerar en sträng där versionsnummer på JavaScript för Anvisning anges enligt följande format: major.minor.fix.

13 (23) 3.5 CSS-filer Vid lokalt integrerad anvisningstjänst kan e-tjänsten själv modifiera utseendet på tjänsten så att den blir mer enhetlig med resten av e-tjänstens hemsida. Detta görs genom att antingen modifiera befintliga CSS-filer eller att skapa helt nya filer. Det är en rekommendation att använda de CSS-filer som finns tillgängliga på federationswebben. 3.6 Anvisningsfeed Anvisningsfeed är en json-fil som innehåller information om de e-tjänster och legitimeringstjänster (legitimering/autentisering av respektive e-legitimation) som är anslutna till federationen. Informationen som finns i anvisningsfeedet är från federationens metadata. Det är med hjälp av denna information som anvisningstjänsten skapar det gränssnittet där användaren utför anvisningen. De legitimeringstjänster som inte uppfyller de krav som e-tjänsten ställer på användarens e-legitimation, sorteras bort från listan med valbara legitimeringstjänster. Det är därför viktigt att anvisningstjänsten har tillgång till ett anvisningsfeed. Se federationswebben för URL till den aktuella versionen av anvisningsfeed för de olika versionerna av JavaScript för anvisning. 3.7 DiscoveryError DiscoveryError är ett JavaScript-objekt som innehåller errorcode och description. 3.7.1 errorcode errorcode är den numeriska koden för det fel som har inträffat i anvisningstjänsten. (Se 3.7.3 Lista på fel för mer information om vilka numeriska koder som finns) 3.7.2 description description innehåller en sträng som kort beskriver vad som gick fel under anvisningen. (Se 3.7.3 Lista på fel för mer information om vilka beskrivningar som finns) 3.7.3 Lista på fel errorcode: 100 description: Missing input parameter to dodiscovery

14 (23) Förklaring: DiscoverySettings-objektet skickades inte med i anropet till dodiscovery. errorcode: 101 description: An entityid for the e-service must be supplied Förklaring: entityid-parametern saknas i DiscoverySettings-objektet. errorcode: 102 description: An correct id for insertion element must be supplied Förklaring: includeelement-parametern saknas i DiscoverySettings eller ett element med id som stämmer överens med includeelement saknas i e-tjänstens webbsida. errorcode: 103 description: An array of one or more addresses to the discovery feed must be supplied Förklaring: dsproxies-parametern saknas i DiscoverySettings. errorcode: 104 description: A resultcallback function must be supplied Förklaring: resultcallback-parametern saknas i DiscoverySettings. errorcode: 105 description: Calling e-service lacks required elements in metadata Förklaring: E-tjästen saknar obligatoriska element i metadata. errorcode: 106 description: E-service entityid does not exist in metadata Förklaring: Det entityid som har skickats med finns inte med i federationens metadata, kontrollera att e-tjänsten är tillagd i federationen och att rätt entityid är angivet i parametern entityid. errorcode: 107 description: Underlying discovery feed cannot be reached Förklaring: Anvisningstjänsten kan inte komma åt de anvisningsfeeds som angivits i dsproxies. Kontrollera att länkarna fungerar. errorcode: 108 description: A errorcallback function must be supplied Förklaring: errorcallback-parametern saknas i DiscoverySettings. errorcode: 109 description: No IdP:s available for selection

15 (23) Förklaring: Det finns inga legitimeringstjänster att välja. Detta beror troligtvis på att filtrering har utförts vilket har lett till att det inte finns några legitimeringstjänster som uppfyller de filtreringskrav som har ställts. Referenser [1] IANA Language Subtag Registry, [Online]. Available: http://www.iana.org/assignments/language-subtag-registry/language-subtagregistry. [2] SAML Identity Provider Discovery Service Protocol and Profile, [Online]. Available: http://docs.oasis-open.org/security/saml/post2.0/sstc-saml-idpdiscovery.pdf.

16 (23) Appendix A JavaScript API 1 Introduction This document gives an overview over the Discovery Service JavaScript API for the Swedish eid framework. The JavaScript API is used for both the Central Discovery Service and the locally integrated Discovery Service. 1.1 Purpose This API will be used to create the interface in which the user can select an identity provider. Every service provider will be able to use different parameters and calls to modify how the interface will be displayed. 1.2 Extent Service providers will use this API to show the user an interface, in which the user can choose an identity provider that will be returned to the service provider. The API uses a discovery feed, which contains information about the identity providers that could be displayed in the interface; it also contains information about the service providers and will use this information to filter which identity providers the user will be able to choose from. The discovery feed originates from the federation metadata. 1.3 Definitions, acronyms and abbreviations Term IdP SP API Definition Identity Provider Service Provider Application Programming Interface 2 JavaScript API 2.1 Namespace All the functions within the JavaScript API for the Swedish eid framework are declared in a namespace called discosveleg. 2.2 discosveleg.getversion() Returns a string containing the version of the API in the format: major.minor.fix.

17 (23) 2.3 discosveleg.dodiscovery(discoverysettings) dodiscovery is the main function in the API, which will create the interface for the user to make the choice of IdP. dodisovery is called according to the following way: discosveleg.dodiscovery(discoverysettings) 2.3.1 DiscoverySettings The DiscoverySettings object contains several key-value pairs and a callback function is used to transfer the user selected Identity Provider. The key-value pairs and the callback function are further described in the following subsections. Example of a DiscoverySettings object: var DiscoverySettings = { entityid: https://www.testsp.se/sp1, includeelement: showdiscovery, dsproxies: [ https://anvisning.sveleg.se/discoveryfeed.json ], uiconfig: { ispassive : false, resultcallback: discoverycallback, errorcallback: errorcallback entityid Required. The ID of the Service Provider. includeelement Required. The ID of the HTML element in which dodiscovery will create the interface. The inner contents of this HTML element will be replaced with the contents generated by the discovery service. dsproxies Required.

18 (23) dsproxies is a list containing one or more addresses to the disoveryfeed. The API will try to open the first address in the array and then move to the next if it could not open it. uiconfig Not required. A dictionary containing parameters on how to display the interface. Right now ispassive, language, showcancelbutton and showhelplinks are supported keys in uiconfig. ispassive: Not required. ispassive is a Boolean variable. If ispassive is not specified in uiconfig it will be set to the default value: false. If ispassive is set to true, then the API will try to derive the user choice of IdP without showing the interface for the user. The API checks if the use has an active choice in the current browser session and then returning that choice. If no choice has been made in the current browser session the API returns null. language: Not required This parameter specifies the preferred language of the API interface. The API interface will be translated if the language is supported, otherwise Swedish will be used. The API will also check if the IdP s have the language supported, and if they do it will be translated into the language, if they don t, they will be shown in Swedish. The language is specified with two or three letters according to IANA Subtag Registry [1]. E.g. en for English and sv for Swedish. showcancelbutton: Not required showcancelbutton is a Boolean variable. If showcanelbutton is not specified in uiconfig it will be set to the default value: false. If showcancelbutton is set to true then a cancel button will be shown in the graphical interface. If the user clicks on the cancel button then null will be returned to resultcallback. showhelplinks: Not required showhelplinks is a Boolean variable. If showhelplinks is not specified in uiconfig it will be set to the default value: true. If showhelplinks is set to true then help links will be shown in the bottom of the graphical interface. resultcallback Required. This callback function will be used by the API when a choice has been made to send back the result. The function should take one parameter to receive the result.

19 (23) The result will either be the choice of IdP or null if no choice was made by the user. errorcallback Required. When an error occurs in the API it will call this callback function with a JavaScript-object containing key-value pairs. An exception to this is when the DiscoverySettings-object is missing from the dodiscovery call or if either resultcallback or errorcallback is missing from the DiscoverySettings-object. If this happen dodiscovery will throw a JavaScript-exception with a JavaScriptobject containing key-value pairs. The JavaScript-object contains this key-value pair: errorcode Numeric code. description A description of the error. Error codes 100 - Missing input parameter to dodiscovery 101 - An entityid for the e-service must be supplied 102 - A correct id for the insertion element must be supplied 103 - An array of one or more addresses to the discovery feed must be supplied 104 - A resultcallback function must be supplied 105 - Calling e-service lacks required elements in metadata 106 - E-service entityid does not exist in metadata 107 - Underlying discovery feed cannot be reached 108 - An errorcallback function must be supplied 109 - No IdP:s available for selection 3 References [1] http://www.iana.org/assignments/language-subtag-registry/language-subtagregistry

20 (23) Appendix B Exempelkod integration enligt [idp-disco] <!DOCTYPE HTML> <html lang="sv"> <head> <title>central anvisning</title> </head> <body> <center> <button id="dodiscovery" type="button">do Discovery</button> </center> </body> <script src="//ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js"></script> <script type="text/javascript"> $('#dodiscovery').click( function() { / entityid - Required The entityid of the Service Provider. var entityid = 'Replace this with your entityid; / return - Not required Specifies the return URL. Default: DiscoveryResponse URL from DiscoveryFeed. var returnpath = ""; / policy - Not required Sets the policy that will be used by the Discovery service. Default: urn:oasis:names:tc:saml:profiles:sso:idp-discovery-protocol:single. var policy = "urn:oasis:names:tc:saml:profiles:sso:idp-discovery-protocol:single"; / returnidparam - Not required Sets a custom return parameter name that will contain the return value from central discovery service. Default: entityid var returnidparam = "entityidcustom"; / ispassive - Not Required. Set to true - dodiscovery will try to get the result without a user input. It will check if the user has an active choice and will return it directly. Set to false (default) - dodiscovery will be shown for the user and wait for the user to make a choice. var ispassive = false; / Create the URL for sending the user to the Central Discovery service. Add the parameter and value pairs with '&' as separator. var url = 'https://anvisning.sveleg.se/' + "?entityid=" + entityid + "&return=" + returnpath

21 (23) + "&policy=" + policy + "&returnidparam=" + returnidparam + "&ispassive=" + ispassive; / Change the page to CentralDiscovery. When the user has chosen, it will be sent back to the URL specified by the metadata for the Service Provider. window.location.replace(url); ); </script> </html>

22 (23) Appendix C Exempelkod integration enligt modellen för lokalt integrerad anvisning <!DOCTYPE HTML> <html lang="sv"> <head> <title>lokalt integrerad anvisning</title> <!-- Include the CSS for Discovery. This CSS will modify the content inside the Discovery DIV --> <link href="compact.local.css" rel="stylesheet" media="screen"> </head> <body> <center> <h1>lokalt integrerad anvisning</h1> <!-- Area where the locally integrated discovery UI will be inserted --> <div id="showdiscovery" style="width:600px;"> </div> </center> <!-- Include the JavaScript for making a Discovery.--> <script src="anvisning-1.js"></script> <script> //JavaScript to start dodiscovery. / entityid - Required The entityid of the Service Provider. Change YourEnityID to your own entityid var entityid = 'Replace this with your entityid'; //This entityid must exist in the metadata as a ServiceProvider. / includeelement - Required The id of the element where dodiscovery should show its content. var includediv = 'showdiscovery'; / dsproxies - Required An array that contains one or more addresses for DiscoveryFeed. var dsproxies = ["discoveryfeed.json"]; / ispassive - Not Required. Set to true - dodiscovery will try to get the result without a user input. It will check if the user has a active choice and will return it directly. Set to false (default) - dodiscovery will be shown for the user and wait for the user to make a choice. var ispassive = false; / language - not Required Send empty string to use the default value - "sv" Swedish is the default value. Language entered according to the IANA Language Subtag Registry (http://www.iana.org/assignments/language-subtag-registry). var lang = "sv"; / showcancelbutton - not Required Set to true - The graphical interface will show a cancel button which returns null to resultcallback is pressed by the user. var showcancelbutton = false; /