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 som är utgiven under 2020. Observera att vi valt att inte ta med stämplar just nu i Ineras erbjudande eftersom det finns juridiska utmaningar för signaturer till juridisk person i och med brist på dessa e-legitimationer.
Det är lätt att stämplar blandas ihop med en automation så som t ex signering av ankomna handlingar i ett ärendehantering system 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 t ex all flödeslogik om det är mer ä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 som Inera tillhandahåller samt man underskrifttjänsten använder sig av Säkerhetstjänsters IdP, samt nya SITSH eID klienten på desktop eller Mobil.

2. Definitioner:

3. Förbereda er organisation på ett icke tekniskt 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

Men även de svenska lagar dessa underskrifter kommer tillämpas (lagrummet). 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.”

Verifikations punkter:

• 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 e-tjänst måste hålla reda på följande information under användarens session och vid tillfället då ni skapar anropet för signering mot stödtjänsten ska utnyttja dessa.

• Användarens HSA ID eller personnummer <Lägg till länk där detta attribut beskrivs på IdP sidan>
• Användarens medarbetar uppdrag som valdes vid inloggning <Lägg till länk där detta attribut beskrivs på IdP sidan>
• IdP för Signering som ni kommer att få som attribut av IdP:n vid inloggning <Lägg till länk där detta attribut beskrivs på IdP sidan>
• LOA nivå användaren loggade in med. <Lägg till länk där detta attribut beskrivs på IdP sidan>

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) även 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 göra 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 applikations drift i Linux eller Docker miljöer där man 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.

Metadata utbyte 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 livscykel hanteras, men stödjer i version 2011.xx och framåt att göra Rolling updates dvs 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, via 3e part eller tecknar avtal med CGI att få 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 och Metadata i Sweden connect och SAMBI skiljer sig ganska ordentligt åt så har Inera valt att göra en implementerings som ska underlätta för er som organisation där man som e-tjänst kommer enbart i början 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.

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 den nya Autentiserings klienten antingen installerad på sin PC eller i form av Mobilt SITHS och använda dessa vid inloggning <TBA Var kan man läsa mer om detta>.
• 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 Signerings meddelande (Sign message) som kommer visas i eID klienten vid signering. Läs. mer i 4.3
• 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.

Verifikations punkter:

• 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).

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 en e-tjänst som har stöd för att skapa en Sign request 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 ett antal beroenden till följande open source komponenter.

• Redis
• Tomcat
• Apache

Det är Redis som styr hur man göra sin design kring redundans och high availability. Redis stödjer ett flertal olika implementerings modeller 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.

5.1.2. Sign Message:

Sign Message är ett text meddelande som binder ihop användarens intention att göra en e-underskrift med vad de tidigare gick med att sända för e-underskrift i e-tjänsten. Denna funktion har funnits länge på e-ID:n så som BankID eller Freja eID och finns nu då även i nya SITHS eID klienterna och är ett SKALL krav att använda vid underskrift. Meddelandet kan vara upp till 16K Byte stor men vi rekommenderar er att hålla detta så kort som möjligt med samtidigt utformar det just som tanken är att binda ihop användarens websession i läsaren till den aktiva handlingen att aktivera sitt eID för underskrift.

5.1.3. Display name:

I Ineras Autentiserings klient så kommer det nu visas på samma sätt som då man använder BankID vem som begär en Autentisering och en Signering.

Det finns i Metadatan två skilda fält, en vem som är Juridiska organisationen bakom namnet detta representeras i Metadatan för en e-underskriftstjänst på fältet

<md:OrganizationName xml:lang="sv">Region Stockholm</md:OrganizationName>

En organisation kan ha en eller flera Displayname

<md:OrganizationDisplayName xml:lang="sv">Region Stockhoms underskriftstjänst</md:OrganizationDisplayName>

Men ju fler Display name ni väljer att ha ju mer konfiguration att hålla koll på i Stödtjänsten och Inera förvaltningen/CGI på både underskriftstjänsten och IdPn så håll Display name till ett minimum om det är möjligt.

5.2. Logisk separation av kunder.

Både Stödtjänsten och underskriftstjänsten är så kallade multitenanta tjänster där en miljö klarar av att logiskt separera många kunder. Samma sätt som dagens Inera IdP:n hanterar från en infrastruktur flera Service Providers (Sp).

6. Stödtjänsten:

Den är tänkt att finnas en eller flera 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 Skatteverket om jag är inne och gör moms deklaration och även om jag gör inkomstskattedeklaration. Dvs av Skatteverkets alla e-tjänster så använder de samma Display name. 

Men det går utmärkt att använda då samma stödtjänst för att även från samma städtjänst infrastruktur stödja andra organisationer så som Min myndighetspost och Kronofogdemyndigheten. 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.

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 bygge kanske 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å signerings uppdrag sända till sig, och då kanske får en notifiering via t ex min myndighetspost.

6.1. Stödtjänstens API

Efter man ingå avtal med Inera att avropa underskrifttjänsten så får ni tillgång till den kompletta API manualen från CGI för integration med Stödtjänsten.

Men det är viktigt att redan nu förstå att det finns fält i manualen som står som Optional som i Ineras implementering är SKALL krav.

Följande saker är ett SKALL krav på i Ineras implementering av CGI Signature Service och dess stödtjänst.

För funktionen PrepareSignature så gäller följande i Ineras Implementering:

Dessa nedan angivna parametrar är SKALL krav att de finns med i API anropet vid användning av CGI’s Stödtjänst och användning av Ineras SITHS eID klient och IdP.

• documents
• user
• authenticationServiceId
• consumerURL
• transactionId
• profile
• signMessage

6.2. Policy för att skapa sitt egna TransactionID

CGI underskriftstjänst och dess stödtjänst har en funktion att generera från sin ett eget TransactionID som sedan underlättar att använda vid felsökning.

Underskrifttjänsten i sig har inga personnummer i sina loggar, utan loggar enbart på TransactionID, och även eventuella felsidor som en användare kan råka ut för visar för användaren vilket TransactionID användaren har då de får ett fel som gör att användaren inte sänds vidare tillbaka till e-tjänsten. Detta för att hjälpa användaren att vis kontakt till Support kunna säga vilket TransactionID de har och tid de försökte göra underskriften.

I ineras implementering har vi valt att kravställa att e-tjänsten SKA skapa sitt eget TransactionID. Men för att få detta unikt så finns det krav på e-tjänsten då de genererar detta enligt följande Policy:

${customerId}-${applicationId}-${timestamp}-${uuid}

Exakt hur enligt nedan algorithm och förklaring:

Genom att varje e-tjänst genererar sin egen TransactionID för varje underskrift de vill få utförd så får vi spårmöjligheter att kunna felsöka t ex om en kund har flera olika e-tjänster, men bara en som genererar fel. Genom hur policyn hur man som e-tjänst ska generera sina TransactionID så underlättar detta sedan för Servicedesk och alla olika förvaltningar som kan bli inblandad i en felsökning på ett underskriftsärende.

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å.

underskriftstjänsten agerar då Service provider för underskrift för er som organisation, men i och med att Display name står i metadatan 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, Men är i SAML språk lika med separata entityID.

8. IdP:n

IdP:n för signering är logiskt skild jämfört med 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 Autentiserings metoderna ä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 endpoint Idp:er för signering Ineras IdP tillhandahåller.

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:

Det menar vi vilka attribut som kommer in i underskriftscertifikatet och som då baserar sig på de profiler som digitaliseringsmyndigheten definierat för inloggning.

• Natural Personal Identity with Civic Registration Number (Personnummer)
• Organizational Identity for Natural Persons
• Natural Person Identity with HSA-ID

Detta dokument förklarar inte hur en e-tjänst gör i sitt API anrop för att kunna anropa för att få respektive profil, och inte heller hur själva underskriftscertifikatet ser ut. Men det är viktigt att organisationen förstå i ett tidigt skede de möjligheter man har som e-tjänst och organisation samt vilken information en får från ett underskrivet dokument.

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
• 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*

* Om ni som kund köper hjälp av CGI som kommer de hjälpa er att ta fram denna ur CGI’s stödtjänst.

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

1. URL för metadata
2. URL:er för anrop
3. Vilka IdP:er vi satt upp mot Ineras Centrala IdP för er.

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).