Innledning

Dette er spesifikasjon av bruk av AMQP for meldingsutveksling med Helsenorge basert på den internasjonale standarden AMQP.

Meldingsutveksling med Helsenorge

For å sende meldinger benyttes den åpne, internasjonale standarden AMQP som transportprotokoll. Norsk Helsenett (NHN) har etablert en Tjenestebuss som er tilgjengelig for alle virksomheter tilknyttet Norsk Helsenett.

I noen tilfeller benyttes også meldingsutveksling for å tilby synkrone tjenester. I utgangspunktet bør dette løses av mekanismer for datadeling, men av sikkerhetsmessige og historiske grunner har integrasjon via meldingsutveksling vært mest hensiktsmessig.

Eksempel flyt meldingsutveksling

Sekvensdiagram for et eksempel av asynkron tjeneste er vist i figuren under:

Open

Sekvensdiagram for et eksempel av synkron tjeneste er vist i figuren under.

Open

AMQP Meldingsutveksling

Ved innføring av Digital Dialog fastlege, var det behov for en mekanisme for synkron meldingsutveksling. Synkrone meldinger er ikke godt støttet med standard for meldingsutveksling basert på SMTP og ebXML. Bruk av AMQP ble derfor pilotert, og benyttes som transportprotokoll med Helsenorge.

Meldingsutveksling via AMQP er vist på figuren under med lignende notasjon som i standard for meldingsutveksling:

Open

Dette kapittelet beskriver AMQP profil som er utarbeidet og feilhåndtering som benyttes ved utveksling av meldinger.

AMQP Profil

En AMQP melding består av «Bare message» som er meldingen generert av avsender. Denne er «immutable», dvs. det verken kan eller vil skje endring fra den er sendt til den er levert.

Open

«Annotated message» inneholder tilleggsinformasjon for å transportere meldingen korrekt frem til mottaker.

«Bare message» består

• Properties: Liste over predefinerte nøkler og deres verdier (dersom de er satt). Eks. «reply-to» eller «subject».

• Application properties: Egendefinerte nøkler og deres verdier. Eks. “cpa-id”. Alle er av typen String

• Application data: Selve innholdet i meldingen, dvs. fagmeldingen

Open

De øvrige elementene er:

• Header 0 eller 1 forekomst, inneholder leveranseattributter for meldingen.

• Delivery annotations 0 eller 1 forekomst, inneholder ikke-standard leveranseattributter for meldingen. Ikke i bruk

• Message annotations 0 eller 1 forekomst

• Footer 0 eller 1 forekomst

Videreføring av prinsipper og funksjonalitet i ebXML/ebMS

ebXML rammeverket benyttes i dag for håndtering av:

• Trygghet for at meldingen kommer fram ved bruk av transportkvitteringer

• Sikkerhet. SMTP som protokoll har svært lite innebygget sikkerhet

Med AMQP-protokollen eksisterer det en struktur som er egnet for å håndtere de standardiserte feltene og verdiene som benyttes i ebMS V2. Bruk av ebMS sammen med AMQP vurderes som lite hensiktsmessig og gir et ekstra lag med innkapsling som tilfører lite verdi.

ebXML-transportkvittering (ebXML Acknowledgment) er håndtert ved følgende funksjonalitet i AMQP og krav til kommunikasjonsparametre i Tjenestebussen:

• Avsender kan kun skrive til Tjenestebuss som eksisterer og er tilgjengelig

• Positiv bekreftelse på at skriving til Tjenestebuss er OK

• Sendingsforsøket feiler dersom Tjenestebuss er utilgjengelig

• Krav til bruk av kommunikasjonsparametre (CPP og CPA), mottager har aktivt valgt å støtte en kommunikasjonsprosess.

Feilmelding (ebXML Error Signal) er håndtert ved følgende funksjonalitet i AMQP (avsnitt 2.2 i AMQP spesifikasjon)

• Transaksjonsbasert lesing av køen med støtte for å bekrefte at lesing og behandling av melding har gått bra før den slettes fra køen.

• Leseoperasjon der transaksjonen ikke avsluttes, vil resultere i at meldingen etter 10 forsøk havner på mottagers Deadletter kø

• Bruk av Error-kø der mottager sender en feilmelding som inneholder feilkode og en feilstatus, samt referanse til den opprinnelige meldingen

• Krav til prosesser og rutiner for håndtering av error og deadletterkø

Applikasjonskvittering benyttes for å kvittere positivt eller negativt på selve fagmeldingen.

Med AMQP som protokoll er det også full sporbarhet av meldinger, slik at NHN som driftsleverandør kan identifisere status for en melding, hvem som har skrevet melding og hvem som eventuelt har mottatt og lest melding fra kø.

Ansvarsoverdragelse for behandling av melding

AMQP følger retningslinjer beskrevet i "Veiledning til riktig bruk av Applikasjonskvittering" (HISD 1168:2016)

Det er er definert at ansvaret for behandling av melding overføres ved mottak av positiv applikasjonskvittering:

«Applikasjonskvittering brukes for å bekrefte eller avkrefte om en fagmelding har kommet korrekt fram til fagsystemet. Når positiv applikasjonskvittering er mottatt, skal avsender av fagmeldingen kunne være sikker på at fagmeldingen er kommet frem, at innholdet er i rett format, og at meldingen er klar for behandling i mottakers fagsystem. Det betyr således at mottaker har overtatt ansvaret for den videre behandlingen av fagmeldingen. Applikasjonskvitteringen er derfor avgjørende for tilliten til den elektroniske samhandlingen.»

Dette betyr også at det er avsender sitt ansvar å følge opp en sendt melding helt til en får en positiv applikasjonskvittering.

For synkrone tjenester som ikke benytter applikasjonskvittering, overdras ikke ansvaret til mottager av meldingen.

AMQP Køoppsett

Køer administeres ved hjelp av funksjoner i Adresseregisteret. Behovene til den enkelte virksomhet og tjeneste, sammen med kravene i de aktuelle forretningsprosessene, bestemmer hvilke køer som trengs.

Følgende køer benyttes av helsenorge ved meldingsutveksling via AMQP

• Async: Brukes ved asynkrone operasjoner. Time to Live (TTL) for async kø er satt til 10 dager

• Sync: Brukes ved synkrone operasjoner. TTL er satt til 15 sekunder

• Error: Brukes ved kjente feilsituasjoner, beskrevet i AMQP Feilhåndtering. TTL er satt til 10 dager

• Deadletter: Innkommende meldinger rutes til deadletter-køen dersom mottaker forsøker å lese meldingen fra kø flere enn et definert antall ganger uten at transaksjonen avsluttes. TTL er satt til 10 dager

Det er etablert løsning for arving av køer fra virksomhet, for å redusere antall køer og forenkle drift og vedlikehold. Det er også mulig å sette opp en mal for nye tjenester, som gjør at disse automatisk får ønsket oppsett ved opprettelse.

Hvilken kø det skal sendes til skal hentes fra samhandlingsavtale (CPA), se Krav til bruk av kommunikasjonsparametre for mer informasjon.

Type køer og kønavn

Krav til monitorering og oppfølging

Error-køen skal monitoreres slik at feilen kan rettes, og eventuelt gi sluttbruker beskjed om at en utgående melding har feilet og at mottager derfor ikke kunne prosessere meldingen. Sluttbruker skal bli presentert med angitt årsak og mulighet til å resende meldingen etter at feilsituasjon er rettet.

Formålet med deadletter-køen er å holde på innkommende meldinger som ikke kan prosesseres av mottaker på det gitte tidspunktet. Årsaken til at meldingen havner på deadletter kan være flere, men i hovedsak skal det dreie det seg om at ett eller flere bakenforliggende system er nede, nettverksbrudd eller uhåndterte feil.

Meldinger som havner på deadletter-køen må analyseres for feilkilde. I noen tilfeller kan det være tilstrekkelig å reprosessere melding, dette gjelder ved midlertidige feil. I andre tilfeller vil det kreves en retting i meldingstjener for å behandle melding korrekt. Melding kan reprosesseres ved å legge melding tilbake på kø spesifisert i «to»-feltet i AMQP properties.

Deadletter-køen skal overvåkes slik at det gis anledning til å identifisere feilen og reprosessere disse meldingene etter at feilsituasjon er rettet.

AMQP attributter

AMQP versjon 1.0 (OASIS Advanced Message Queuing Protocol (AMQP) Version 1.0) skal benyttes i henhold til profilen under.

Bokstavkodene for kolonnen Required/optional betyr følgende:

• R = Feltet er påkrevd i alle sammenhenger når det sendes en AMQP-melding

• R2 = Feltet er kun påkrevd når AMQP-meldingen brukes for å melde transportfeil

• O = Feltet er valgfritt og skal kun brukes i henhold til beskrivelsen av feltet

• O2 = Feltet er valgfritt og skal kun brukes når AMQP-meldingen brukes for å melde transportfeil og i henhold til beskrivelsen av feltet

Application properties er utvidet med attributter fra SOAP:Header i ebXML for å støtte bruk av kommunikasjonsparametre.

Tabellen under angir innhold i de ulike feltene

Sertifikathåndtering

Meldingstjener anbefales å holde en lokal cache av sertifikater for systemoptimalisering.

Følgende skal valideres for sertifikater ved inngående og utgående meldinger:

• Er innenfor gyldighetsperioden

• Har korrekt bruksområde

  • Benytt OID verdi 2.5.29.15 - Key Usage for å kvalitetsikre bruksområdet til sertifikatet

• Ikke er tilbakekalt/revokert ved å gjøre en Online Revocation Check

• Dersom validering-serveren til sertifikatutsteder er nede skal operasjonen avbrytes og det kan forsøkes på nytt etter et egendefinert tidsrom.

Dersom validering av offentlige sertifikat feiler, skal cache invalideres og nye sertifikater hentes fra adresseregisteret. Meldingen skal beholdes, og dekryptering eller validering skal gjøres på nytt med det nye sertifikatet når dette er lastet ned og installert.

For løsninger som støtter parallelle sertifikater skal nyeste sertifikat benyttes som default. Dette for å gjøre overgang fra gammelt til nytt sertifikat så smidig som mulig og minimere risiko for feil ved utløp av gammelt sertifikat.

For meldingsutveksling ved AMQP benyttes kommunikasjonsparametre, der CPA angir hvilket sertifikat som er benyttet for kryptering og signering. Denne mekanismen vil håndtere sertifikatbytter på en smidig måte, uten behov for manuelle steg.

Kryptering og signering av fagmelding

Den krypterte og signerte fagmeldingen («Payload» i ebMS) plasseres direkte i AMQP Application Data uten noen form for MIME-encoding/konvertering. Dvs. at en skriver/leser de krypterte dataene til/fra AMQP-meldingen på samme måte som om en skriver til/fra en fil (dataene er en byte-array, byte[]). For signering benyttes «encapsulated data». Ved bruk av både signering og kryptering skal fagmeldingen først signeres og deretter krypteres. Cryptographic Message Syntax benyttes for signering og kryptering, og prosessen for dette er:

1. Signerer fagmeldingen (encapsulated, ikke detached)

   1. Input er komplett fagmelding + virksomhetssertifikat med Key Usage = «Non-Repudation»

   2. Output er signert fagmelding

2. Deretter kryptereres den signerte fagmeldingen

   1. Input er signert fagmelding fra pkt. 1b + virksomhetssertifikat med Key Usage = «Key Encipherment»

   2. Output er kryptert fagmelding

3. Til sist opprettes en AMQP Message:

   1. ContentType = “application/pkcs7-mime; smime-type=signed-andenveloped-data”

   2. Body = Output fra 2b

Signering og kryptering benytter virksomhetssertifikater registrert i Adresseregisteret

Synkronisering av klokke

For sending og mottak av meldinger er det viktig og påkrevd at klokken på klienten er synkronisert med en sentral tidsserver. Dette kreves blant annet for:

• Sikre at synkrone meldinger håndteres korrekt

• Sikre at tidsstempel i fagmelding er riktige, disse brukes i noen tilfeller for sortering av meldinger

For synkronisering av klokker er det flere tilgjengelige tidsservere på internett og disse kan velges fritt. NHN tilbyr en tidstjener for applikasjoner på helsenett. Denne er vist i tabellen under.

AMQP Feilhåndtering

Meldingsutveksling benytter følgende mekanismer for å ivareta leveringssikkerhet og at avsender får beskjed om feil som oppstår når mottaker henter ned en melding fra kø og prosesserer meldingen:

• AMQP-Error: benyttes ved feilsituasjoner på transportnivå. Dette er feil som oppstår i forbindelse ved validering av sertifikater i signerings- og krypteringssammenheng, feil encoding på Payload eller manglende påkrevde felter på AMQP-konvolutt.

• Negativ AppRec: brukes dersom fagmelding ikke kan tolkes eller behandles av mottakers system.

• Fagmelding: Dersom fagmeldingen har passert validering og positiv AppRec er sendt, men det oppstår en situasjon som skal rapporteres tilbake til avsender som en feil svares det med en fagmelding.

• Håndtering av manglende AppRec: Dersom avsender ikke mottar en AppRec etter en definert tidsperiode skal meldingen tolkes som å ha fått en negativ AppRec.

Håndtering av de ulike mekanismene er ytterligere detaljert i underavsnitt.

Prosess asynkrone tjenester

For asynkron kommunikasjon er prosessen for sending av meldinger, inkludert feilhåndteringsprosessen vist i figuren under.

Open

Stegene i prosessen er kortfattet beskrevet i tabellen under.

Prosess synkrone tjenester

For synkron kommunikasjon er prosessen for meldingsutveksling inkludert feilhåndteringsprosessen vist i figuren under. Den største ulikheten på den asynkrone prosessen er at

• Applikasjonskvittering benyttes ikke: det forventes en synkron og når sanntid respons fra mottager. Dersom denne responsen ikke kommer vil transaksjonen time ut hos avsender

• Dead letter kø benyttes ikke, meldingen er ikke persistent og vil time ut fra kø.

Open

Stegene i prosessen er kortfattet beskrevet i tabellen under.

Validering av meldinger og håndtering av feil

Både AMQP-meldingen og fagmeldingen skal valideres av avsender før den sendes, og av mottaker før den prosesseres. Avsnittet beskriver minstekravene for validering av en melding og hvordan feil i validering skal håndteres.