Integrasjoner

En Fiks-integrasjon er måten et fagsystem får lov til å gjøre noe på Fiks-plattformen på vegne av en kommune eller en annen organisasjon. Et arkivsystem som sender post gjennom Fiks SvarUt, eller et fagsystem som legger meldinger i Fiks Innsyn, bruker en Fiks-integrasjon.

Ordet integrasjon brukes om mye. Digdir kaller også Maskinporten-klienter for integrasjoner i selvbetjeningen sin. På denne siden er en integrasjon alltid Fiks-integrasjonen, og Maskinporten-klienten heter Maskinporten-klient.

Denne siden forklarer hva som må være på plass, hvem som gjør hva og hvordan et kall ser ut. Den er skrevet for leverandøren som skal lage integrasjonen og for den i kommunen som skal sette den opp.

Tre ting må være på plass

Et kall fra et fagsystem til en Fiks-tjeneste må svare på tre spørsmål. Hvert svar kommer fra sitt eget sted.

Mangler ett av de tre, blir svaret 401 eller 403. Se Når det ikke virker.

Slik henger det sammen

Et eksempel. Storevik kommune bruker et sak- og arkivsystem fra en leverandør og vil sende post fra systemet gjennom SvarUt.

1. Leverandøren har en Maskinporten-klient på sitt eget organisasjonsnummer, med scopet ks:fiks. Den samme klienten bruker leverandøren for alle kundene sine.
2. Storevik kommune oppretter en Fiks-integrasjon i Fiks forvaltning og setter leverandørens organisasjonsnummer som autorisert organisasjon. Kommunen får en integrasjons-id og et passord.
3. Storevik kommune gir integrasjonen tilgang til det den skal gjøre, for eksempel «Sende forsendelser» på SvarUt-kontoen til byarkivet.
4. Kommunen gir integrasjons-id og passord til leverandøren, som legger dem inn i fagsystemet.
5. Fagsystemet henter token fra Maskinporten med leverandørens egen nøkkel og kaller SvarUt med tokenet, integrasjons-id og passord.

Fiks sjekker at organisasjonsnummeret i tokenet er det samme som den autoriserte organisasjonen på integrasjonen, at passordet stemmer og at integrasjonen har tilgangen. Da går forsendelsen.

To organisasjonsnummer er i spill, og de er som regel ulike: kommunens, som eier SvarUt-kontoen og integrasjonen, og leverandørens, som står i Maskinporten-tokenet og som autorisert organisasjon på integrasjonen. Det er vanlig og riktig at autorisert organisasjon er et annet nummer enn kommunens. Leverer leverandøren til flere kommuner, har hver kommune sin egen integrasjon, og alle har leverandørens nummer som autorisert organisasjon.

Ikke bytt autorisert organisasjon til kommunens eget nummer når du rydder i integrasjonene. Står det et nummer du ikke kjenner igjen, er det som regel leverandøren som drifter fagsystemet. Bytter du det, slutter integrasjonen å virke.

Hvem gjør hva

Kommunen

• Har avtale med KS Digital om tjenesten, for eksempel SvarUt.
• Oppretter Fiks-integrasjonen i Fiks forvaltning, under tjenesten den gjelder, med leverandørens organisasjonsnummer som autorisert organisasjon.
• Gir integrasjonen tilgang til det den trenger, og ikke mer.
• Gir integrasjons-id og passord til leverandøren på en trygg måte.
• Trekker tilbake tilgangen ved å bytte passord eller slette integrasjonen i Fiks forvaltning. Det stopper alle kall med en gang.

Leverandøren

• Har en Maskinporten-klient med scopet ks:fiks, se Maskinporten.
• Legger integrasjons-id og passord inn i fagsystemet, helst på en konfigurasjonsside kommunen selv kan fylle ut.
• Bruker tokenet, integrasjons-id og passord i alle kall.

Det finnes ikke noe API for å opprette Fiks-integrasjoner eller gi tilganger. Det gjøres av kommunen i Fiks forvaltning.

Maskinporten

Fiks-plattformen bruker Maskinporten for å vite hvilken organisasjon som kaller. Fiks krever dette av tokenet:

• Det er et JWT access token fra Maskinporten, med scopet ks:fiks.
• Organisasjonsnummeret i tokenet, claimet consumer, er det samme som den autoriserte organisasjonen på Fiks-integrasjonen. Hva som avgjør hvilket nummer Maskinporten legger i tokenet, står hos Digdir.
• Klienten kan være autentisert med virksomhetssertifikat eller med en egen asymmetrisk nøkkel. Fiks bryr seg ikke om hvilken.

Før du kan velge ks:fiks i Digdirs selvbetjening, må KS Digital ha gitt organisasjonen din tilgang til scopet. Send organisasjonsnummeret til fiks@ksdigital.no, og si om det gjelder test, produksjon eller begge. For kommuner og fylkeskommuner må det være hovedorganisasjonsnummeret, det samme som har avtale med Digdir om Maskinporten.

Vår anbefaling er at leverandøren eier Maskinporten-klienten og bruker sitt eget virksomhetssertifikat eller sin egen nøkkel. Da kan én klient brukes for alle kundene, og kommunen slipper å dele noe. Et virksomhetssertifikat er en nøkkel som lar den som har det, opptre som organisasjonen. Kommunen skal aldri gi virksomhetssertifikatet sitt til en leverandør.

Vil kommunen eie Maskinporten-klienten selv, kan den opprette klienten på sitt eget organisasjonsnummer og registrere leverandørens offentlige nøkkel på den. Leverandøren lager nøkkelparet, beholder den private nøkkelen og gir kommunen bare den offentlige. Tokenet får da kommunens organisasjonsnummer, og autorisert organisasjon på Fiks-integrasjonen skal være kommunens. Kommunen kan i tillegg trekke tilbake leverandørens tilgang ved å slette nøkkelen på klienten.

Hvordan du får avtale med Digdir, får tilgang til selvbetjeningen, oppretter klienten og registrerer nøkler, står hos Digdir, og det er dit du skal:

• Ta i bruk Maskinporten som konsument, for kommuner og andre som skal bruke API-et selv.
• Maskinporten for leverandører, for leverandører som henter token på vegne av kunder.
• Teknisk veiledning for API-konsumenter, med hvordan tokenet hentes og hvordan egen nøkkel registreres.

Står du fast hos Digdir, er det Digdir som kan hjelpe: servicedesk@digdir.no.

Klientbiblioteker

KS Digital har biblioteker som henter token fra Maskinporten, med virksomhetssertifikat eller egen nøkkel:

Du trenger ikke bruke dem. Et hvilket som helst bibliotek som kan hente et Maskinporten-token, virker.

Slik ser et kall ut

Alle kall fra en Fiks-integrasjon har tre HTTP-headere:

curl https://api.fiks.test.ks.no/<tjeneste>/api/v1/<endepunkt> \
  -H "Authorization: Bearer <access token fra Maskinporten>" \
  -H "IntegrasjonId: <integrasjons-id>" \
  -H "IntegrasjonPassord: <passord>"

For kall med JSON-innhold legger du til Content-Type: application/json. Endepunktene, parameterne og innholdet er beskrevet i spesifikasjonen til hver tjeneste.

Kall på vegne av en innlogget person

Er en person logget inn i fagsystemet med ID-porten, kan fagsystemet gjøre kall på vegne av personen. Da sender du personens access token i Authorization i stedet for et token fra Maskinporten. IntegrasjonId og IntegrasjonPassord er de samme. Organisasjonsnummeret i tokenet, claimet consumer, må være den autoriserte organisasjonen på integrasjonen.

Tjenesten som blir kalt, vet da både hvem personen er og hvilken integrasjon kallet kommer fra, og det er personens egne tilganger i Fiks som gjelder.

Test og produksjon

Testmiljøet og produksjon er helt adskilt, hos oss og hos Digdir. En integrasjon, et token eller en tilgang i test gjelder ikke i produksjon, og Maskinporten-klienten i test er en annen klient enn den i produksjon. Bruker du virksomhetssertifikat, trenger du ett for test og ett for produksjon. Bruker du egen nøkkel, trenger du én per miljø. Hvilke sertifikater Digdir godtar i hvert miljø, står hos Digdir.

Testmiljøet skal bare inneholde testdata. Produksjonsdata skal ikke inn i testmiljøet: ikke personopplysninger, ikke dokumenter og ikke annet som kommer fra reelle saker. Bruk syntetiske testpersoner. Organisasjoner er som regel deres egne fra Enhetsregisteret, og det er dem testvirksomhetssertifikatet er utstedt til. Se testmiljø.

Komme i gang i test

1. Send organisasjonsnummeret til fiks@ksdigital.no, så gir vi tilgang til ks:fiks i Maskinportens testmiljø. Be samtidig om tilgang til Slack-kanalen vår for support. Der tar vi helst spørsmålene.
2. Opprett Maskinporten-klienten i Digdirs testmiljø.
3. Be oss om en testorganisasjon i testmiljøet til Fiks forvaltning, eller bruk den dere har. Opprett integrasjonen der, med organisasjonsnummeret fra Maskinporten-klienten som autorisert organisasjon. Skjemaet kan vise en feilmelding når organisasjonsnummeret ikke finnes i testregisteret, men integrasjonen virker likevel.
4. Gi integrasjonen tilgang til tjenesten dere tester mot.

Se også testmiljø for testdata.

Komme i gang i produksjon

1. Kommunen må ha avtale med KS Digital om tjenesten.
2. Send organisasjonsnummeret som skal stå i Maskinporten-tokenet til fiks@ksdigital.no, så gir vi tilgang til ks:fiks i produksjon.
3. Opprett Maskinporten-klienten i produksjon hos Digdir.
4. Kommunen oppretter integrasjonen i Fiks forvaltning og gir tilganger.

Når det ikke virker

Grensesnitt og spesifikasjoner

API-ene er REST med JSON. Hver tjeneste har en OpenAPI-spesifikasjon som både dokumenterer grensesnittet og kan brukes til å generere klienter. Spesifikasjonene ligger under hver tjeneste på dette nettstedet, og en samlet oversikt over KS Digitals egne klientbiblioteker finnes på Klientbiblioteker.

Feilmeldinger

De fleste API-ene svarer med feil på dette formatet:

{
  "timestamp": 1767222000000,
  "status": 400,
  "error": "Bad Request",
  "errorId": "15a92338-8d98-4b05-a8a6-a879913259fd",
  "path": "/tjeneste/api/v1/meldinger/40441e83-5120-445d-8c31-63ed2f4e8112",
  "message": "Ugyldig forespørsel",
  "errorCode": "FIKS-0001",
  "errorDetails": {
    "fiksOrgId": "1a5038d7-c1fe-4110-9310-fe3b096a0564",
    "externalReference": "a8793ee2-b7b2-40a5-9731-51e018244cf4"
  }
}

errorId er det vi trenger når du ber om hjelp. errorCode og errorDetails er satt bare når tjenesten har en maskinlesbar feilkode.