1. Inledning:

Inera har av CGI upphandlat en central fristående underskriftstjänst i enlighet med Digitaliseringsmyndighetens (DIGG) standard Tekniskt ramverk för Sweden connect.

Detta dokument har som mål att vägleda er som kund till Inera i de steg ni som organisation måste ta för att dels förbereda er på en policy- och organisatorisk nivå, men även de tekniska förberedelserna och beställningsprocessen som krävs för att kunna ansluta sig.

Det totala ekosystemet för underskrift och identifiering baserar sig i grunden på Ineras referensarkitektur. Observera att stämplar just nu inte ingår i Ineras erbjudande eftersom det finns juridiska utmaningar med signaturer av juridisk person i och med brist på dessa e-legitimationer. Det är lätt att stämplar kombineras med automation så som t.ex. signering av ankomna handlingar i ett ärendehanteringssystem eller signering av loggar vilket tekniskt är en stämpelsignering, men som då inte passar in i en fristående underskriftstjänst baserat på dess mål att lösa signeringar av dokument som ligger under eIDAS artikel 26 eller artikel 36.

Ineras underskriftstjänst är en tjänst utan grafiskt gränssnitt. Det innebär att det som användaren ser måste byggas av er själva och via ett SOAP API göra integrationen med stödtjänsten för att kunna göra en underskrift.
Detta ställer krav på er som organisation att själva utforma det grafiska flödet, samt all flödeslogik om det t.ex. är fler än en person som ska skriva under samma dokument.
Detta dokument förutsätter att man som kund använder sig av en stödtjänst samt den underskriftstjänst som Inera tillhandahåller och som använder sig av Säkerhetstjänsters IdP, samt SITHS eID-klienten på Desktop eller Mobil.

Övergripande bild över infrastrukturen:

Det kan vara enklare att förstå flödet med denna bilden i stället för att sätta in utvecklarna hur underskriftsflödet går till.

Flödesdiagram:

2. Definitioner:

3. Förbereda er organisation på ett icketekniskt plan.

E-underskrifter kan vara ett mycket komplext område och vid implementering av e-underskrift i en e-tjänst så måste den egna organisationen också förstå sitt egna juridiska ansvar för slutprodukten (den underskrivna dokumentet). En fristående underskriftstjänst definierad av Digitaliseringsmyndigheten innebär ett delat ansvar för den slutgiltiga e-underskriften, vilket eget ansvar ni som organisation har beror på er egen miljö och uppsättning av den.

En bra start för organisationen är att börja läsa för att förstå är:

• Digitaliseringsmyndighetens Normativ Specifikation
  • Policy
  • Tjänstespecifikation

• e-SAM’s vägledning ”e-legitimation och e-underskrift 1.1”
• eIDAS förordningen

Med den utgångspunkten är det viktigt att också förstå relevanta svenska lagar. Notera att i det svenska lagrummet så tillämpas två nivåer, Elektronisk Underskrift eller Avancerad Elektronisk Underskrift. Dessa två nivåer har definition i eIDAS förordningen Artikel 3. Den fristående e-underskriftstjänsten som Inera levererar är en tjänst som når upp till nivån Avancerad Elektronisk Underskrift om alla ingående komponenter lever upp till kravet i eIDAS Artikel 26. Det är punkt C som e-tjänsten kommer ha ett delansvar samt även då IdP:n och Signerings meddelandet ”Sign message” som e-tjänsten skapar som är viktiga komponenter som ni som organisation själva måste se till att tillsammans med verksamhet och jurister komma fram till hur detta ska implementeras i era egna e-tjänster. Här finns det stöd hur man bör utforma sin e-tjänst från Kammarkollegiet (Vägledning avrop eID tjänster 2.0) där de ritat upp ett rekommenderat arbetsflöde i en tjänst som kan följas.

Viktigaste texten som definierar relationen och ansvar mellan e-tjänst och underskriftstjänst finns i Digg’s Tjänstespecifikation Kapitel 2.3
” Underskriftstjänsten tillämpar en rollfördelning där e-tjänsten tillhandahåller funktioner gentemot användaren för att visa och hantera dokument samt sända och ta emot signeringsmeddelanden till underskriftstjänsten. Underskriftstjänsten agerar i detta avseende som underleverantör till e-tjänsten. Underskriftstjänsten ställer ut underskriftscertifikat och tillhandahålla bland annat funktioner för spärrinformation gentemot förlitande part.”

Verifikationspunkter:

• Vi har utfört analys av vårat eget juridiska ansvar och den tänkta implementeringen?
• Vi har utfört analys hur vi ska lösa arkivering av e-underskrifter?

4. Förbereda er organisation på ett tekniskt plan

Ni som organisation måste utveckla er e-tjänst så den kan få tag på ett antal attribut som kommer behövas som indata vid signering.

Baserat på vilken typ av underskrift ni vill göra så behöver er e-tjänst känna till ett antal attribut om användaren. Om ni använder Ineras IdP så kan samtliga attribut som ni behöver erhållas vid Inloggning. Förenklat kan man säga att ni baserat på val kan behöva hålla reda på följande från att användaren loggat in till då den skall utföra e-signaturen.

• IdP för signering
• förnamn + efternamn
• personalIdentityNumber
• employeeHsaId
• organizationIdentifier
• Vilken LOA (tillitsnivå) som användaren måste ha (som lägst) för att underteckna dokumentet.
• Användarens medarbetaruppdragsval vid inloggning.

Er e-tjänst måste också vara utvecklad på ett sådant sätt att användarens inloggade websession bibehålls även efter den sänds till andra domännamn för att skapa underskriften och identifiering för signering som görs mot IdP:n. Användaren då den styrs tillbaka efter underskrift till e-tjänsten måste då komma in på den inloggade användarens websession. Säkerställ här testfall att användaren måste vara först inloggad två minuter eller mer innan den påbörjar en underskrift för att se att e-tjänsten efter underskrift inte tappat bort användarens websession.

Det API anrop som görs mot stödtjänsten är SOAP och för att komma igång så behöver ni utvecklarkunskap som kan skriva en applikation som utnyttjar detta API. Det finns i Stödtjänst manualen (som fås då kontrakt skrivs med Inera för underskriftstjänsten) samt ett Java kodexempel och ett C#-exempel i manualen. Titta även på flödes diagrammet i manualen för förstå de hopp som görs och hur man som utvecklare ska sända och ta emot de XHTML post som görs.

Stödtjänsten är en komponent som installeras lokalt hos er. Det är i grunden en Java applikation som har – baserat på arkitekturvalet – ett antal beroenden till andra komponenter som beskrivs i 5.1.1.

Inera rekommenderar att ni köper hjälp av CGI (ni får teckna egna avtal för detta) för att få stöd hur ni bör bygga arkitekturen kring stödtjänsten baserat på era krav på upptid/tillgänglighet med mera. Stödtjänsten som applikation konfigureras i konfigurationsfiler. Stödtjänsten saknas grafiskt admin-interface så all administration bör skötas av tekniker som är vana vid applikationsdrift i Linux- eller Docker-miljöer där en använder moderna verktyg så som t.ex. Bitbucket som håller koll på alla konfigurationsfiler och sedan använder verktyg som t.ex. Ansible för att trycka ut eventuella uppdateringar av konfigurationen.

Då man väl satt upp stödtjänstens konfiguration så är den ganska statisk förutom att man måste livscykelhantera de certifikat som används för att Signera och verifiera Sign request och Sign responce.

Metadatautbyte mellan den logiska instansen i underskrifttjänsten och er stödtjänst görs vid etablering/uppsättning av er logiska instans i underskrifttjänsten.

Denna metadata ska livscykelhanteras, men stödjer i version 2011.xx och framåt att göra Rolling updates dvs att ha två certifikat i metadatan för att minska driftpåverkan då certifikat byts.

Verifikationspunkter

• Vi har utvecklarkunskap eller avtal med 3e part som kan utveckla eller ändra vår e-tjänst så den tar hand om det grafiska som visas för användaren och integreras med en lokalt installerad stödtjänst.
• Vi har redan kunskap eller via 3e part får hjälp att sätta upp arkitektur och uppsättning/konfiguration av stödtjänsten.
• Vi har kunskap eller avtal med 3e part som sköter drift av vår lokala stödtjänst.

5. Vad är en fristående e-underskriftstjänst i enlighet med Tekniskt ramverk från Digitaliseringsmyndigheten?

Den korta versionen är att det är en e-underskriftsfunktion som är frikopplad från e-tjänsten och även e-legitimationsbäraren. Den långa versionen kan lättast läsas och inhämta förståelse genom att läsa Digitaliseringsmyndighetens Tjänstespecifikation för en fristående underskriftstjänst.

Eftersom hanteringen av SAML-autentisering och -Metadata i Sweden connect och SAMBI skiljer sig ganska ordentligt åt så har Inera valt att göra en implementation som ska underlätta för er som organisation där man som e-tjänst initialt enbart kommer kunna använda sig av den centrala Inera IdP:n vid underskrift. Det är fortfarande möjligt att använda sig av lokal Proxy IdP för inloggning, men för e-underskrift så kommer den centrala underskrifttjänsten att alltid använda den centrala Inera IdP:n.

5.1. Vilka steg behöver vi som organisation ta rent tekniskt för att ansluta till Ineras underskriftstjänst?

• Alla användare måste ha SITHS eID-klienter på Windows eller Mobiltelefon och använda dessa vid inloggning, se SITHS eID app (Autentiseringsklienter).
• Ha en e-tjänst som antingen redan har en egen inbyggd stödtjänst eller gör en integration mot CGI’s Stödtjänst mjukvara som kan tillhandahållas som just mjukvara till en organisation för egen drift. Läs mer om Stödtjänsten
• e-tjänsten måste vara kodad så den håller reda på användarens inloggade web-session även fast man går utanför dess domän så se upp med hur inloggningskakor hanteras i Chrome och andra webläsare. 
• En e-tjänst design som stödjer organisationens egna ansvar för underskrift. Läs mer i Kap 3 ovan om vägledning.
• Ett väl genomtänkt Signeringsmeddelande (Sign message) som kommer visas i eID klienten vid signering. Läs. mer i 6.1.2.
• En e-tjänst som kan hantera de nya attributen som pekar ut URL:er för signering baserad vilken inloggnings metod användaren använde vid inloggning till e-tjänsten <TBA URL till dessa attribut på IdP dokumentationen>.
• Eventuellt en funktion i er e-tjänst som grafiskt kan åskådliggöra en valideringsrapport som stödtjänsten kan returnera om man vill validera ett av tjänsten underskrivet dokument.
• Beslut vad för ”Display name” som ska visas i Autentiserings klienten för en integration.
• Beställ av Inera uppsättning av en e-underskriftstjänst i enlighet med beställnings formuläret.

Verifikationspunkter:

• Ansvarig för e-tjänsten/tjänsterna som ska implementera e-signering förstår vad de måste ändra eller uppfylla för att kunna implementera underskriftstjänsten?
• Organisationen har beslutat vilka Display Names som ska användas vid underskrift.
• Organisationen har beslutat Sign Message ska tillämpas för e-tjänst/e-tjänsterna som ska ha e-underskrift.
• Organisationen förstår hur de ska använda IdP vid inloggning och att det kommer framöver kunna få ett attribut som ger vägledning vilken IdP de ska använda för underskrift (som är en funktion som ska in i anropet till stödtjänsten).
• Organisationen ska skaffa ett funktionscertifikat enligt Policy kring certifikat för metadata för underskriftstjänster.

5.1.1. Stödtjänst Vad är det? Behöver vi den? Hur levereras den?

En stödtjänst är en mjukvara som e-tjänsten kan dra nytta av om de inte vill själva utveckla stöd för att skapa en Signrequest i enlighet med Digitaliseringsmyndighetens Teknisk ramverk för DSS. Mjukvaran ska installeras på kundens infrastruktur så nära e-tjänsten som möjligt.

CGI levererar till Inera en stödtjänst som mjukvara som är en Java applikation. Det går att kontakta CGI direkt för att teckna avtal för hjälp gällande paketering och konfiguration och design av denna mjukvara. Det går även att paketera stödtjänsten som en Dockerleverans om så önskas.

Det rekommenderas att köra stödtjänsten som en container (Docker), men vill man köra den som Java applikation så har den beroenden till följande open source-komponenter.

• Redis
• Tomcat
• Apache

Uppsättningen av Redis styrs av arkitekturella beslut kring redundans och tillgänglighet. Redis stödjer ett flertal olika implementeringsmodeller där CGI rekommenderar – baserat på last och andra krav – antingen Hot/Cold design eller ett kluster av tre aktiva Redis noder som servar 3 aktiva stödtjänster, och en Lastbalanserare som jämt last fördelar mellan alla tre noder.

Apache används för webfront till Tomcat och sköter också Autentiseringen mot stödtjänsten från de olika e-tjänster som ska få använda den. Vid tecknande av kontrakt med Inera så får man med djuplodande information om stödtjänsten.

Verifikationspunkter:

• Det finns kravställning på tillgänglighet för stödtjänsten och en huvudarkitekt som kan göra en design hos kund för e-tjänst och stödtjänst.
• Det finns kunskap att sätta upp en Redis som kommer vara nyckeln hur man gör designen kring tillgänglighet (En design på 3 noder som all är aktiva? En design med Hot/Cold?) Hur lastbalansering ska designas, samt även en webfront så som t ex Apache som skyddar Applikations servern och även tar hand om Autentiseringen mot stödtjänstens applikation med MTLS. Är saker som man som organisation som ska ha egen stödtjänst måste ha koll och kunskap på.
• Det finns kunskap i organisationen om applikationsdrift på Java applikation via en Tomcat applikations server, samt hur man skyddar en Tomcat bakom en webfront så som t ex Apache.

6. Stödtjänsten:

Den är tänkt att finnas en eller flera stödtjänster per organisation. Om ni tänker er hur det ser ut på andra myndigheter så står det t.ex. jag gör underskrift för Myndighet A om jag är inne och gör underskrift i deras Självbetjäningsportal för klagomål och även om jag sedan gör en ansökan om flytt till annan kommun. D.v.s. Myndighet A:s alla e-tjänster använder samma Display name eftersom de är samma juridiska instans. 

Men det går utmärkt att använda samma stödtjänst för att även från samma stödtjänst-infrastruktur stödja andra organisationer så som Myndighet B och och Myndighet C.  I stödtjänsten så baserar det sig på Profilhanteringen att respektive e-tjänst i sitt API anrop till stödtjänsten anropar sin profil för att visa korrekt display name.

Vill man här separera mer än på denna nivå så sätter man upp egna stödtjänster eller använder sig av en Signaturproxy som också är vanlig väg från ett arkitekturperspektiv på stora organisationer att använda sig av för att dels enklare kunna migrera mellan olika stödtjänster framöver, men även kanske bygga en koncerngemensam ”mina underskrifter”-portal som då kanske enkelt kan visas på ”mina sidor” om man har flöden mellan ett antal e-tjänster och har användare som kan få signeringsuppdrag skickade till sig, och då kanske får en notifiering via t.ex. Min myndighetspost eller motsvarande.

Stödtjänsten är en Javaapplikation som kräver en applikationsserver för att fungera, samt en Redis som databas. Applikationen kräver som lägst Tomcat 8

Följande versioner är testade

• Tomcat 8x på Linux
• Redis på Linux
• Apache på Linux

6.1. Göra en enkel POC

CGI har paketerat stödtjänsten i en Docker och preparerat den så den fungerar mot underskriftens systemtest miljöoch en Inera Demo-kund, med en koppling mot Inera Test IdP:n. Denna väg är ett enkelt sätt att få upp en lokal stödtjänst som första steg innan man bygger upp lokal infrastruktur i större skala för att börja "klämma och känna" utan behöva ta ett stort första steg. Läs mer om detta här.

7. Underskriftstjänsten

Denna infrastruktur sköter CGI, så det är inget ni som e-tjänst kommer behöva tänka så mycket på. CGI och Inera Säkerhetstjänsters förvaltning kommer extrahera bort all komplexitet som finns mellan underskriftstjänsten och Inera SÄK-förvaltningens IdP. 

Underskriftstjänsten agerar Service provider för underskrift för er som organisation, men i och med att Display name står i metadata så blir separationen per Display name som sätts upp.

Det innebär att underskriftstjänsten kommer behöva sätta upp lika många kunder som deras begrepp är,  i SAML lika med separata entityID.

Det finns givetvis en trust mellan stödtjänsten och den logiska instansen för er som kund i underskriftstjänsten. Det vill säga det kommer ske ett metadatautbyte mellan varje stödtjänst som tillhör en logisk instans på underskriftstjänsten. Troligtvis så kommer ni som kund inte vilja publicera stödtjänstens metadata (om ni inte väljer att låta e-tjänsten agera Proxy och hämta upp den från eran lokala stödtjänst). 

8. IdP:n

IdP:n för signering är logiskt skild från IdP:n för Identifiering och det eftersom Metadatan skiljer sig så mycket mellan SAMBI och Sweden connect samt att man i och med de nya Autentiseringsmetoderna ändå måste separera dessa som skilda IdP:er.

Det nya begreppet IdP för signering som kommer framöver användas för att beskriva relationen per EntityID på underskriftstjänsten och de tre olika logiska IdP:er för signering som Ineras IdP tillhandahåller.

Tillsvidare så kommer underskrift enbart anslutas till Ineras Säkerhetstjänster's IdP för att kunna komma igång i och med att kopplingarna mot IdP:n blir lätt väldigt komplext.

Förklarande bild:

Det ser kanske komplext ut med massa pilar från lagret underskriftstjänst och det är mycket konfiguration där, samt då på IdP delen. Men för en integrerande e-tjänst så blir bilden lite enklare.
Men i och med att man ska dels stödja flera olika inloggningsmetoder, samt då kanske även från samma stödtjänst fler e-tjänster, och även underskrifts attributs profiler (som ovan bild inte visar) så blir det många användarfall som man måste kunna hålla isär framförallt vid test.

9. Underskriftsprofiler:

Underskriftsprofiler indikerar vilka attribut som kommer in i underskriftscertifikatet och som då baserar sig på de Attribut set som digitaliseringsmyndigheten definierat för inloggning (https://github.com/swedenconnect/technical-framework/blob/master/04%20-%20Attribute%20Specification%20for%20the%20Swedish%20eID%20Framework.md#attribute-sets).

• Natural Personal Identity with Civic Registration Number (Personnummer)
• Organizational Identity for Natural Persons
• Natural Person Identity with HSA-ID
• Kombination av ELN-AP-Pnr-01 + ELN-AP-OrgPerson-01 (1 och 3 i listan)

För att undvika en teknisk komplex lösning så ska ni ställa frågan till organisationen. "Vilka uppgifter är absolut minimum för att skriva under dokumentet utifrån lag-, form- eller policykrav i verksamheten?"
Baserat på det svaret så kan det vara enklare att i e-tjänsten lägga till information i dokumentet innan man sänder dokumentet för underskrift t ex "Detta dokument är elektroniskt underskrivet av behörig läkare på Södersjukhuset" och så behövs kanske bara en underskriftsprofil i den tekniska lösningen implementeras. 
Texten i ett dokument om tillhörande organisation om man väljer att skapa den innan man sänder dokumentet för underskrift omslutes av själva elektroniska underskriften som fysiska personen gör. Så i verkligheten är det lättare i efterhand att titta i dokumentet om den informationen jämfört med att tekniskt behöva gräva fram det ur själva X509 certifikatet för att hitta den informationen. Dvs man kan i många fall kanske bara implementera profilen Natural Person Identity with HSA-ID om man anser att det blir komplext för e-tjänsten att hålla reda på en massa extra attribut som den måste begära vid inloggning för att kunna realisera profilen Organizational Identity for Natural Persons. 

Dessa profiler konfigureras i stödtjänstens groovy-fil (Signservice-support.groovy) som är uppdelad i dels  en common del och sedan en trustedAuthenticationServices del. För att konfigurera upp dessa inställningar så krävs det en hel del förståelse om hur SAML och olika Attribut namnges på urn:oid. För att underlätta så kommer i det stödtjänstpaketet som tillhandahålls av Inera medfölja en default-konfiguration för respektive miljö.

10. Information som behövs i beställningen från er som kund.

• Organisationsnamn (Legal identity):___________________________
• Displaynamn 1:_____________________
• Displaynamn 2:_____________________
• Displaynamn x:_____________________
• Vill kunna ha underskriftsprofil:
  • Natural Personal Identity with Civic Registration Number (Personnummer)
  • Organizational Identity for Natural Persons
  • Natural Person Identity with HSA-ID
  • Kombination av ELN-AP-Pnr-01 + ELN-AP-OrgPerson-01 (1 och 3 i listan)
• Metadata för e-tjänst/Stödtjänst: Ange en URL varifrån metadata kan hämtas.  Alternativt bifoga metadata som XML i ärendet eller ange en annan väg att föra över metadata.

11. Efter beställning får ni följande information

1. URL för metadata som er stödtjänst ska använda
2. URL:er för anrop som er stödtjänst ska använda
3. Vilka IdP:er vi satt upp mot Ineras Centrala IdP för er och som ni ska använda er av i er stödtjänst.

12. FAQ

Q: Behövs det separata stödtjänster per e-tjänst på en och samma organisation?

A: Nej, sätt upp en lokal stödtjänst som servrar fler e-tjänster, dock om de ska ha olika Displaynames så måste detta separeras i olika profiler i stödtjänsten, kontakta INERAS förvaltning för vidare information.

Q: Kan applikationen köras i container/Docker?

A: Ja, det är möjligt.

Q: Visst finns det certifikat i lösningen som måste underhållas?

A: Ja, på samma sätt som Metadata mellan SP och IdP så finns det certifikat som signerar meddelanden mellan Stödtjänsten och signeringstjänsten som måste livscykel hanteras.

Q: Finns det fler certifikat än det för Stödtjänsten?

A:Ja om man vill ha MTLS Autentisering på API:et mellan e-tjänst och stödtjänst så behövs det. Detta rekommenderats för annars så är det fritt fram för de som kan prata med stödtjänsten och dess API att initiera en signatur.

Q: Kommer man behöva någon brandväggsöppning från stödtjänsten till någon tjänst utanför vår organisation?

A: Ja, eftersom validerings funktionaliteten av signerade dokument finns i stödtjänsten så måste den kunna ladda ner CRL filer från CA:n som signerar dokumenten. Denna CDP (CRL Distribution point) är publicerad på internet från CGI’s sida och laddas ner via port 80. Ingen externt utgående trafik behövs.

Q: Vilka andra externa tjänster behöver Stödtjänsten?

A: Korrekt tid är ett krav, dvs ni måste se till att stödtjänstens servrar går korrekt och synkroniserar mot en säker tids-källa (NTP), och att servrarna inte drar sig, sedan är det kopplingen till en REDIS tjänst som antingen sätts upp med hjälp av CGI’s hjälp eller om ni redan har en sådan intern som kan användas.

Q: Hur pratar e-tjänsten med Stödtjänsten?

A: Ett SOAP API över MTLS.

Q: Vad är det vanligaste felet som kunderna har?

A: I och med att chrome/Google i Chrome 80 ändrade säkerheten med kakor så orsakar att e-tjänster tappar användarnas session från det de sänder requesten till den centrala miljön och sedan tar tillbaka den.
En signatur slutförs inte korrekt om e-tjänsten inte har koll på användarens inloggade session och sedan ger tillbaka den via API:et till stödtjänsten. 

Q: Vilka miljöer finns det av Signeringstjänsten?

• Systemtest (SIT) – kan också benämnas bara test, Integration test, dev integrations test osv Funktion är 100% lik produktion, dock ej kapaciteten och klustringen.
• Acceptanstest (AT) – Kan benämnas som stage eller QA eftersom denna är 100% lik produktion i uppbyggnad och kapacitet.
• Produktion (Prod)

Q: Går det att skapa organisationsstämplar?

A: Nej, enligt eIDAS så är en stämpel kopplad till Juridisk person och Sverige och Sweden connect saknas idag e-legitimations Scheman för eID:n utställda till en juridisk person. Tekniskt så skulle tjänsten kunna skapa en organisations stämpel om det fanns ett eID schema för juridisk person. Så tillsvidare så skapar tjänsten signaturer utställda till enbart fysiska personer, men eller utan organisations tillhörighet (lär mer om Underskriftsprofiler).