Integrasjonsutvikling

En integrasjon på Fiks-plattformen er en maskin-til-maskin klient som benytter tjenestelaget for å utføre oppgaver på vegne av en fiks-organisasjon. Dette kan for eksempel være et arkivsystem som sender saker gjennom Fiks SvarInn, eller et fagsystem som oppdaterer meldinger i Fiks Innsyn.

Når en Fiks-organisasjon tar i bruk plattformen vil man se at det allerede finnes en del forhåndsdefinerte integrasjoner, for eksempel en SvarUt-integrasjon mot Fiks Innsyn. Dette er “globale integrasjoner” som blir tilgjengelig for alle Fiks-organisasjoner uten at hver organisasjon trenger å opprette dem. Ta kontakt med fiks-kundeservice om du på denne måten ønsker å gjøre en av dine integrasjoner tilgjengelig på hele plattformen. Dette er for det meste relevant for leverandører av skyløsninger for flere kommuner.

Hver Fiks-organisasjon kan også opprette sine egne “lokale” integrasjoner - dette gjøres gjennom Fiks Konfigurasjon. Her opprettes integrasjonen, og man definerer hvilken organisasjon som skal ha rett til å sende forespørseler til Fiks-plattformen på vegne av denne. Organisasjonen kan være Fiks-organisasjonen selv, eller en tredjepart som har driftsansvar. Se under for detaljer om opprettelse av integrasjoner.

Etter organisasjonen er opprettet må den autoriseres for å kunne handle på vegne av en Fiks-organisasjon. Om man for eksempel ønsker å autorisere en integrasjon for å indeksere meldinger Fiks Innsyn må det relevante privilegiet tildeles på konfigurasjonssiden for denne tjenesten. Dette gjelder også for globale integrasjoner.

Hvordan komme i gang med utviklingen

  1. Bestill virksomhetssertifikat fra comfides eller buypass for test. NB! På grunn av krav fra DIFI/Maskinporten kan du ikke bruke selvsignert sertifikat hverken i test eller produksjonsmiljø
  2. Vi må ha org.nr på kontoen hos ID-porten (samme som i virksomhetssertifikatet), slik at vi får gitt dere tilgang til “ks:fiks”-scopet. Sendes til fiks-utvikling@ks.no
  3. Følg oppskrift her for å lage klient hos idporten
  4. Send en e-post til fiks-utvikling@ks.no med e-postadresser som vil ha tilgang til vår Slack support-kanal. Vi liker best å ta support på Slack-chat.
  5. Har dere personinnlogginger i ID-porten test, send disse i en e-post til oss slik at vi kan sette opp test kommune/organisasjon i test. fiks-utvikling@ks.no Hvis ikke får dere testpersoner av oss.
  6. Ta kontakt på Slack-kanalen hvis dere står fast eller ønsker å få tilbakemelding på om dere bruker api-ene korrekt.

Grensesnitt

Integrasjoner mot Fiks-plattformen vil hovedsakelig benytte grensesnitt basert på REST/json.

Vi publiserer OpenAPI-Specification for alle api’er. I dag benyttes versjon 2.0, med plan om migrering til 3.0 etter hvert som verktøy får støtte for denne. Disse spesifikasjonene er nyttige både som dokumentasjon for rest-grensesnittet og som grunnlag for automatisk generering av klienter og modell-objekter. Dette kan for eksempel gjøres ved bruk av Swagger Codegen.

Konfigurasjon

En Fiks-organisasjon kan opprette egen integrasjoner gjennom Fiks konfigurasjon.

  • Sett autorisert organisasjon. Dette vil som regel være organisasjonen som drifter systemet som skal integreres, enten fiks-organisasjonen selv eller en tredjepart.
  • Genererer servicepassord. Dette må opplyses for å autentisere integrasjonen, se under for detaljer.
  • Tildel navn. Et visningsnavn for integrasjonen.
  • Sett beskrivelse. En beskrivelse av hva integrasjonen er og hvilke oppgaver den løsner.
  • Sett tjenester. Hvilke tjenester er denne integrasjonen aktuell for?

Autentisering

Integrasjoner autentiseres på to ulike måter: som “integrasjon” med oAuth 2.0, eller “integrasjon-person” m. Open Id Connect (OIDC).

Integrasjon

Denne metoden benyttes for ren server til server integrasjon, for eksempel når et fagsystem skal laste opp meldinger til Fiks Innsyn. Organisasjonen henter et OAuth 2.0 access token med scope “ks:fiks” fra ID-Porten, basert på organisasjonens virksomhetssertifikat. Dokumentasjon for dette finnes her. Vi støtter i første omgang kun JWT access_tokens, dette må konfigureres hos ID-Porten. I tillegg til dette tokenet må man ha en header for integrasjonId og for integrasjonPassord.

Kallet mot Fiks-plattformtjenesten trenger dermed følgende HTTP headere:

  • Authorization: OAuth-2.0 Jwt Access token som bekrefter organisasjonens identitet, signert av ID-Porten. Scope skal være “ks:fiks”.
  • IntegrasjonId: Id for integrasjonen, generert i Fiks-konfigurasjon. Org.nr i Jwt’en i Authorization header må være konfigurert som autorisert organisasjon for integrasjonen.
  • IntegrasjonPassord: Passord for integrasjonen (fra Fiks-konfigurasjon)

Integrasjon-person

Denne metoden benyttes hvis en innbygger er logget inn på en server i en kommune, og man ønsker å gjøre en forespørsel på vegne av denne innbyggeren. Man trenger fortsatt integrasjon-ID og integrasjonpassord, men i stedet for virksomhetens access token sender man brukerens, innhentet med “ks:fiks” scope via OIDC fra ID-Porten.

Kallet mot Fiks-plattformtjenesten trenger dermed følgende HTTP headere:

  • Authorization: OAuth-2.0 Jwt Access token som bekrefter inbyggerens identitet (fnr), signert av ID-Porten. Scope skal være “ks:fiks”.
  • IntegrasjonId: Id for integrasjonen, generert i Fiks-konfigurasjon. Orgnr i Jwt’en i Authorization header må være konfigurert som autorisert organisasjon for integrasjonen.
  • IntegrasjonPassord: Passord for integrasjonen (fra fiks-konfigurasjon)
http POST https://api.fiks.test.ks.no/innsyn-sok/api/v1/sok \
"IntegrasjonId: <din integrasjon id>" \
"IntegrasjonPassord: <ditt integrasjon passord" \
"Authorization: Bearer <gyldig innbygger access token jwt fra id-porten>"

Autorisering

I tillegg må integrasjonen autoriseres for tilgang til en spesifikk tjeneste. Hvis for eksempel et fagsystem skal kunne laste opp meldinger til Fiks Innsyn må en administrator i kommunen benytte Fiks-Konfigurasjon for å legge til denne tilgangen hos den relvante kommunen.

Dette gjelder også for integrasjoner som leveres som en del av Fiks-plattformen. Skal SvarUt kunne indeksere forsendelse i Fiks Innsyn må også her kommunen eksplisitt autorisere dette.