Beskrivning

I "EFI-piloten" avser vi hitta pilotaktörer som är villiga att delta med sina system för att genomföra pilotverksamhet avseende dessa system för anslutning mot NLL. Då det finns risker kring att hitta pilotaktörer samt då dessa piloter kan genomföras har tanken på ett "torrsim" i EFI-piloten väckts. Detta torrsim är inte möjlig eller rimlig att "ta i produktion" i ett senare skede - det är alltså snarare en POC än en pilot. Detta torrsim (hädanefter POC) utgår inte från en befintlig aktör med förutsättningar för att delta i piloten, utan samtliga delar som ingår byggs för POCen.

Målet är att i POC simulera det som behövs för att ett it-system ("klient") i organisation A ska kunna göra ett API-anrop till ett API i organisation B enligt de mönster "delegerad åtkomst" och med de standarder för digital samverkan och federativ infrastruktur som beskrivs inom Ena.

POC implementerar 2.1 enligt inter-domain-calls.md och SSO enligt authn-authz-patterns.md. Tanken är att kunna utöka POC i ett andra steg till att implementera 2.2 (inter-domain-calls) och eventuellt växling av SAML-intyg (authn-authz-patterns). 

För att åstadkomma API-anrop mellan System och API behöver ett vissa förutsättningar finnas och inledande steg genomföras, dessa beskrivs nedan. 

Steg 1 - Inloggning av användare i System

Användaren loggar in i System. Detta sker genom en legitimationstjänst (SAML-IDP) och resulterar i att användaren har en inloggningssession i System.

System består av två komponenter, dels en Webbapplikation (Quarkus) och dels en Keycloak-instans som agerar SAML-SP mot SAML-IDP. Webbapp använder Oauth authorization code-flow mot Keycloak. 

1. Användaren riktar sin browser mot URL för Webbapp. Webbapp konstaterar att användaren inte är inloggad (avsaknad av session-cookie).
2. Webbapp startar OAuth Authentication code flow mot Keycloak (delkomponent i System) som vidarebefodrar (via redirect, alltså via Användare, visas ej i diagram) användaren mot login-sida som också tillhandahålls av Keycloak.
3. Keycloak (i egenskap av SAML-SP) initierar SAML AuthnRequest mot SAML-IDP. Detta sker också genom redirect via Användare som är den som egentligen utför AuthnRequest mot IDP (syns ej i diagram). Slutresultatet är att Användare blir presenterad med inloggningssida hos SAML IDP.
4. Användare autentiserar sig (i denna implementation genom username/password snarare än e-legitimation, av praktiska skäl).
5. Efter autentisering returneras resultat i form av SAML Response till Keycloak/SP. Detta sker också via Användare (syns ej i diagram). Keycloak sparar tills vidare Response.
6. Keycloak slutför code flow genom att returnera Authz code och Webbapp använder denna mot token-endpoint (syns ej i diagram). Keycloak tillverkar och returnerar Access token till Webbapp och upprättar inloggningsession för användaren.

Steg 2 - Interaktion med lokal auktorisationstjänst och SSO mot IDP

Någon gång efter inloggning utför användaren något i System som föranleder att API-anrop mot API (i organisation B) behöver utföras. För att göra detta behöver först ett underlag genereras (som kan användas i steg 3 för att begära åtkomstintyg). Detta underlag (signerad JWT) skapas genom att System utför begäran mot lokal auktorisationstjänst (AS-A) som får en uppfattning om användaren genom ett SSO-flöde till SAML-IDP. 

Detaljerad beskrivning av interaktion med AS-A. 

1. Användare (inloggad) utför något i System som föranleder API-anrop till API i organisation B (trycker på en knapp/länk). Detta kan ske direkt efter inloggning eller efter att en viss tid passerat.
2. System startar OAuth Authentication code flow mot AS-A (en instans av Keycloak) och anger scope ("refapi") som gäller för kommande (i steg 3) API-anrop. AS-A som tar emot anropet vidarebefodrar (via redirect, alltså via Användare, visas ej i diagram) användaren mot login-sidan som också tillhandahålls av AS-A.
3. Keycloak (i egenskap av SAML-SP) initierar SAML AuthnRequest mot SAML-IDP. Detta sker också genom redirect via Användare som är den som egentligen utför AuthnRequest mot IDP (syns ej i diagram). Slutresultatet är att Användare blir presenterad med inloggningssida hos SAML IDP.
4. Användare autentiserar sig (i denna implementation genom username/password snarare än e-legitimation, av praktiska skäl.
5. Efter autentisering returneras resultat i form av SAML Response till AS-A (SP). Detta sker också via Användare (syns ej i diagram). Keycloak sparar tills vidare Response.
6. AS-A slutför code flow genom att returnera Authz code och Webbapp denna mot token-endpoint (syns ej i diagram). AS-A har nu en session avseende Användare. AS-A tillverkar och signerar JWT (user_JWT). Refresh_token tillverkas också vars giltighetstid speglar den tid
7. Keycloak returnerar user_JWT samt refresh_token till System. 

User_JWT har en giltighetstid som är relativt kort (xx minuter). Refresh_token har en giltighetstid som speglar hur länge förnyelse kan göras. Om förnyelse av user_JWT behöver göras medans giltighet för refreshtoken finns:

1. (Eventuellt) Användare utför åtgärd som kräver giltig user_JWT. Detta kan lika gärna vara något som initieras från internt i System. System upptäcker att giltighet user_JWT har passerats.
2. System initierar token fresh mot AS-A
3. AS-A tillverkar ny user_JWT och signerar denna
4. AS-A returnerar user_JWT

Om refresh inte är möjlig (giltighet passerad), återgår man till det initiala flödet med code flow mot AS-A för att ny autentisering av användaren ska kunna ske mot SAML IDP. 

Steg 3 - Begäran av åtkomstintyg från organisation B

När underlag finns kan åtkomstbegäran göras mot auktorisationstjänst (AS-B) i organisation B. AS-B använder metadata (som får via Resolver/Batch) för att verifiera underlag och klient som för förfrågan (System). Resultatet är ett åtkomstintyg (access token) som returneras till System.

Detaljerad beskrivning av flöde.

1. System har nu user-JWT från tidigare steg. System tillverkar en "client-JWT" enligt JWT Profile for Client Authentication. Både user-JWT och client-JWT anges i anrop till AS-B enligt RFC7523 samt scope "refapi".
2. AS-B tar emot förfrågan och verifierar
   1. client-JWT - att identitet (iss) går att slå upp som entitet i metadata
   2. client-JWT - att signatur går kan verifieras genom nyckelmaterial på entitet i metadata
   3. client-JWT - att entitet (iss) har tillitsmärke för "EFI-pilot-tjänsteleverantor" knuten till sig
   4. client-JWT - att klient finns med i whitelist för klienter
   5. user-JWT - att identitet (iss) går att slå upp som entitet i metadata
   6. user-JWT - att signatur kan verifieras genom nyckelmaterial på entitet i metadata
   7. user-JWT - att entitet (iss) har tillitsmärke för "EFI-pilot-identitet" och "EFI-pilot-behorighet" knuten till sig
3. AS-B tillverkar access token med sig själv som issuer, för över relevant information from user-JWT (samt eventuellt client-JWT) och krypterar denna. AS-B returnerar access token till System

Steg 4 - API-anrop mot API i organisation B

System har nu förutsättningar att utföra API-anrop mot API med åtkomstintyg som bärare av säkerhetsinformation. 

System kan nu utföra API-anrop till API och anger access token som Bearer token enligt RFCxxx. API verifierar att access token (genom signatur) är utställd (avkrypterar) av AS-B. API kontrollerar även scope. 

Beskrivning av komponenter i POC

Användare

Användare representerar själva användaren ("personen bakom tangentbordet") och den klient användaren använder (webbläsare). E-legitimation används inte i POC, utan ersätts av praktiska skäl av användare och passord. 

System

System representerar ett it-system i organisation A, som skulle kunna motsvaras av exempelvis ett journalsystem eller Pascal eller något liknande. Detta system har ett behov av att (föranlett av en aktivitet användaren utför i systemet) utföra ett API-anrop till API i organisation B. I POCen är detta en quarkus-applikation med följande funktionalitet:

• Agera webb-applikation 
• Inloggning av användare
• SAML-SP mot SAML-IDP (SAML-SP är en keycloak-instans som gör request mot SAML-IDP, quarkus-applikationen kör OAuth code-flow mot keycloak).
• Möjlighet för användare (via "knapptryck") initiera API-anrop mot API
• OAuth-klient enligt Authorization code-flow mot AS-A för att begära user-JWT
• Tillverka signerad "klient-JWT" för client authentication mot AS-B
• OAuth-klient mot AS-B för att göra åtkomstbegäran med user-JWT samt klient-autentisering med client-JWT
• API-klient mot API för att utföra API-anrop med access token som bärare av säkerhetsinformation.

SAML-IDP

Den legitimeringstjänst som användaren använder för att göra en inloggning i System. Denna legitimeringstjänst används även av AS-A (som SAML-SP) för att köra webSSO. SAML-IDPn är en instans av Keycloak konfigurerad att agera SAML-SP. Den har lokala användare konfigurerade och autentisering av Användare sker med username, password.

• Agera SAML-IDP för System
• Agera SAML-IDP för AS-A (SSO)
• Autentisering av användare med username+password
• Är beskriven i Sambi-trial metadata

AS-A

Auktorisationstjänst i organisation A. Används av System för att begära åtkomstunderlag (user-JWT) för att i nästa steg används som underlag mot AS-B för åtkomstbegäran. AS-A är en Keycloak-instans som tillhandahåller ett OAuth auth code-flow mot System. Detta initierar ett webSSO-flöde mot SAML-IDP för göra SAML AuthnRequest för att få ut en SAML Response för användaren i fråga. AS-A är i detta flöde SAML-SP mot SAML-IDP. AS-A kommer vid lyckad autentisering (antingen via SSO eller ny autentisering av användaren)

• Tillhandahålla OAuth Auth code-flow för System
• Agera SAML-SP mot göra AuthnRequest mot SAML-IDP
• Överföra relevant information i SAML Response (AttributeStatement, AuthnContextClassRef) till JWT, samt signera denna JWT med privat nyckel

AS-B

Autktorisationstjänst i organisation B. Tar emot OAuth åtkomstförfrågan (enligt RFC7523) och ställer ut access token. Quarkus-applikation med följande funktionalitet:

• Implementerar RFC7523 avseende authorization grant (user-JWT)
• Implementerar RFC7523 avseende client credentials (client-JWT)
• Whitelisting av klienter
• Kontrollerar utfärdare, signering samt tillitsmärken för user-JWT mot Ena metadata via resolver/batch.
• Kontrollerar utfärdare, signering samt tillitsmärken för client-JWT mot Ena metadata via resolver/batch.
• Tillverkar och signerar access token

API

API representerar det "skyddade API" som System vill anropa. Detta är en Java-applikation som implementerar ett enkelt REST-API. Det relevanta i POC är att den tar emot och kontrollerar accesstoken, alltså att denna är signerad/krypterad av AS-B. 

• REST-server
• Hantering/kontroll av accesstoken (Enligt RFC Bearer token)