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 code flow mot Keycloak som vidarebefodrar (redirect) användaren mot Keycloak authorization-endpoint.
3. Keycloak (i egenskap av SAML-SP) initierar SAML AuthnRequest mot SAML-IDP. Detta resulterar i att användare blir vidarebefodrad (redirect) mot SAML-IDP.
4. (Eventuellt) Om behov av autentisering av användare behövs så presenteras inmatning av kreditiv för användare.
5. Efter autentisering returneras resultat i form av SAML Response till Keycloak. Keycloak sparar tills vidare Response.
6. Keycloak returnerar Authz Code till Webbapp
7. Webbapp använder Code mot Token-endpoint i Keycloak. Keycloak överför eventuell information till access token. 
8. Keycloak returnerar Access token och användaren är inloggad i Webbapp. Webbapp upprättar session-cookie i webbläsare

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 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 code flow mot AS-A (en instans av Keycloak) och anger scope ("refapi") som gäller för kommande API-anrop. Detta vidarebefodrar (redirect) användaren mot Keycloak authorization-endpoint.
3. Keycloak (i egenskap av SAML-SP / webSSO) initierar SAML AuthnRequest mot SAML-IDP. Detta resulterar i att användare blir vidarebefodrad (redirect) mot SAML-IDP.
4. (Eventuellt) Om behov av autentisering av användare behövs så presenteras inmatning av kreditiv för användare.
5. Efter autentisering returneras resultat i form av SAML Response till Keycloak. Keycloak sparar tills vidare Response.
6. Keycloak returnerar Authz Code till System
7. System använder Code mot Token-endpoint i Keycloak. Keycloak överför information från Response (AttributeStatement, LOA) och anger andra relevanta claims (sub, aud, iss, scope etc.) till signerad JWT ("user-JWT") och signerar denna med nyckel vars publika del finns i metadata. 
8. Keycloak returnerar user-JWT till System

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)