Introduksjon

Funksjonell dokumentasjon for Posten signering.

Signeringsoppdrag

Et signeringsoppdrag (ev. signeringsjobb) er en jobb som inneholder et dokument som skal signeres, og kan adresseres til en eller flere undertegnere som skal signere. Tjenesten tilbyr to ulike typer signeringsoppdrag hvor måten de signeres på er den vesentlige forskjellen.

Synkrone signeringsoppdrag

Et synkront oppdrag signeres når undertegner allerede er pålogget i avsenders system. Disse oppdragene passer for avsendere som ønsker at sluttbrukerne skal oppleve signeringsprosessen som en integrert del av deres nettsted.

Flyten ser typisk slik ut:

  1. Undertegner er innlogget i avsenders tjeneste, og utfører en prosess der, f.eks. utfylling av et skjema.
  2. Avsender oppretter et oppdrag i signeringstjenesten maskinelt
  3. Undertegner blir sendt til signeringstjenesten og gjennomfører signeringssermonien
  4. Undertegner blir sendt tilbake til avsenders tjeneste
  5. Avsender laster ned signatur og tilbyr en kopi av det signerte dokumentet til undertegner

Asynkrone signeringsoppdrag

Et asynkront oppdrag signeres i Postens signeringsportal.

Flyten ser typisk slik ut:

  1. Avsender oppretter et oppdrag maskinelt eller i avsenderportalen
  2. Signeringstjenesten varsler undertegner på e-post (og ev. SMS om spesifiert ved opprettelse
  3. Undertegner logger inn på signeringsportalen og gjennomfører signeringssermonien
  4. Undertegner laster ned signert kopi av dokumentet
  5. Undertegner logger ut av signeringsportalen
  6. Avsender laster ned signatur

Opprette signeringsoppdrag

Ved opprettelse av signeringsoppdrag kan følgende felter angis:

  synkrone oppdrag asynkrone oppdrag  
Dokument Obligatorisk Obligatorisk  
Undertegner(e) Obligatorisk Obligatorisk se undertegners kontaktinfo
Tittel Obligatorisk Obligatorisk  
Signaturtype Valgfritt Valgfritt se signaturtype
Sikkerhetsnivå Valgfritt Valgfritt se sikkerhetsnivå
Melding til mottaker(e) Valgfritt Valgfritt  
Undertegners identifikator Valgfritt Valgfritt se undertegners identifikator
Aktiveringstidspunkt Ikke overstyrbar1 Valgfritt  
Levetid Ikke overstyrbar2 Valgfritt  
E-postadresse Ikke relevant Obligatorisk se varsling
Mobilnummer Ikke relevant Valgfritt se varsling
Rekkefølge Ikke relevant Valgfritt se kjedet signatur

Begrensninger

Antall undertegnere

Tjenesten tillater maksimalt 10 undertegnere pr. oppdrag.

Hastighet

Tjenesten tillater maksimalt 10 API-kall i sekundet per organisasjonsnummer. Hvis en avsender overskrider denne grensen vil API-et returnere HTTP 429 Too Many Requests, og avsenderen vil bli blokkert i 30 sekunder.

Dokumentformater

Tjenesten støtter dokumenter av typen ren tekst (.txt) og PDF (.pdf). Både PDF og PDF/A aksepteres av tjenesten. Det signerte dokumentet vil være av samme type som originaldokumentet. Et originaldokument som er PDF/A gir et signert PAdES-dokument som er PDF/A, og et originaldokument som er PDF versjon 1.1 – 1.7 gir et signert PAdES-dokument som er PDF versjon 1.7. For PDF/A vil tjenesten alltid produsere signerte PAdES-dokumenter av typen PDF/A-3b, uavhengig av PDF/A-versjon og -konformitetsnivå (conformance level) på originaldokumentet.

For arkivering av signerte dokumenter anbefaler vi å bruke originaldokumenter av typen PDF/A. Dette er et krav hvis det signerte dokumentet skal avleveres til Riksarkivet.

Filen kan maksimalt være 3 MB (3 145 728 bytes) stor. PDF-versjoner som støttes er PDF 1.1-1.7.

I PAdES vil dokumentet alltid presenteres i A4- og portrett-format. For best resultat anbefales det at det innsendte dokumentet også har dette formatet.

Passordbeskyttede dokumenter (begrenset lese- og/eller skrive-tilgang) er ikke støttet av tjenesten.

Aktiveringstidspunkt

Angir tidspunkt for når signeringsoppdraget skal tilgjengeliggjøres for undertegner(e). Dersom aktiveringstidspunktet er i fortiden, blir oppdraget tilgjengelig øyeblikkelig etter opprettelse.

For kjedete signeringsoppdrag gjelder aktiveringstidspunktet for første gruppe.

1 Synkrone signeringsoppdrag blir alltid aktivert øyeblikkelig etter opprettelse

Standardverdi: øyeblikkelig etter opprettelse

Oppdragets levetid

Angir hvor lenge etter aktivering et signeringsoppdrag er tilgjengelig for undertegner før det utløper. Kan maksimalt være 90 dager etter aktivering.

For kjedete signeringsoppdrag gjelder levetiden for hver gruppe, slik at alle undertegnere får like mye tid på seg til å signere.

2 Synkrone signeringsoppdrag har alltid 30 dagers levetid for å unngå at et dokument blir signert uhensiktsmessig lenge etter opprettelsen av oppdraget. Eventuell frist fra avsenders perspektiv må kommuniseres og håndteres i avsenders tjenester.

Standardverdi: 30 dager etter aktivering

Kansellere signeringsoppdrag

Kansellering av signeringsoppdrag er bare relevant for signeringsoppdrag som signeres i signeringsportalen, dvs. asynkrone oppdrag.

Et signeringsoppdrag kan på et hvilket som helst tidspunkt kanselleres av avsender, så lenge ikke oppdraget allerede er fullført. Kansellerte oppdrag blir utilgjengeliggjort for undertegnere som enda ikke har signert.

Undertegners identifikator og kontaktinfo

Undertegner kan adresseres/identifiseres på ulike vis, basert på om avsender benytter synkron eller asynkron flyt og hvilken informasjon avsender har om undertegner.

Adressering med fødselsnummer

Dette gir en sikker identifisering, da kun riktig person har mulighet til å åpne og signere dokumentet.

For asynkrone signeringsoppdrag: Undertegner må først identifisere seg ved å logge inn i signeringsportalen med ID-porten, BankID, BankID på mobil eller Buypass. Deretter kan hun åpne og signere dokumentet med f.eks. BankID. BankID vil derfor bli brukt 2 ganger.

For synkrone signeringsoppdrag: Avsender er ansvarlig for å sende riktig person til riktig lenke i signeringstjenesten (returneres fra tjenesten ved opprettelse av oppdraget). Undertegner kan deretter åpne og signere dokumentet med f.eks. BankID.

Signerte dokumenter vil inneholde navn på undertegner og hvilken elektronisk ID som ble brukt. Man kan for øvrig velge hvilken identifikator man ønsker i signerte dokumenter.

Adressering med kontaktinfo for asynkrone oppdrag

Kun tilgjengelig for private avsendere.

Denne signeringstypen krever ingen innlogging, og du trenger ikke vite undertegners fødselsnummer. I stedet sender du inn e-postadressen og/eller mobilnummeret som skal motta varsel om signeringen. Se regler for varselutsending for en oversikt over hvilke varsler som sendes til hvilke tidspunkter.

Du som avsender er ansvarlig for at riktig person åpner og signerer dokumentet.

Undertegner får en lenke til dokumentet og fyller inn en sikkerhetskode som er oppgitt i varselet. Undertegneren kan deretter åpne og signere dokumentet direkte med BankID, BankID på mobil eller Buypass.

Selve signaturen er like sikker som hvis man logger inn før signering.

Signaturen vil inneholde navn og fødselsdato på undertegner, samt hvilken elektronisk ID som ble brukt.

Adressering med egenvalgt identifikator for synkrone oppdrag

For synkrone oppdrag er det mulig å benytte en egenvalgt identifikator, f.eks. kundenummer, for å adresse undertegner. Dette er et velegnet alternativ om:

  • Avsender ikke kjenner undertegners fødselsnummer, eller
  • Det er mindre vesentlig nøyaktig hvem som signerer, så lenge det f.eks. er en representant for en spesifikk virksomhet.

Når fødselsnummer ikke benyttes til adressering vil man ikke kunne sikre at personen oppdraget adresseres til faktisk er den som undertegner. En del forretningsprosesser krever ikke denne konfidensialitetssikringen, eller sikker adressering og autentisering av undertegner, og da kan det være praktisk å slippe å kjenne til undertegners fødselsnummer i forkant av signeringen.

Behovet for konfidensialitet kan også være mindre for dokumenter som ikke inneholder personopplysninger.

Når fødselsnummer ikke brukes under adressering vil det heller ikke kunne inkluderes i signerte dokumenter.

Merk: I prosesser der det er spesielt viktig å sikre hele prosessen rundt signering og å ha sterk autensitet knyttet til det signerte dokumentet (f.eks. i de tilfeller der man krever avansert e-signatur) vil det normalt ikke være anbefalt å la være å adressere undertegner med fødselsnummer.

Signaturtype

Autentisert og avansert e-signatur

Avsender velger om den vil innhente autentisert eller avansert signatur fra undertegner. I esignaturloven er dette omtalt som hhv. elektronisk signatur og avansert elektronisk signatur.

Om ingen signaturtype angis ved opprettelse av oppdraget, vil følgende type innhentes som standard:

  • Autentisert e-signatur for offentlige virksomheter
  • Avansert e-signatur for private virksomheter

Sikkerhetsnivå

Avsender må angi hvilket sikkerhetsnivå signeringsoppdraget skal ha. Dette kan være 3 eller 4, og begrenser hvilke elektroniske ID-er undertegner kan bruke for å signere dokumentet, se tabellen under. Sikkerhetsnivået begrenser også hvilke innloggingsmetoder undertegner kan bruke for å se signeringsoppdraget og dets detaljer, samt begynne selve signeringen.

Om ingen signaturtype angis ved opprettelse av oppdraget, vil nivå 4 settes som standard.

Begrenset visning av oppdrag

Er bruker innlogget på et lavere nivå enn det som kreves for å se detaljene om signeringsoppdraget, vil hun få en begrenset visning av oppdraget, der kun en ikke-sensitiv tittel er synlig. For å se alle detaljer om oppdraget vil hun bli bedt om å logge inn på nytt på et høyere sikkerhetsnivå. Brukeren vil alltid bli veiledet til den innloggingsmetoden som kreves for oppdraget som skal signeres, slik at brukeropplevelsen blir så god som mulig.

Oversikt over elektroniske ID-er

Autentisert e-signatur

For offentlige virksomheter vil alle e-IDer tilbys gjennom ID-porten

e-ID Gjelder Nivå
Min ID Offentlige virksomheter 3
BankID Offentlige virksomheter 4
Buypass Offentlige virksomheter 4
Commfides Offentlige virksomheter 4
BankID på mobil Offentlige virksomheter 4

Avansert e-signatur

e-ID Gjelder Nivå
BankID Offentlige og private virksomheter 4
Buypass Offentlige og private virksomheter 4

Multiundertegner

Et multiundertegneroppdrag er et signeringsoppdrag (synkront eller asynkront) som er adressert til minst 2 undertegnere. Selv om det for undertegnerne oppleves likt om det er én eller flere undertegnere, er det noen forskjeller for avsenderen.

Terminerende handlinger

Hvis det gjøres en terminerende handling på et signeringsoppdrag vil oppdraget avsluttes og ev. undertegnere som fortsatt ikke har signert vil miste muligheten til dette. Avsenderen blir varslet om at signeringsoppdraget er avsluttet med en status som beskriver hvilken terminerende handling som ble gjort.

De ulike handlingene som avslutter et signeringsoppdrag er:

  1. En undertegner avviser oppdraget
  2. Avsender kansellerer oppdraget
  3. Oppdragets utløpstidspunkt blir passert

NB! For offentlige virksomheter vil oppdraget avsluttes før det blir aktivert for noen undertegnere hvis minst én mottaker ikke eksisterer i eller er reservert fra elektronisk kommunikasjon i Kontakt- og reservasjonsregisteret.

Eksempel

Avsender oppretter et oppdrag med tre undertegnere. Undertegner 1 signerer, undertegner 2 avviser. Dersom undertegner 3 logger inn i signeringsportalen etter at undertegner 2 har avvist, vil hun ikke se signeringsoppdraget og vil ikke ha mulighet til å signere.

Kjedet signatur

Kjedet signatur er bare relevant for signeringsoppdrag som signeres i signeringsportalen, dvs. asynkrone oppdrag.

Avsender kan spesifisere rekkefølgen et signeringsoppdrag skal bli tilgjengeliggjort for undertegnerne. Når alle undertegnerne i en gruppe1 har signert vil oppdraget bli tilgjengelig for neste gruppe undertegnere.

Terminerende handlinger for kjedete signeringsoppdrag

En terminerende handling på et kjedet signeringsoppdrag vil føre til at oppdraget avsluttes for alle undertegnere som enda ikke har signert, inkludert de undertegnere som ikke har fått oppdraget tilgjengeliggjort enda.

Hvis en undertegner i første gruppe avviser oppdraget eller signeringsfristen går ut, vil oppdraget aldri tilgjengeliggjøres for undertegnerne i de senere gruppene og avsender blir varslet om at oppdraget er fullført med en feilende status.

1 En gruppe undertegnere er alle som har samme order i APIet og kan bestå av én eller flere undertegnere som skal signere i parallell.

Signerte dokumenter

Tjenesten tilgjengeliggjør signaturer i to formater når et dokument har blitt signert – PAdES og XAdES. Det vil maksimalt finnes én PAdES for et signeringsoppdrag, mens det vil finnes én XAdES per undertegner som har signert.

PAdES er tilgjengelig når minst én undertegner har signert og vil inneholde de signaturene som er gjennomført for oppdraget i nedlastningsøyeblikket. XAdES er tilgjengelig fra det øyeblikket undertegner har signert dokumentet.

Alle dokumenter kan lastes ned i en periode etter at signeringsoppdraget er fullført. Levetiden er avhengig av om langtidslagring er aktivert for avsenderen.

Undertegners identifikator

Under opprettelse av signeringsoppdrag kan avsender velge hvordan undertegnerne skal identifiseres i de signerte dokumentene. Dette kan for eksempel være nyttig hvis dokumentet skal signeres av flere enn én person og du ikke ønsker å utlevere fødselsnumrene til undertegnerne. Avsender velger å inkludere én av følgende identifikatorer i signerte dokumenter:

  1. Navn og fødselsnummer (standardverdi)
  2. Navn og fødselsdato
  3. Navn

Følgende tabell viser hvilke valg som er gyldige for hhv. offentlige og private avsendervirksomheter når det innhentes avanserte eller autentiserte signaturer:

  Privat Offentlig
Avansert 1, 2 1
Autentisert N/A 1, 3

Merk: Alternativ 1 kan kun benyttes om fødselsnummer er brukt for å identifiseres undertegner ved opprettelse av oppdraget. Se for øvrig avsnittet om undertegners identifikator og kontaktinfo

Hvis du utelater fødselsnummer i de signerte dokumentene kan vi ikke påvise identiteten med 100 % sikkerhet.1 Vi kan likevel i de aller fleste tilfeller oppnå tilstrekkelig beviskraft, på bakgrunn av konteksten signeringen skjer i.

Sannsynligheten er for eksempel svært liten for at 2 personer med navn Kari Olsen signerer en lærekontrakt med Lærlingebedrift AS på eksakt samme tidspunkt. I tillegg vil tekniske spor (audit trail), og andre eksterne forhold som kunderelasjon eller opplysninger i dokumentet også støtte opp under identiteten til den som har signert.

1 Det signerte dokumentet inneholder en anonymisert identifikator som identifiserer undertegneren med 100 % sikkerhet hos leverandøren av e-ID, for eksempel hos BankID. Dette krever oppslag hos leverandøren av e-ID og støttes kun ved avansert e-signatur.

Varsling

Signeringstjenesten tilbyr varsel og oppdrag til signering på SMS og e-post.

Regler for utsending

Reglene for utsending av varsler avhenger av signeringsfristen:

Signeringsfrist e-post e-post SMS
0-24 timer Ved aktivering - Ved aktivering
2-3 dager Ved aktivering 1 dag før frist 1 dag før frist
4-5 dager Ved aktivering 2 dager før frist 1 dag før frist
6-9 dager Ved aktivering 3 dager før frist 2 dager før frist
10 dager + Ved aktivering 5 dager før frist 2 dager før frist

Dersom det ikke finnes en e-postadresse for en undertegner vil det sendes SMS istedet for e-post ved aktivering.

SMS sendes ikke mellom 22 og 08, med mindre oppdraget opprettes på natten og fristen er så kort at det er nødvendig med umiddelbar utsending.

Kontaktinformasjon

Kontaktinformasjon for varsling kan angis på to måter:

  • Dersom tjenesteeier spesifiserer varslingsinformasjon ved opprettelse av oppdraget vil denne brukes. Overstyrt varslingsinformasjon får prioritet over Kontakt- og reservasjonsregisteret. NB: Offentlige virksomheter kan kun overstyre varslingsinformasjonen dersom undertegner mottar oppdraget i kraft av en rolle knyttet til sitt arbeid.
  • Dersom varslingsinformasjon ikke spesifiseres, vil tjenesten hente varslingsinfo fra Kontakt- og reservasjonsregisteret. Dette er kun tilgjengelig for offentlige virksomheter.

Krav til kontaktinformasjon:

  • Alle undertegnere må ha minst ha én av e-postadresse og mobilnummer.
  • Sending av SMS er frivillig og kan bestilles av tjenesteeieren.
  • Dersom en undertegner har mobilnummer og ikke e-postadresse vil det alltid bli sendt SMS.
  • Tjenesten støtter kun norske mobilnumre. Oppdrag med overstyrt kontaktinformasjon med utenlandsk mobilnummer vil bli avvist, mens utenlandske mobilnumre fra Kontakt- og reservasjonsregisteret vil bli ignorert.

Bruk av Kontakt- og reservasjonsregisteret

Signeringstjenesten gjør oppslag mot Kontakt- og reservasjonsregisteret ved opprettelse av oppdrag for alle offentlige virksomheter for undertegnere uten overstyrt kontaktinformasjon. Hvis undertegnere er reservert mot digital kommunikasjon vil oppdraget bli avvist og påfølgende uthenting av status for oppdraget vil gi en feil med informasjon om hvilke undertegnere som er reservert. Undertegnere med overstyrt kontaktinformasjon bli ikke sjekket for reservasjon.

  • Ved utsending av senere varsler (enten utsatt aktivering på grunn av kjedet signatur eller påminnelser) blir det gjort et nytt oppslag mot registeret for å hente ut den sist oppdaterte kontaktinformasjonen.
  • Dersom Oppslagstjenesten for Kontakt- og reservasjonsregisteret er utilgjengelig ved utsending av påminnelser vil resultatet fra oppslaget ved opprettelse av oppdraget bli brukt.
  • Reservasjon ved utsatte førstegangsvarsler: I scenariet der tjenesteeier har satt en kjedet rekkefølge på undertegnerne, og førstegangsvarsel skal sendes til en undertegner som i perioden mellom oppdraget ble opprettet og førstegangsvarsel skal sendes har reservert seg mot elektronisk kommunikasjon, så vil hele oppdraget feile.
  • Reservasjon ved påminnelser: Hvis sluttbrukeren har reservert seg etter at oppdraget ble opprettet, men oppdraget allerede er aktivert, vil det ikke bli sendt påminnelser (e-post/SMS), men oppdraget vil heller ikke feile før signeringsfristen eventuelt løper ut.

Langtidslagring

Posten signering tilbyr en tilleggstjeneste for langtidslagring av originaldokument og signerte dokumenter. Tjenesten må aktiveres før en avsender kan ta den i bruk.

For avsendere med langtidslagring aktivert, lagres alle dokumenter i minst 50 år. Dersom langtidslagring ikke er aktivert kan dokumentene bli utilgjengeliggjort etter 40 dager.

Avsendere som bruker avsenderportalen kan aksessere langtidslagrede dokumenter via webgrensesnittet. Dokumentene er tilgjengelig via REST-grensesnittet for avsendere som integrerer mot tjenesten maskinelt, som beskrevet i teknisk dokumentasjon.

Signeringstjenesten langtidslagrer kun XAdES. Når man henter PAdES genereres denne “on demand” basert på XAdES.

Sletting av dokumenter

Avsendere kan slette arkiverte dokumenter hvis de ønsker å fjerne dem fra arkivet. Avsendere som bruker avsenderportalen kan slette dokumenter via webgrensesnittet. Dokumentene kan slettes via REST-grensesnittet for avsendere som integrerer mot tjenesten maskinelt, som beskrevet i teknisk dokumentasjon.

Begrensninger:

  • Alle undertegnere må ha signert før dokumentene kan slettes. Dokumenter som ikke blir signert av samtlige undertegnere vil slettes automatisk etter 40 dager, og kan ikke slettes manuelt av avsender.
  • Dokumenter kan tidligst slettes 24 timer etter signeringtidspunkt.
  • Dokumenter som skal sendes til undertegners digitale postkasse kan ikke slettes før de har blitt sendt dit. Dersom undertegner ikke har digital postkasse ventes det inntil 7 dager før dokumentene kan slettes.

Integrere med API

Teknisk dokumentasjon

Teknisk dokumentasjon og annen støtte for å utvikle integrasjon med Posten signering er tilgjengelig på GitHub: github.com/digipost/signature-api-specification

Klientbiblioteker

Det finnes klientbiblioteker som vil forenkle utvikling av integrasjonen:

Ordliste

avsender — avsenderen av et signeringsoppdrag. Dette er parten mottakere ser som avsender av dokumenter som skal signeres.

undertegner — en mottaker av et dokument som skal signeres. Et signeringsoppdrag kan adresseres til flere undertegnere.

signeringsoppdrag (alt: signeringsjobb) — en jobb inneholder et dokument som skal signeres, og kan adresseres til en eller flere undertegnere som skal signere.

synkront signeringsoppdrag — signeringsoppdrag som signeres mens undertegner allerede er pålogget i et eksternt system. Selve signeringen blir dermed en del av en eksisterende flyt i avsenders system ved at undertegner blir videresendt til en egen tjeneste hos Posten signering. Man utfører signeringen, og blir til slutt redirectet tilbake til avsenders applikasjon.

asynkront signeringsoppdrag — signeringsoppdrag som signeres i signeringsportalen.

signeringsportal — nettsted for undertegnere. Her logger man seg inn og signerer eller avviser mottatte dokumenter.

avsenderportal — nettsted for avsendere hvor man kan sende ut dokumenter som skal signeres, samt administrere signeringsoppdrag.

PAdES — PDF-fil som inneholder alle ferdige signaturer, samt originaldokumentet. En PAdES kan åpnes i en vanlig PDF-leser, og lesere som støtter det vil i tillegg vise hvilke undertegnere som har undertegnet dokumentet.

XAdES — XML-representasjon av et dokument med digital signatur fra én undertegner.