Introduktion

Underskriftstjänsten - Bas tillhandahåller funktioner för säker och standardiserad elektronisk underskrift i enlighet med Digitaliseringsmyndighetens (DIGGs) Tekniskt ramverk för Sweden connect.
Nuvarande version av Underskriftstjänsten stödjer undertecknande med SITHS e-legitimation, antingen med SITHS-kort i dator eller mobilt med Mobilt SITHS.

Denna guide har som syfte att stötta organisationer som avser att ansluta en eller flera e-tjänster till Underskriftstjänsten - Bas. Dokumentet innehåller bland annat vägledning i val av integrationsmönster, viktiga organisatoriska hänsynstaganden och förberedelser samt teknisk anslutningsinformation.

Se huvudsidan för Underskriftstjänsten för en översiktlig beskrivning av tjänsten och olika anslutningsmönster.

Teknisk översikt

Figuren nedan visar ett exempel på integration, med ingående system. Exemplet inkluderar en e-tjänst som använder Ineras IdP för inloggning samt Stödtjänsten för förberedelse av signeringsunderlag och validering av signatur.

Flödesdiagram med exempelflöde:

Förutsättningar och förberedelser

Juridik och informationssäkerhet

E-underskrifter är ett komplext område och vid införande av e-underskrift i en e-tjänst så måste den egna organisationen också förstå sitt juridiska ansvar för slutprodukten (det underskrivna dokumentet). En fristående underskriftstjänst så som definierad av Digitaliseringsmyndigheten innebär ett delat ansvar för den slutgiltiga e-underskriften.

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 tillhandahåller är en tjänst som når upp till nivån Avancerad Elektronisk Underskrift om alla ingående komponenter lever upp till kraven i eIDAS Artikel 26.

Dokumentet som skall undertecknas skall inte skickas till Underskriftstjänsten i sin helhet. E-tjänsten räknar istället ut en kontrollsumma av dokumentet (en hashsumma) som skickas till Underskriftstjänsten för signering, tillsammans med ett underskriftsmeddelande "Sign Message" som visas för användaren i autentiseringsklienten vid underskriftstillfället. Detta meddelande skapas av e-tjänsten, och det är viktigt att organisationens verksamhet och jurister tillsammans kommer fram till hur detta meddelande skall utformas i de egna e-tjänsterna. Efter utförd signering så måste e-tjänsten kombinera resultatet med ursprungsdokumentet till en färdig undertecknad elektronisk handling. Kammarkollegiet har i Vägledning avrop eID tjänster 2.0 ritat upp ett rekommenderat arbetsflöde i en tjänst som kan följas.

Det viktigaste stycket 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.”

Teknik

Alla användare måste ha SITHS e-legitimation och SITHS eID-klienter (appar) på Windows eller Mobiltelefon.

E-tjänsten måste anpassas/utvecklas för att kunna ansluta till Underskriftstjänsten.

Antingen måste e-tjänsten själv hålla funktionalitet för att skapa SignRequest, ta emot och kombinera signaturen med orginaldokumentet till en undertecknad elektronisk handling samt validera signaturer, eller så delegeras dessa funktioner till en lokalt driftsatt instans av Stödtjänsten.

Underskriftstjänsten har inga användarflöden eller komponenter för användargränssnitt, annat än felsidor som i undantagsfall visas för användaren (i de fall Underskriftstjänsten av någon anledning inte kan returnera ett felmeddelande till e-tjänsten). Alla användarflöden för att förbereda och presentera dokument för underskrift måste byggas i e-tjänsten. Själva autentiseringen och presentation av underskriftsmeddelandet ("Sign Message") sköts av IdP-tjänsten och eID-klienterna.

Underskriftstjänsten utfärdar vid varje underskrift ett underskriftscertifikat utifrån begärd underskriftsprofil. Vilken profil som begärs bör styras av verksamhetens behov. Vissa underskriftsprofiler - de som innehåller organisationsinformation - kan kräva att användaren väljer vårdmedarbetaruppdrag i IdP. För att undvika detta användarval så kan e-tjänsten välja en underskriftsprofil utan organisationsinformation och istället inkludera organisationsinformationen i själva dokumentet som skall signeras.

I anslutningen av e-tjänst till Underskriftstjänsten anges ett "Display Name" som motsvarar ett namn på e-tjänsten. Detta namn kommer visas för användarna vid elektronisk underskrift i eID-klienten och bör därför väljas med omsorg. T.ex. "Jag skriver under hos Acme AB dokumenttjänst." Om e-tjänsten använder Ineras IdP för inloggning så kan det vara pedagogiskt att använda samma "Display Name" för inloggning och underskrift.

Vid anslutningen utbyts metadata mellan e-tjänsten och Underskriftstjänsten. Detta metadata skall livscykelhanteras. E-tjänstens förvaltning måste ha rutiner för att läsa in uppdaterat metadata från Underskriftstjänsten, samt distribuera uppdaterat metadata för e-tjänsten, t.ex. vid certifikatsbyte.

Metadatautbyte mellan Underskriftstjänsten och IdP sköts internt av Inera.

Checklista

• Är organisationens juridiska ansvar analyserat, utifrån den tänkta lösningen?
• Finns färdig utformning av underskriftsmeddelanden ("Sign Message") som skall visas för användarna?
• Är anslutningsmönster beslutat?
  • Skall e-tjänsten ansvara för skapandet av underskriftsbegäran samt hantering och validering av resultatet eller delegera detta till en Stödtjänst?
  • Skall e-tjänsten använda Ineras IdP för inloggning?
• Finns beslut om namn på e-tjänsten i form av "Display Name" som skall visas för användarna?
• Är behovet av användarattribut i underskriftscertifikatet analyserat?
  • Vilken/vilka underskriftsprofiler skall e-tjänsten använda sig av?
• Är det klart hur användardialoger och arbetsflöden i e-tjänsten skall se ut vid förberedelse av dokument för elektronisk underskrift?
• Är det beslutat hur arkivering av underskrivna dokument skall gå till?
• Är SITHS eID-klienter distribuerade till användarna, eller finns det en plan för distribution?
• Finns kompetens och resurser att implementera eventuella ändringar i e-tjänsten?
• Finns kompetens och resurser att installera, konfigurera och drifta en eventuell Stödtjänst lokalt?

Underskriftsbegäran

Kommunikation mellan e-tjänst och Underskriftstjänsten sker enligt version 1.5 av DIGG:s Implementation Profile for using OASIS DSS in Central Signing Services.

 SignRequest

Skapandet av underskriftsbegäran - SignRequest - kan skötas av e-tjänsten själv, alternativt delegeras till Stödtjänsten eller annan motsvarande support-funktion.

SignRequestExtension

Versionen av SignRequestExtension-protokollet är 1.4 vilket MÅSTE anges i SignRequest.

<csig:SignRequestExtension xmlns:csig="http://id.elegnamnden.se/csig/1.1/dss-ext/ns" xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion" xmlns:xenc="http://www.w3.org/2001/04/xmlenc#" Version="1.4">

IdentityProvider (IdP)

Fältet IdentityProvider anger vilken IdP som skall utföra autentiseringen.

Ineras IdP tillhandahåller tre logiskt separerade instanser för e-legitimering vid elektronisk underskrift, motsvarande olika autentiseringsmetoder. Detta möjliggör för e-tjänsten att specificera i anropet vilken autentiseringsmetod som skall användas, för att undvika att användaren ställs inför ett metodval. De tre logiska IdP:erna tillhandahåller autentiseringsmetoderna:

• Autentisering med SITHS eID på samma enhet
• Autentisering med SITHS eID på annan enhet
• Ospecificerat (Användaren får välja metod själv hos IdP)

E-tjänster som använder Ineras IdP för inloggning kan från IdP begära attributet urn:identityProviderForSign som pekar ut vilken logisk IdP för underskrift som korresponderar mot samma autentiseringsmetod som användes vid inloggning. Tanken är att användaren antagligen vill använda samma metod vid inloggning och vid underskrift, och genom att direkt ange motsvarande IdP i SignRequest så kan e-tjänsten bespara användaren den interaktionen hos IdP.

Se Underskriftstjänstens Miljöer nedan för specifika entityID för logiska IdP:er per miljö.

Underskriftsprofil

De underskriftsprofiler som Underskriftstjänsten stödjer är definierade enligt Profilhantering. Vald underskriftsprofil styr vilka attribut som inkluderas i underskriftscertifikatet och därmed även vilka attribut Underskriftstjänsten begär från IdP.

Begärd underskriftsprofil anges i fältet AuthnProfile.

<csig:AuthnProfile>...</csig:AuthnProfile>

Signer

Fältet Signer används för att identifiera vilken användare som skall utföra underskriften. Attributen som inkluderas är styrande vid autentisering av användaren för underskrift, och måste exakt matcha de attribut som returneras från IdP efter autentiseringen. Se exempel nedan.

För e-tjänster som använder sig av Ineras IdP för inloggning är det enkelt att populera attributen i Signer utifrån användarattribut i inloggningsbiljetten från IdP. 

RequestedCertAttributes

Fältet RequestedCertAttributes anger attribut som skall ingå i underskriftscertifikatet. Sätts till samma attribut som är definierade i den begärda underskriftsprofilen. Se exempel nedan.

Tillitsnivå (LoA)

Accepterade tillitsnivåer för den e-legitimering som utförs i samband med den elektroniska underskriften anges som AuthnContextClassRef-fält. Möjliga fältvärden är de som levereras från IdP, se Tillitsnivå (LoA) för information om hur IdP tolkar LoA.

Möjliga värden är:

<saml:AuthnContextClassRef>http://id.sambi.se/loa/loa2</saml:AuthnContextClassRef>
<saml:AuthnContextClassRef>http://id.sambi.se/loa/loa3</saml:AuthnContextClassRef>

RequestID

Fältet RequestID SKALL genereras enligt TransactionID (RelayState) nedan.

Exempel

Nedanstående tabell visar exempel på hur ovanstående fält i SignRequest kan se ut, för varje underskriftsprofil.

Fullständiga exempel på SignRequest och övriga meddelanden i flödet tillgängliggörs efter beställning.

TransactionID (RelayState)

Underskriftstjänsten använder ett transaktionsid, TransactionID, för att kunna följa ett underskriftsflöde i loggarna. TransactionID SKALL genereras av e-tjänsten och skickas dels som RequestID i SignRequest, och dels som RelayState i HTTP POST-anropet till Underskriftstjänsten.

Detta id inkluderas i alla efterföljande protokollmeddelanden i underskriftsflödet, och används i loggar för att identifiera det specifika underskriftsförsöket. TransactionID visas också för användarna i eventuella felsidor hos Underskriftstjänsten. Att ha detta id tillgängligt vid supportärenden underlättar felsökning avsevärt, särskilt om felsökningen löper över flera involverade tjänster.

E-tjänster som använder Stödtjänsten för generering av SignRequest skickar samma TransactionID i anropet till Stödtjänsten.

E-tjänsten SKALL generera TransactionID enligt följande policy:

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

Anslutning

Beställning

Se Ineras hemsida för övergripande information om beställning.

Följande information inkluderas vid den tekniska anslutningen till Underskriftstjänsten i en förstudie:

• Organisationsnamn (Legal identity)
• "Display name" - namn per e-tjänst
• Önskade underskriftsprofiler (samt i förekommande fall, stödtjänstsprofil(-er), se Profilhantering)
  
  • eln_ap_pnr_01
  • digg_ap_hsaid_01
  • eln_ap_orgperson_01
  • eln_ap_pnr_01_orgid
• 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.
• Testresultat vid produktionsanslutning

Efter beställning tillgängliggörs:

• URL:er för hämtning av Underskriftstjänstens metadata
• URL:er för anrop till Underskriftstjänsten
• Fullständig dokumentation för Stödjtänsten
• Nerladdning av Stödtjänsten för installation

Metadata

Vid anslutning behöver e-tjänstens SAML2-metadata förmedlas, antingen via en URL där metadata kan hämtas, eller direkt bifogat i anslutningsbegäran. Metadata behöver innehålla e-tjänstens publika cert.

För de organisationer som använder sig av Stödtjänsten så genererar Stödtjänsten upp SAML2-metadata utifrån tjänstens konfiguration.

Anslutande systems signeringscertifikat (det certifikat som bifogas i t.ex. SAML metadata) för produktionsmiljö kan ställas ut av valfri utfärdare men nyckelhanteringen förutsätts följa de instruktioner och rekommendationer som anges i "Instruktion, nyckelhantering för lagrade krypterade data".

Inera rekommenderar välrenommerade och robusta utfärdare med följsamhet mot principerna i ISO-27002 (wikipedia, riktlinjer till ISO-27001). Väljs "SITHS e-id Function CA v1" (utfärdare, SITHS e-id Root CA v2) kan mer information ges på SITHS på inera.se. Se SITHS CA repository för de utfärdande certifikaten. Den anslutande e-tjänsten ansvarar för att hantera sina privata nycklar på ett säkert sätt. Osäker hantering av e-tjänstens privata nyckelmaterial kan leda till att e-tjänstens åtkomst till Underskriftstjänsten missbrukas .

CA-struktur för underskriftscertifikat

Underskriftstjänsten har en struktur för certifikatutfärdare (CA) som är uppdelad i tre separata certifikatkedjor (CA-kedjor) enligt nedan:

Vilken CA-kedja som den digitala signaturen skapas från bestäms utifrån vilken tillitsnivå som IdP anger för den e-legitimation (användarcertifikat) som används vid autentiseringen.

Tillitsnivå hög (LoA 4) används i dagsläget inte i SITHS.

URL:er för nerladdning av CA-kedjor

Certifikatkedjorna finns tillgängliga enligt nedan. De kan behövas för att t.ex. lägga till lokal "trust" i t.ex Adobe reader:

Produktion: https://crl.signatureservice.se/rootCA/

QA/AT: https://crl.at.signatureservice.se/rootCA/

SIT/Test: https://crl.st.signatureservice.se/rootCA/

Underskriftstjänstens Miljöer

Underskriftstjänsten är driftsatt i tre publika miljöer kopplade mot motsvarande IdP-miljöer.

Logiska IdP:er per autentiseringsmetod