Dokumenthistorik

...

Introduktion

Autentiseringstjänsten tillhandahåller autentisering för legitimering och underskrift via SITHS eID Windowsklient och SITHS eID Mobilklient (SITHS eID-klienterna) för användare som har e-legitimation från Identifieringstjänst SITHS.

Denna guide har som syfte att stödja organisationer som avser att ansluta en e-tjänst eller lokal IdP till Inera Autentiseringstjänst.

Övergripande information och val av integrationsmönster

Det finns tre integrationsmönster för organisationer som vill koppla e-tjänster mot autentisering via Autentiseringstjänsten och SITHS eID-klienterna.

1. Anslutning av lokal e-tjänst till Ineras IdP
2. Anslutning av lokal IdP till Ineras IdP (proxy-anslutning)
3. Anslutning av lokal IdP till Autentiseringstjänsten (direktanslutning)

I integrationsmönster 1 och 2 ovan så kommunicerar den lokala e-tjänsten eller IdP:n med Ineras IdP via SAML- eller OIDC-protokollet. Ineras IdP är i sin tur ansluten till Autentiseringstjänsten och tillhandahåller dess autentiseringsmetoder som den lokala tjänsten kan välja att exponera för sina användare. I integrationsmönster 3 så ansluter den lokala IdP:n direkt till Autentiseringstjänsten via Ineras proprietära API. Alla tre integrationsmönstren beskrivs närmare under respektive rubrik nedan.

Oavsett val av integrationsmönster så finns det hänsynstaganden som behöver hanteras av alla organisationer som avser att använda sig av Autentiseringstjänsten för legitimering och signering.

Generellt anslutningsflöde

1. Anmäl intresse, teckna avtal med Inera
2. Fyll i relevant förstudiemall för testanslutning och skicka in för granskning.
3. När förstudien är godkänd kan anslutning upprättas mellan den lokala tjänstens testmiljö och testmiljö hos Ineras tjänst (IdP eller Autentiseringstjänsten, beroende på val av integrationsmönster).
4. Testa anslutningen och funktionen i test.
5. Fyll i ny förstudie för produktionsanslutning, bifoga testrapport som visar att integrationen fungerar som tänkt.
6. När förstudien mot produktion är godkäns kan anslutning ske mellan produktionsmiljöerna.

Förutsättningar

• Användarna har SITHS eID på kort (används för inloggning via windowsklienten, samt för att utfärda Mobilt SITHS eID).
• Den anslutande tjänsten har ett SITHS Funktionscertifikat.
• Det finns en organisation och en plan för att distribuera SITHS eID-klienterna till användarna samt hålla dessa uppdaterade.

Nätverk

• Användarnas SITHS eID-klienter behöver kunna kommunicera med Autentiseringstjänsten och Utfärdandeportalen.
• För att kunna utfärda/administrera Mobilt SITHS eID så måste användarnas browser kunna komma åt Utfärdandeportalen samt den instans av Ineras IdP som Utfärdandeportalen använder sig av för autentisering.
• För de integrationer som ansluter till Ineras IdP så måste denna vara åtkomlig från användarnas enheter.

Brandväggsöppningar

<TODO> Sökvägar och brandväggsöppningar

Sjunet

<TODO> Guide till IdP

Distribution av SITHS eID-klienterna

Mobilklienterna laddas ner via App Store eller Google Play. Windowsklienten tillgängliggörs i detta confluence-space och organisationer kan välja att distribuera den själva eller att dela länken med sina användare.

Se nedan för länkar till specifik information kring respektive applikation.

Windowsklienten

Användarhandbok - SITHS eID Windowsklient.

SAD - SITHS eID Windowsklient

Guide för supporterade enheter - SITHS eID Windowsklient

Mobilklienten

Användarhandbok - SITHS eID Mobilklient

SAD - SITHS eID Mobilklient

Guide för supporterade enheter - SITHS eID Mobilklient

Nerladdningslänkar

• Windows: Ladda ner SITHS eID Windowsklient
• iOS: https://apps.apple.com/se/app/siths-eid/id1498029661
• Android: https://play.google.com/store/apps/details?id=se.inera.authclient.produktion

Anslutning av lokal e-tjänst till Ineras IdP

En e-tjänst kan ansluta till Ineras IdP som en SAML SP (Service Provider) eller OIDC RP (Relying Party). Vilka autentiseringsmetoder som är tillgängliga för användarna konfigureras i IdP per e-tjänst, det går således att välja vid anslutningen att endast använda ett urval av de autentiseringsmetoder som Ineras IdP tillhandahåller.

• e-tjänsten väljer vilka autentiseringsmetoder som skall vara valbara för användare.
• e-tjänsten anger i sitt metadata (om SAML) eller i autentiseringsanropet (om OIDC) vilka användarattribut som önskas.
• Inera IdP tillhandahåller användarattribut som finns i den nationella HSA-katalogen samt presenterar uppdragsval för användaren.
• Inera IdP tolkar och förmedlar tillitsnivå (LoA) utifrån användarens certifikat.

Se Guide till IdP för vidare information om anslutning till Ineras IdP.

Image Removed

Anslutning av lokal IdP till Ineras IdP (proxy-anslutning)

En lokal IdP kan anslutas som en OIDC RP eller SAML SP mot Ineras IdP och agera som en "proxy-IdP". Anslutningen sker (med några undantag) som en vanlig anslutning av en e-tjänst till Ineras IdP.

• Lokal IdP implementerar en SAML-SP eller en OIDC-RP som ansluts till Ineras IdP.
• Lokal IdP väljer vid anslutningen vilka autentiseringsmetoder som Inera IdP skall tillhandahålla för användare.
• Inera IdP tillhandahåller attribut som rör autentisering av användaren.
• Övriga användarattribut hämtar lokal IdP från den lokala katalogtjänsten. Lokal IdP ansvarar för uppdragsval.
• Lokal IdP beräknar tillitsnivå (LoA) utifrån certifikatsattribut som Ineras IdP tillhandahåller.
  • Se Tillitsnivå (LoA) för information om hur Ineras IdP tolkar tillitsnivåer.

Image Removed

Tillgängliga attribut för en lokal IdP

Förutom attribut som alltid anges i SAML-biljetten eller OIDC-tokens per default (se Attributlista), så är följande attribut tillgängliga för en lokal IdP att begära från Inera IdP:

...

amr

...

urn:sambi:names:attribute:x509IssuerName

http://www.w3.org/2000/09/xmldsig#X509IssuerName

...

http://www.w3.org/2000/09/xmldsig#X509SubjectName

...

Anslutning av lokal IdP till Autentiseringstjänsten (direktanslutning)

En lokal IdP kan anslutas direkt till Autentiseringstjänsten via Ineras proprietära API.

• Lokal IdP ansvarar för eventuellt val av inloggningsmetod
• Lokal IdP förmedlar autostarttoken till SITHS eID-klienterna
• Lokal IdP ansvarar för att tolka och förmedla tillitsnivå, utifrån information från användarcertifikatet som levereras från Autentiseringstjänsten.
  • Se Tillitsnivå (LoA) för information om hur Ineras IdP tolkar tillitsnivåer.

Image Removed

Förutsättningar för anslutning till Autentiseringstjänsten

1. Det finns avtal tecknat med Inera.
2. HSA-id för tjänsten som önskar ansluta förmedlas för inläsning i Autentiseringstjänsten.
3. Den anslutande tjänsten är en central IdP för den anslutande organisationen. Varje kund tillåts ha en ansluten IdP, med eventuellt undantag för exempelvis de största regionerna.
   1. Denna begränsning ämnar dels till att möjliggöra följsamhet mot referensarkitekturen, som specificerar att autentisering skall centraliseras till en specialiserad tjänst.
   2. Att hålla nere antalet anslutna tjänster är också avgörande för att kunna säkerställa att anslutna system håller sina anslutningar uppdaterade i takt med att Autentiseringstjänsten förändras.
4. Den anslutande IdP:n måste hållas uppdaterad i takt med att Autentiseringstjänsten och dess API:er förändras.
   1. När nya versioner av API:erna släpps så kommer de gamla API-versionerna att ligga aktiva parallellt med de nya under en övergångsperiod på 6 månader under vilken den anslutande IdP:n måste anpassas för att använda den nya versionen av API:erna.
5. Den anslutande IdP:n stödjer appväxling. IdP:n behöver kunna anropa det externa protokollet "siths://" för att kunna autostarta SITHS eID-klienterna vid inloggning "på samma enhet".
6. Relying party API:et skyddas av mTLS. För att kunna anropa detta API behöver IdP:n presentera sig med ett SITHS funktionscertifikat (SITHS e-id Function CA v1) vars subject matchar tjänstens HSA-id som läses in i Autentiseringstjänsten vid anslutningstillfället.

Teknisk Information

Flödesbeskrivning

1. Anslutande tjänst (RP) startar flödet med AT genom att skicka en förfrågan till "auth" med information om bland annat subject och autentiseringsförfrågans organisationstillhörighet. 
2. AT svarar på förfrågan till "auth" genom att skicka tillbaka en "orderRef" (referens till utfärdad autentiseringsförfrågan) samt en "autoStartToken". RP förmedlar denna autostarttoken till SITHS eID-klienten m.h.a. appväxling eller QR-kod.
3. RP kollar (förslagsvis kontinuerligt m.h.a pollning) mot "collect" hos AT för att se om AT fått autentiseringen legitimerad av subject. Till "collect" skickas tidigare mottagna "orderRef" som är kopplad till en autentiseringsförfrågan.
4. AT svarar på förfrågan till "collect" genom att skicka tillbaka en status och tillhörande data om huruvida kopplad autentiseringsförfrågan blivit legitimerad, om den blivit legitimerad är autentiseringsflödet nu avklarat.
   1. alternativt kan subject välja att avbryta ("cancel") en legitimering och då avslutas autentiseringsflödet och detta meddelas som svar på "collect".

Autentiseringstjänstens API

Autentiseringstjänstens API är indelat i tre delar:

1. Relying Party API: API för att RP ska kunna starta och konsumera autentiserings- och signerings-förfrågningar.
2. Client API: API för att en klient ska kunna resolvera autentiserings- och signerings-förfrågningar.
3. Registration Authority: API för att registrera och aktivera certifikat.

Anslutande IdP:er kommunicerar via Relying Party API. 

Anrop där förmedling av certifikat krävs ska ske mot adresser som är prefixade med secure. T.ex. för test https://secure-authservice.idp.ineratest.org/.

...

Autentiseringstjänstens API-dokumentation tillgängliggörs via swagger på Autentiseringstjänsten med följande sökväg: "/openapi/swagger-ui/index.html?url=/v3/api-docs/rp#".

Exempel för Testmiljön: 

https://authservice.idp.ineratest.org/openapi/swagger-ui/index.html?url=/v3/api-docs/rp#

https://secure-authservice.idp.ineratest.org/

Hänsynstaganden vid anrop mot /auth

Parametern "checkRevocation" anger huruvida Autentiseringstjänsten skall utföra revokeringskontroll på användarcertifikatet och bör sättas till "true". Det är fullt möjligt att utföra revokeringskontrollen i IdP efter autentiseringen är utförd, men det rekommenderas att delegera detta till Autentiseringstjänsten för att eventuella fel i autentiseringen skall upptäckas så tidigt som möjligt i flödet.

Parametern "enhancedAuthentication" måste sättas till "true". Den var initialt menad att kunna ange huruvida autostarttoken krävdes eller inte, men klienterna stödjer inte längre flödet utan autostarttoken. Parametern lär försvinna helt i framtida versioner.

Hänsynstaganden vid anrop mot /collect

Pollning mot autentiseringstjänsten ska göras från servern. Det vill säga en användare ska inte kunna påverka hur ofta pollningen mot autentiseringstjänsten sker (annat än att påbörja sin inloggning).
Rekommenderat tidsinterval för pollning är 2 sekunder.

Starta klienten och förmedla autostarttoken

Kopplingen till klienten skapas genom att klienten från IdP får en autostarttoken (som IdP från från Autentiseringstjänsten i svaret ifrån anropet till /auth) som klienten sedan använder i sitt anrop mot Autentiseringstjänsten. Förmedligen av autostarttoken till klienten kan ske på två sätt:

1. Autostart via appväxling m.h.a. custom-protokollet <siths://> (om autentisering på samma enhet)
2. QR-kod som scannas in med Mobilklienten (om autentisering på annan enhet)

...

siths://?autostarttoken=<autostarttoken>

Vid inloggning med annan enhet (mobil eller platta) ska en QR kod genereras och exponeras av IdP:n och skannas av med hjälp av Mobilklienten.
QR koden ska innehålla värdet <autostarttoken>.