Version | Datum | Författare | Kommentar |
---|---|---|---|
0.1 | Utkast | ||
0.2 | Första granskning | ||
0.3 |
| Mindre korrigeringar | |
0.9 |
| Brutit ut information. Omskrivningar. | |
0.91 |
| Förtydliganden |
Introduktion
Underskriftstjänsten 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. 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:
- 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.
För fullständiga exempel på SignRequest, se SAD - Underskriftstjänsten - Requests.
Profilnamn (AuthnProfile) | Signer | LOA | Requested Cert Attributes |
eln_ap_pnr_01 | < csig:Signer > < saml:Attribute Name = "http://sambi.se/attributes/1/personalIdentityNumber" > < saml:AttributeValue xmlns:xs = "http://www.w3.org/2001/XMLSchema" xmlns:xsi = "http://www.w3.org/2001/XMLSchema-instance" xsi:type = "xs:string" >199101192384</ saml:AttributeValue > </ saml:Attribute > </ csig:Signer > |
| <csig:RequestedCertAttributes> <csig:RequestedCertAttribute CertAttributeRef="2.5.4.4" FriendlyName="sn" Required="true"> <csig:SamlAttributeName>http://sambi.se/attributes/1/surname</csig:SamlAttributeName> </csig:RequestedCertAttribute> <csig:RequestedCertAttribute CertAttributeRef="2.5.4.42" FriendlyName="givenName" Required="true"> <csig:SamlAttributeName>http://sambi.se/attributes/1/givenName</csig:SamlAttributeName> </csig:RequestedCertAttribute> <csig:RequestedCertAttribute CertAttributeRef="2.5.4.3" FriendlyName="commonName" Required="true"> <csig:SamlAttributeName>urn:name</csig:SamlAttributeName> </csig:RequestedCertAttribute> <csig:RequestedCertAttribute CertAttributeRef="2.5.4.5" FriendlyName="serialNumber" Required="true"> <csig:SamlAttributeName>http://sambi.se/attributes/1/personalIdentityNumber</csig:SamlAttributeName> </csig:RequestedCertAttribute> <csig:RequestedCertAttribute CertAttributeRef="2.5.4.97" FriendlyName="organsiationid" Required="true"> <csig:SamlAttributeName>http://sambi.se/attributes/1/organizationIdentifier</csig:SamlAttributeName> </csig:RequestedCertAttribute> </csig:RequestedCertAttributes> |
digg_ap_hsaid_01 |
|
| <csig:RequestedCertAttributes> <csig:RequestedCertAttribute CertAttributeRef="2.5.4.42" FriendlyName="givenName" Required="true"> <csig:SamlAttributeName>http://sambi.se/attributes/1/givenName</csig:SamlAttributeName> </csig:RequestedCertAttribute> <csig:RequestedCertAttribute CertAttributeRef="2.5.4.4" FriendlyName="sn" Required="true"> <csig:SamlAttributeName>http://sambi.se/attributes/1/surname</csig:SamlAttributeName> </csig:RequestedCertAttribute> <csig:RequestedCertAttribute CertAttributeRef="2.5.4.5" FriendlyName="serialNumber" Required="true"> <csig:SamlAttributeName>http://sambi.se/attributes/1/personalIdentityNumber</csig:SamlAttributeName> </csig:RequestedCertAttribute> <csig:RequestedCertAttribute CertAttributeRef="2.5.4.3" FriendlyName="commonName" Required="true"> <csig:SamlAttributeName>urn:name</csig:SamlAttributeName> </csig:RequestedCertAttribute> </csig:RequestedCertAttributes> |
eln_ap_orgperson_01 | < csig:Signer > < saml:Attribute Name = "http://sambi.se/attributes/1/employeeHsaId" > < saml:AttributeValue xmlns:xs = "http://www.w3.org/2001/XMLSchema" xmlns:xsi = "http://www.w3.org/2001/XMLSchema-instance" xsi:type = "xs:string" >TST5565594230-12R7</ saml:AttributeValue > </ saml:Attribute > < saml:Attribute Name = "urn:orgAffiliation" > < saml:AttributeValue xmlns:xs = "http://www.w3.org/2001/XMLSchema" xmlns:xsi = "http://www.w3.org/2001/XMLSchema-instance" xsi:type = "xs:string" >TST5565594230-12R7@559085-8584</ saml:AttributeValue > </ saml:Attribute > </ csig:Signer > |
| <csig:RequestedCertAttributes> <csig:RequestedCertAttribute CertAttributeRef="2.5.4.4" FriendlyName="sn" Required="true"> <csig:SamlAttributeName>http://sambi.se/attributes/1/surname</csig:SamlAttributeName> </csig:RequestedCertAttribute> <csig:RequestedCertAttribute CertAttributeRef="2.5.4.42" FriendlyName="givenName" Required="true"> <csig:SamlAttributeName>http://sambi.se/attributes/1/givenName</csig:SamlAttributeName> </csig:RequestedCertAttribute> <csig:RequestedCertAttribute CertAttributeRef="2.5.4.3" FriendlyName="commonName" Required="true"> <csig:SamlAttributeName>urn:name</csig:SamlAttributeName> </csig:RequestedCertAttribute> <csig:RequestedCertAttribute CertAttributeRef="2.5.4.5" FriendlyName="serialNumber" Required="true"> <csig:SamlAttributeName Order="1">http://sambi.se/attributes/1/employeeHsaId</csig:SamlAttributeName> <csig:SamlAttributeName Order="0">urn:orgAffiliation</csig:SamlAttributeName> </csig:RequestedCertAttribute> <csig:RequestedCertAttribute CertAttributeRef="2.5.4.10" FriendlyName="organisation" Required="true"> <csig:SamlAttributeName>http://sambi.se/attributes/1/organizationName</csig:SamlAttributeName> </csig:RequestedCertAttribute> </csig:RequestedCertAttributes> |
eln_ap_pnr_01_orgid | <csig:Signer> <saml:Attribute Name="http://sambi.se/attributes/1/personalIdentityNumber"> <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">199101192384</saml:AttributeValue> </saml:Attribute> <saml:Attribute Name="http://sambi.se/attributes/1/organizationIdentifier"> <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">559085-8584</saml:AttributeValue> </saml:Attribute> </csig:Signer> |
| <csig:RequestedCertAttributes> <csig:RequestedCertAttribute CertAttributeRef="2.5.4.4" FriendlyName="sn" Required="true"> <csig:SamlAttributeName>http://sambi.se/attributes/1/surname</csig:SamlAttributeName> </csig:RequestedCertAttribute> <csig:RequestedCertAttribute CertAttributeRef="2.5.4.42" FriendlyName="givenName" Required="true"> <csig:SamlAttributeName>http://sambi.se/attributes/1/givenName</csig:SamlAttributeName> </csig:RequestedCertAttribute> <csig:RequestedCertAttribute CertAttributeRef="2.5.4.3" FriendlyName="commonName" Required="true"> <csig:SamlAttributeName>urn:name</csig:SamlAttributeName> </csig:RequestedCertAttribute> <csig:RequestedCertAttribute CertAttributeRef="2.5.4.5" FriendlyName="serialNumber" Required="true"> <csig:SamlAttributeName>http://sambi.se/attributes/1/personalIdentityNumber</csig:SamlAttributeName> </csig:RequestedCertAttribute> <csig:RequestedCertAttribute CertAttributeRef="2.5.4.97" FriendlyName="organsiationid" Required="true"> <csig:SamlAttributeName>http://sambi.se/attributes/1/organizationIdentifier</csig:SamlAttributeName> </csig:RequestedCertAttribute> </csig:RequestedCertAttributes> |
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}
${customerId}-${applicationId}-${timestamp}-${uuid} Where $ {customerId} and $ {applicationId} are normalized according to:
$ {customerId} is a 11 character name provided by CGI that represent the client name (same that exist in your Metadata and request URL). $ {timestamp} is the number of milliseconds since January 1, 1970, 00:00:00 GMT in hexadecimal format. $ {applicationId}, You can use the context section of the consumer URL (ex: java.net.URL: getPath (...)) Ex. if consumerURL is "https://app.company.com/app1/process/resp?id=123&ttl=1" then ApplicationID becomes: "app1processr" (12 characters) $ {uuid} is 128-bit unique ID according to RFC 4122. The length of a transactionID will be between 56 and 83 characters. |
---|
Anslutning
Beställning
Se Beställ Underskriftstjänsten för övergripande information om beställning.
Följande information inkluderas vid beställning av anslutning till Underskriftstjänsten:
- Organisationsnamn (Legal identity)
- "Display name" - namn per e-tjänst
- Önskade underskriftsprofiler
- 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.
Efter beställning levereras URL:er för hämtning av Underskriftstjänstens metadata samt URL:er för anrop till Underskriftstjänsten.
Metadata
Det finns inga av DIGG definierade krav på E-tjänstens metadata i anslutning till Underskriftstjänsten. Att generera och skicka in SAML2-metadata rekommenderas, men det viktigaste är att skicka in e-tjänstens publika certifikat för etablering av tillit. 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.
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.
LoA | CA |
---|---|
LoA 2 | Low DSS |
LoA 3 | Substantial DSS |
LoA 4 | High DSS |
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.
Miljö | URL-suffix | Kopplad IdP |
---|---|---|
Systemtest | *.st.signatureservice.se | idp.ineratest.org |
Acceptanstest | *.at.signatureservice.se | idp.ineraqa.org |
Produktion | *.signatureservice.se | idp.inera.se |
Logiska IdP:er per autentiseringsmetod
Autentiseringsmetod | Produktion | Acceptanstest | Systemtest |
---|---|---|---|
Ospecificerat (Användaren får välja) | https://idp.inera.se:443/saml/sign | https://idp.ineraqa.org:443/saml/sign | https://idp.ineratest.org:443/saml/sign |
SITHS eID på annan enhet | https://idp.inera.se:443/saml/sign/sithseid-other-device | https://idp.ineraqa.org:443/saml/sign/sithseid-other-device | https://idp.ineratest.org:443/saml/sign/sithseid-other-device |
SITHS eID på samma enhet | https://idp.inera.se:443/saml/sign/sithseid-same-device | https://idp.ineraqa.org:443/saml/sign/sithseid-same-device | https://idp.ineratest.org:443/saml/sign/sithseid-same-device |