Dokumenthistorik

Introduktion

Nomenklatur

Denna guide har som syfte att stödja organisationer som avser att ansluta sin lokala IdP till Ineras Autentiseringstjänst. En sådan anslutning möjliggör autentisering hos den egna IdP:n m.h.a. SITHS eID-klienterna för Windows och iOS/Android.

Autentiseringstjänsten har för syfte att facilitera autentisering med Out Of Band teknik. Det innebär att säkerhetskanalen är separerad från den primära informationskanalen.
Det är en beprövad teknik som tjänster så som BankID har använt sig av länge. För att kunna använda Autentiseringstjänsten behöver användaren ha klienten installerad på sin desktop eller mobil, samt ha ett godkänt SITHS eID.
För att autentisera sig med mobilen behöver användaren ha utfärdat ett SITHS eID till sin mobil.

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

1. Det finns avtal tecknat med inera.
2. HSA-id inskickat för tjänsten som önskar ansluta.
3. Det finns en organisation och plan för distribution av SITHS eID klienter till användarna.
4. För att kunna använda SITHS eID på iOS/Android så behöver användarna ha tillgång till enheter som som uppfyller vissa krav.
5. 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.
6. Den anslutande IdP:n kan 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 under vilken den anslutande IdP:n måste anpassas för att använda den nya versionen av API:erna.
7. 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".
8. Relying party API:et skyddas av mTLS. För att kunna anropa detta API behöver IdP:n presentera sig med ett SITHS funktionscertifikat vars subject matchar tjänstens HSA-id som läses in i Autentiseringstjänsten vid anslutni

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".
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 som täcker funktionalitet för att:

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.

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

Pollning

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. 

Swaggerdokumentation

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

API för Autentiseringstjänstens Testmiljö

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

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