Fiks IO er en kanal for sikker maskin-til-maskin integrasjon. Denne kanalen kan benyttes for å bygge prosesser på tvers av systemer og organisasjoner, for eksempel når et fagsystem skal arkivere et dokument i et arkivsystem eller spørre om informasjon som er lagret i et annet system.
Fiks IO tilbyr:
Fiks IO baserer seg på at organisasjoner benytter Fiks Konfigurasjon for å opprette en eller flere kontoer. Andre organisasjoner kan så sende meldinger til disse kontoene, som mottaker kan lese ved å koble seg til io.fiks.ks.no.
For å gjøre det lettere å finne en konto, og vite hvilke meldingstyper systemet som benytter kontoen kan håndtere kan man konfigurere adresser. Adresser består av en eller flere organisasjonsnummer, meldingsprotokoller og sikkerhetsnivåer. Avsendere kan så slå opp i Fiks IOs katalogtjeneste for å finne f.eks. hvilken konto som skal motta digisos meldinger med sikkerhetsnivå fire for Bergen kommune.
Funksjonalitet for å sende og lese meldinger vil typisk bli tilbudt av fagsystemleverandører eller offentlig virksomheter, som når Fiks Digisos formidler sosialsøknader fra Nav til kommunens sosialsystem, men kommuner og andre organisasjoner må fortsatt ha et forhold til hvilke kontoer de har, hvilke meldingstyper disse håndterer, og ikke minst hvem som har tilgang til å lese inkommende meldinger.
I eksempelet over ser man en konto opprettet for å formidle Digisos meldinger til en kommunes fagsystem for behandlig av sosialsøknader. Det er opprettet en adresse på kontoen, “Digisos”, man har konfigurert støtte for meldingsprotokollen “no.nav.digisos.fagsystem.v1”, og sagt at dette systemet kan håndtere meldinger for både sikkerhetsnivå tre og fire.
Fiks IO er en selvstendig kanal, og er ikke bygget for å være en erstatning for SvarUt/SvarInn, som begge vil bli videreført i sin nåværende form. Bruksområdene til tjenestene kan overlappe, og dette gjør at det noen ganger kan være tvil om SvarUt/SvarInn eller Fiks IO er riktig verktøy for et problem.
Hovedsakelig bør man benytte svarut/svarinn for “post”: meldinger hvor payload er menneske-lesbar (f.eks. en pdf), hvor automatisk håndtering begrenses til f.eks. opprettelse av sak i et arkivsystem, og hvor sending til Altinn eller som brevpost er gode alternativer hvis den automatiske håndteringen feiler. Andre faktorer kan være:
Benytt Fiks IO, denne leverer utelukkende til spesifisert mottakerkonto og benytter ingen alternative kanaler, som for eksempel printet post.
Benytt Fiks IO, SvarUt/SvarInn meldinger kan bare krypteres med Fiks-plattformens nøkkel, ikke mottakers. Se “Sikkerhet” for deltajer om hvordan man oppnår trygg ende-til-ende kryptering gjennom Fiks-io
Benytt Fiks IO for å få leveranse på sekunder, ved bruk av SvarUt/SvarInn kan levering ta lang tid, siden SvarUt prøver flere kanaler etter tur og defaulter til print ved leveranseproblemer.
Benytt SvarUt, ved Fiks IO forsendelser risikerer man at meldingen ikke blir håndtert eller avvist av mottaker. Man vil få melding om dette, men man må håndtere evt. retry eller sending via alternative kanaler selv.
Økonomiske aspekter kan også spille inn her, Fiks IO meldinger koster vesentlig mindre pr. stykk enn SvarUt forsendelser.
En Fiks organisasjon oppretter en Fiks IO konto. Andre kontoer kan nå sende til denne kontoen gjennom Fiks IOs REST api ved å spesifisere kontoens KontoId som mottaker. Organisasjonen får meldingene ved å etablere en AMQP kobling til io.fiks.ks.no.
Fiks IO tar i utgangspunktet ikke stilling til hva payloaden i meldingen består i. Metadataformat, filformat, kryptering og lignende er opp til brukeren, men Fiks plattformen tilbyr tjenester og verktøy for å etablere format for integrasjoner:
Autentisering av klienter mot REST service for sending av meldinger og AMQP service for leveranse av meldinger skjer gjennom virksomhetssertifikat-basert maskinporten autentisering.
I utgangspunktet legger ikke Fiks IO føringer på hvordan (eller om) en melding sendt over plattformen sikres, men alle klienter som utvikles av KS, og alle protokoller som Fiks spesifiserer, vil benytte signerte og krypterte meldinger gjennom ASIC-E containere. Denne standarden benyttes også av DIFI i forbindelse med integrasjonspunktet. I klientene skjer signering med samme sertifikat som blir benyttet for autentisering mot maskinporten, kryptering skjer med sertifikatet som mottaker har publisert i Fiks IO Kontokatalog.
Merk at man for å oppnå reell ende-til-ende kryptering, i betydningen at KS ikke har noen mulighet til å lese den overførte meldingen, bør innhente mottakers sertifikater gjennom egne kanaler og selv verifisere disse. Fiks-IO tilbyr automatisk oppslag i katalogen som en tjeneste for å lette dette arbeidet, men man bør være klar over at det å benytte denne gir noe svekket sikkerhet.
For å sende en melding i Fiks IO må man kjenne konto-id’en til mottakeren, men for å støtte mer dynamisk bruk tilbys Fiks IO Kontokatalog. Dette er et register over Fiks IO kontoer og tilknyttede adresser. En adresse består av:
Adresser opprettes og forvaltes gjennom Fiks Konfigrasjon. Katalogen gir også mulighet for å laste opp en offentlig nøkkel i form av et X509 sertifikat. Dette sertifikatet blir benyttet for å kryptere meldinger sendt til kontoen, slik at de kan dekrypteres med den private delen av nøkkelen ved mottak.
Fiks Organisasjoner kan gjøre oppslag i registrerte adresser gjennom katalog-api’et.
Merk at bruk av dette api’et i stede for manuell innhenting av sertifikater kan gi noe redusert sikkerhet. Se “Sikkerhet” for detaljer.
Som nevnt over har Fiks IO i utgangspunktet ingen formening om hva innholdet i en melding er, men det er i mange integrasjon-scenarioer nyttig å ha et felles repository med kontrakter for hvordan meldinger skal bygges opp. Protokollkatalogen tilbyr en slik oversikt, og man kan her referere til spesifikasjoner for meldingstypene som inngår i protokollen, og hvordan disse skal benyttes.
Digisos bruker som nevnt over meldingsprotokollen “no.nav.digisos.fagsystem.v1”, som er beskrevet i mer detalj under Fiks Digisos.
Ta kontakt med fiks@ks.no om du ønsker å etablere eller gjøre endringer i en protokoll.
I tillegg til meldinger definert i protokollkatalogen det er også definert en standard meldingstype som forteller at meldingens ttl har utløpt uten at mottaker har mottat den. Meldingstypen er no.ks.fiks.kvittering.tidsavbrudd
. Denne meldingen blir sendt til avsender når originalmeldingen kommer fremst i køen til mottaker. Dette betyr at meldingen ikke trenger å komme når ttl utløper men kan komme en stund senere.
Hvis mottaker er nede og ikke leser meldinger og første melding har ttl på 2 timer. Vil ikke meldinger bak denne trigge tidsavbrudd melding før 2 timer meldingen som er først utløper.
Disse meldingene inneholder ingen body, men kun headere deriblant svar-til
som vil være en referanse til den opprinnelige meldingen (melding-id), svar-til-type
som inneholder den originale typen på meldingen som har utløpt.
NB! Siden utløp av meldinger ikke vil fungere godt om det ligger flere meldinger på kø vil denne funksjonaliteten fases ut snart. I stedet vil man få en serverfeil når en melding er avvist tre ganger
Ved serverfeil hos mottaker skal det sendes en no.ks.fiks.io.feilmelding.serverfeil
tilbake til sender. Json schema følger med i .net pakken for Fiks-IO-client.
Fiks IO støtter sending av store filer ved at alle meldinger større enn 5 megabyte mellomlagres i Fiks Dokumentlager, i en dedikert konto som opprettes sammen med Fiks IO kontoen. En referanse til denne lagrede filen blir så sendt over AMQP. Filer sendt på slik måte får en time-to-live i dokumentlager lik time-to-live for meldingen + 24 timer. Etter dette vil de automatisk slettes.
Hvis man benytter java eller .net klienten utviklet av KS vil denne mellomlagringen oppleves sømløst - klienten streamer automatisk filer fra dokumentlageret om dette er benyttet.
For å gjøre integrasjon lettere vil KS utvikle klienter som benyttes for både sending og mottak av meldinger fra Fiks IO.
Klientene er tilgjengelig i Java, og .net core. Andre språk vil vurderes, og vi vil gjerne høre fra deg om du skriver klienter for andre språk.
Følgende headere er definert i meldingsutvekslingen.
Header | Beskrivelse |
---|---|
avsender-id | Avsenders Fiks IO-konto |
melding-id | Meldingens ID |
avsender-navn | Navnet på avsenderkonto |
type | Meldingstype |
dokumentlager-id | ID til eventuell fil lagret i Dokumentlager |
svar-til | Hvis meldingen er svar på en tidligere Fiks IO-melding, vil svar-til referere til den |
svar-til-type | På no.ks.fiks.kvittering.tidsavbrudd meldinger legges typen til den opprinnelige meldingen |