Transportinfrastruktur

Denne dokumentasjonen beskriver transportinfrastruktur for digital post til innbyggere, samt hvordan en kan ta denne i bruk og integrere egne avsendersystemer.

Bakgrunn

Den proprietære transportinfrastrukturen for Digital Postkasse til innbyggere er erstattet med en standard-infrastruktur for meldingsutvekling i det offentlige, dvs 4-hjørnes-modell med CEF eDelivery/PEPPOL. Følgende aktører inngår:

• Hjørne 1: Avsender (og evt. avsender sin leverandør/databehandler)
• Hjørne 2: Avsenders aksesspunkt-leverandør
• Hjørne 3: Postkasse- og utskriftsleverandørs aksesspunktleverandør
• Hjørne 4: Postkasse- og utskriftsleverandør

Vi ser altså at den sentraliserte Meldingsformidleren er erstattet av et distribuert nettverk av aksesspunkt-leverandører.

Av sikkerhetsgrunner er derfor:

• meldingsformatet i DPI endret noe

samt noen av Meldingsformidlers oppgaver flyttet til tjenesteleverandører i hjørne 4:

• validere ende-til-ende integritet på sendte meldinger
• validere at avsender har tillatelse til å sende digital post
• dersom en melding er sendt av en databehandler, validere at databehandler har lov til å opptre på vegne av avsender
• sørge for at kvitteringer blir sendt tilbake til rett system uavhengig av om avsender bruker databehandler eller ikke

Det er etableret en ny transport-protokoll mellom hjørne 1 og hjørne 2. I tradisjonell PEPPOL-tenking er dette noe som markedsaktørene selv skal ta fram - dvs i prinsippet er dette opp til aksesspunktleverandørene selv å bestemme. Siden Digdir ønsket å gjøre en anskaffelse av aksesspunktleverandørtjenester for formidling av digital post, som de fleste avsendere kommer til å benytte, ble det mest hensiktismessig at Digdir kravstilte en protokoll som skal brukes av denne leverandøren. Det hindrer ikke andre aktører å implementere andre, egne protokoller.

Protokoll mellom hjørne 2 og 3 er bestemt av PEPPOL, og heter AS4. Protokoll mellom hjørne 3 og tjenesteleverandører i hjørne 4 avtales bilateralt mellom disse aktørene i samarbeid med Digdir.

Revidert meldingsformat- og transportformat i DPI

Motivasjon bak revidert meldings- og transportformat i DPI:

• Minst mulig endringer på format, da både avsender-systemer og postkasse-leverandører støttet dette.
• Måtte ta høyde for at en aksesspunktleverandør i PEPPOL kan bli kompromittert av en angriper som vil forsøke å injisere falske meldinger
• Fjerne ebMS 3.0 som transportformat mellom Databehandler og Meldingsformidler, da erfaring viser at denne er relativt komplisert å ta i bruk, og vil være lite attraktiv for potensielle aksesspunktleverandører å måtte implementere, og heller innføre en moderne og sikker lettvektsprotokoll som REST.
• Gjenbrukbart format også for andre meldinger i eMeldingsinfrastrukturen
• Utviklervenlig format med høyt rammeverk- og produktstøtte, for å gjøre det så lett som mulig å sende meldinger fra hjørne 1.

Revidert meldings- og transportformat i DPI innebar derfor:

1. Dokumentpakken, dvs ASiC-pakken beholdes uendret
2. Forretningsmeldingene beholdes også stort sett uendret, men:
   • Formatet skal endres fra XML til JSON for å bli mer tilpasset vanlig REST-bruk
   • json-schema følge dagens xsd så langt det lar seg gjøre. * Strukturen er fremdeles en SBD, dvs. består av
   • Først en SBDH, nå JSON-ifisert.
   • Så selve forretningsmeldinga (eks. digitalpostmelding), også JSON-ifisert * Maskinporten-token må inkluderes i forretningsmeldingen slik at PK-leverandør kan motta dette som bevis på tillatelse til å sende post * Hele SBD’en må signeres på meldingsnivå for å sikre ende-til-ende integritet, og den må defor da bli en JWT.

Grensesnittsdefinisjoner

REST-api mellom Avsender og Hjørne 2

Aksesspunkt-leverandør i hjørne 2 skal tilby et enkelt REST-endepunkt som Avsender bruker for å sende post og hente kvitteringer.

REST-grensesnittet skal sikres med Bearer tokens fra Maskinporten, se: https://docs.digdir.no/maskinporten_auth_server-to-server-oauth2.html. Informasjon om godkjente avsendere og deres eventuelle databehandlere blir kodet inn i dette tokenet.

Aksesspunkt-leverandør skal tilby 2 endepunkt:

Sende post

Post sendes som multipart/form-data og inneholder både forretningsmelding og dokumentpakke. Det oppfordres til å bruke strømming for å støtte sending av store filer.

POST /messages/out
Authorization: Bearer <maskinporten_token>

Body:
<multipart/form-data med forretningsmelding (JWT) og dokumentpakke (kryptert ASICE)>

Hente kvitteringer og marker som lest

URL på formen

GET /messages/in
GET /messages/in/{messageId}
POST /messages/in/{messageId}/read

Se status på en melding

Gir en statuskode på hva som har skjedd med den sendte meldingen.

GET /messages/out/{messageId}/statuses

API-definisjoner

Se DPI skjema

PEPPOL (hjørne 2-> 3)

Se DPI skjema

Se Peppol eDelivery network specifications

Hjørne 3 -> Tjenesteleverandører i hjørne 4 (postkasse- og utskriftsleverandører)

Dette avtales bilateralt mellom de to partene i samarbeid med Digdir.

Forutsetninger:

System-oppsett

Digdir oppretter maskinporten-scopet digitalpostinnbygger:send. Tilgang til dette scopet betyr at Avsender har inngått bruksvilkår for Digital Postkasse til Innbygger. Digdir settes som eier av Maskinporten-scopet, som betyr at det er Digdir som administrerer hvem som får tilgang. Faktura for konsumentene (= alle avsendere) går til Digdir selv og faktureres ikke.

Ved bruk av Altinn Autorisasjon til delegering må det opprettes et “delegationScheme” i Altinn som muliggjør at Behandlingsansvarlig kan delegere til Databehandler. Digdir blir eier av delegationSchemet, og Digdir vil motta faktura for bruk av Altinn.

Nødvendige prosesser og dokumenttyper registreres for mottaker i ELMA av mottakers Peppol-aksesspunkt.

Se prosesser og dokumenttyper

Oppsett av postkasse- og utskriftsleverandør

Tjenesteleverandørene i hjørne 4 registreres i ELMA som mottakere av aktuelle processer og dokumenttyper. Må utføres av Hjørne 3.

Oppsett av ny Avsender

Digdir gir Avsender tilgang i Maskinporten til oauth2-scopet digitalpostinnbygger:send når bruksvilkår for Digital Postkasse er inngått.

Alt 1: Avsender som skal sette opp sitt eget system, må få tilgang til Samarbeidsportalen (i Prod) og registere en maskinporten-integrasjon med det aktuelle scopet. Fagsystemet/oauth2-klieten må konfigureres med den genererte client_id og Avsender sitt virksomhetssertifikat. Avsender som bruker integrasjonspunktet trenger ikke å gjennomføre dette, men må følge de retningslinjer som gjelder for å få satt opp et integrasjonspunkt.

Alt 2: Avsender som benytter systemleverandør/databehandler må i stedet logge inn i Altinn for å delegere tilgangen til å sende DPI videre til systemleverandør. Systemleverandør må få tilgang til Samarbeidsportalen og lage Maskinporten-integrasjon på samme måte som selvstendige avsendere. Merk at systemleverandør autentiserer seg mot Maskinporten med sitt eget virksomhetsertifikat, og trenger ikke å ha sertifikatet til Avsender.

Avsender (evt. systemleverandør) inngår så en avtale med en aksesspunkt-leverandør. Fagsystemet blir konfigureret og integerert mot aksesspunktleverandør.

Avsender må bli satt opp i ELMA som mottaker av DPI-kvitteringsmeldinger. Dette gjør aksesspunktleverandør.

PK-leverandør mottar beskjed manuelt fra Digdir om at det er etablert en ny Avsender.

Meldingsflyt

(dersom du ikke ser et sekvensdiagram under her, må du åpne dokumentet i noe som kan vise mermaid inline grafikk)

1: Avsender henter token fra maskinporten

Fagsystem lager en JWT grant som etterspør digitalpostinnbygger:send-scopet, signerer denne ( se https://docs.digdir.no/maskinporten_protocol_jwtgrant.html, sender dette til Maskinporten og får et access_token i retur.

Ved utstedelse av token vil Maskinporten kontrollere:

• at Avsender har lov til å bruka DPI.
• Viss Avsender har databehandler, sjekkar Maskinporten mot Altinn Autorisasjon at aktuell autentisert Databehandlar har fått lov til å opptre på vegne av Avsender for sending av DPI.

Døme på payload i JWT access token

{
  "iss": "https://maskinporten.no",
  "scope": "digitalpostinnbygger:send",
  "aud": "https://api.aksesspunktleverandør.no/"
  "consumer": {
      "Authority": "iso6523-actorid-upis",
      "ID": "0192:991825827"      // Alltid Avsenders orgno
  }
  "supplier": {
      "Authority": "iso6523-actorid-upis",
      "ID": "0192:999888777"      // Eventuell Databehandler.
  }
  "iat": <timestamp>
  "exp": <iat-verdi + 30 sec>
}

Dersom avsender er sin egen Databehandler så mangler tokenet supplier-claimet.

2: Avsender sender post-melding

Avsender slår opp i KRR og finner hvilken PK-leverandør som innbygger benytter - og vet derigjennom om det skal sendes digital eller fysisk post.

Avsender kan nå konstruere korrekt forretningsmelding (DigitalPostMelding) etter dagens regler, men med følgende tillegg/endringer:

• Format skal være JSON, og følge skjema-definisjonen her på https://docs.digdir.no/schemas/dpi/innbyggerpost_dpi_digital_1_0.schema.json
• Strukturen er fremdeles en SBD, dvs. består av
  • Først en SBDH, nå JSON-ifisert.
  • Så selve forretningsmeldingen (eks. digitalpostmelding), også JSON-ifisert
• Token mottatt fra Maskinporten inkluderes i et felt maskinporten_token under digitalpost
• Hele SBD’en må signeres på meldingsnivå for å sikre ende-til-ende integritet, og den må defor da bli en JWT.
  • Databehandler må signere forretningsmeldingen med samme sertifikat som benyttes til å signere Dokumentpakke.

Regler for hvilke organisasjonsnummer som skal på ulike steder i meldingsstrukturen videreføres, se eksempelet om Bunadsrådet og Acos i eksisterende dokumentasjon.

Eksempel på forretningsmeldinger:

• Se https://docs.digdir.no/resources/begrep/sikkerDigitalPost/nyinf/eksempler/innbyggerpost_dpi_digital_1_0.json for et eksempel med digital post. receiver er her PK-leverandør sitt orgno.
• Se https://docs.digdir.no/resources/begrep/sikkerDigitalPost/nyinf/eksempler/innbyggerpost_dpi_utskrift_1_0.json for eksempel med fysisk post. receiver er her org.no til printtjeneste-leverandør.

Avsender lager nå til slutt en unik meldingsid, og sender så posten :

POST /messages/out
Host: api.aksesspunktleveradandør.no
Content-Type: application/jwt
Authorization: Bearer <maskinporten_token>

Body:
<forretningsmelding (JWT) og dokumentpakke (kryptert ASICE)>

3: Aksesspunkt-leverandør mottek melding

Aksesspunktleverandør (APL) må gjennomføre en teknisk validering av Maskinporten-tokenet ihht Oauth-standarden (ustedt av Maskinporten, gyldig signatur, ikke utløpt).

• Utgått token medfører 401-respons
• Gyldig token men som mangler “digitalpostinnbygger:send”-scope eller avsender med manglende avtale med APL -> 403 repons

Aksesspunktleverandør må videre validere at:

• consumer-claimet i token stemmer med Avsender i forretningsmelding.
• aud-claimet i token stemmer med eget API-endepunkt
• maskinporten_token i forretningsmelding er identisk med det som ble brukt som Bearer token det aktuelle API-kallet
• meldingsid ikke er forsøkt brukt tidligere.

Aksesspunktleverandør lagrer meldingsid, konversasjonsid og tilhørende avsender/databehandler og avsenderidentifikator, slik at kvitteringsmeldinger og feilmeldinger relatert til meldingen kan håndteres, og fagsystemet kan etterspørre status.

4: Aksesspunkt-leverandør i hjørne 2 sender meldingen videre til hjørne 3

APL mapper documentIdentification/type i SBDH-delen av forretningmelding til riktig processid ihht PEPPOL APL slår opp i ELMA på processid og PK-leverandørs orgno (=receiver i SBDH-delen av forretningsmeldinga) og får hvem som er hjørne 3 for den aktuelle PK-leverandøren.

APL kan nå konstrurere en PEPPOL-melding. Dvs:

• Pakke forretningmelding og dokumentpakke om til avtalt payload-format *
• Lage PEPPOL-konvolutt (“ytre” SBDH)
  • SBDH Receiever settes lik pk-leverandør orgno (?)
  • SBDH processid settes lik processid
  • SBDH Sender settes lik (TODO: Avsender eller Databehandler)?

Eksempel: Transport-format i PEPPOL ser ut som her: https://github.com/joergenb/dpi_transport/blob/main/Samples/DIGITALPOST_DPI_1_0_Minimal_Sample.xml

5: Hjørne 3 mottar meldingen, og sender videre til hjørne 4

Leverandør i C3 og mottaker i hjørne 4 avtaler protokoll seg i mellom i samarbeid med Digdir.

De står fritt til å bruke PEPPOL payload-formatet direkte, eller dele opp forretningsmelding/dokumentpakke slik det er gjort over Avsender->Hjørne 2-grensesnittet, eller andre hensiktsmessige protokoller. Det må dog være enkelt og entydig for PK-leverandør å koble dokumentpakke og forretningsmelding sammen.

Partene bestemmer selv hvilken sikringsmekanisme de vil ha (feks egen oauth2 autorisasjonsserver, bruke 2-vegs tls, eller noe annet). Vi anbefaler ikke at de bruker maskinporten-tokenet, da dette kan ha utløpt undervegs.

6: Hjørne 4 mottar meldingen og putter i postkassen til innnbygger eller skriver ut og sender meldingen

Ved mottak av melding, må postkasse-leverandør/utskriftsleverandør validere ende-til-ende integritet, dvs:

a: at DigitalPostMelding er signert av Avsender(eller Databehandler) og inneholder en digest for tilhørende dokumentpakke b: at dokumentpakken er signert av Avsender(eller Databehandler) c: regne ut digest av dokumentpakken og kontrollere at utregnet digest stemmer med påstått verdi i forretningsmeldingen

d: validere at Avsender i forretningsmeldinger stemmer med consumer-claimet i maskinporten_token i forretningsmeldingen. e: validere at virksomhetssertifikatet som er brukt til å signere både Dokumentpakke og DigitalPostMelding stemmer med autorisert avsender (dvs maskinporten-token)

• lik suppliers orgno, dersom dette claimet finnes i maskinporten_token
• lik consumers orgno ellers

Kvitteringer

PK-leverandør må kunne asynkront sende kvittering tilbake i C3 -> C2 -> C1. (dvs C3 må tilby et API eller mekanisme der PK-leverandør kan overføre kvitteringer, og dette må ta høyde for at slik kvitteringslevering skal kunne skje asynkront ifht levering av digitalpostmelding C3->C4.)

Feltet conversation_id kobler sammen en kvittering med tilhørende DigitalPostMelding. Det er lov å sende flere kvitteringer tilhørene en og samme conversation_id.

PK-leverandør lager en forretningsmelding (LeveringsKvittering, VarslingFeilet, Mottak, ReturPost) etter dagens regler, men med endring tilsvarende det som ble skissert i steg 2. Dvs.:

• Format skal være JSON, og følge skjema-definisjonen.
  • PK-leverandør legger til Avsenders orgno i feltet Avsender
  • PK-leverandør legger til evt. Databehandlers orgno i feltet Databehandler
• Strukturen er fremdeles en SBD, dvs. består av
  • Først en SBDH, nå JSON-ifisert.
  • Så selve forretningsmeldinga (eks. leveringskvittering), også JSON-ifisert
• Hele SBD’en må signeres på meldingsnivå for å sikre ende-til-ende integritet, og den må defor da bli en JWT.
• PK-Leverandør må signere forretningsmeldingen med sitt virksomhetssertifikat.

PK-leverandør ber så om at C3 sender kvitteringa til Avsender.

C3 slår opp i ELMA og finner hvem som er C2 for Avsender. C3 lager en PEPPOL-melding til C2. C2 mottar kvitteringa, og legger den i kø. Venter på at Avsenders system poll’er på kvitteringer med riktig conversation-id. Verifiserer at Avsender som forsøker å hente kvittering, er den samme som sendte digitalpostmeldingen.

2-vegs svar

Beskrivelse av 2-vegs-svar vil komme dersom funskjonaliteten vedtas og utvikles.