Brukersynkronisering Sync API

Brukersynkronisering Sync API (Sync API) er et API som lar eksterne målsystemer holde seg kontinuerlig oppdatert på bruker- og gruppedata fra Fiks-plattformen.

Sync API er optimalisert for å hente kun endringer (delta) siden forrige synkronisering. Dette reduserer datamengden og sikrer at målsystemet alltid er synkront med kilden.

1. Arkitektur

Diagrammet under viser hvordan data flyter fra organisasjonens Identity Provider (IdP) til målsystemet via Fiks-plattformen.

Sync API Arkitektur

  1. Provisjonering: IdP (f.eks. Microsoft Entra ID) sender data til Fiks SCIM API.
  2. Lagring: Fiks lagrer dataene i sin database, merket med kildeinformasjon.
  3. Synkronisering: Målsystemet poller Sync API for å hente nye endringer.

Delta-synkronisering med syncToken

Sync API bruker en cursor (syncToken) som klienten må ta vare på mellom hvert kall. Dette tokenet inneholder informasjon om hvor langt klienten har kommet i synkroniseringen, men ikke på et format som klienten skal parse. Det eneste klienten skal gjøre er å ta vare på tokenet, og sende det med på neste request. Dette sørger for at klienten kun får de endringene som har skjedd siden forrige synkronisering.

Sync API Delta Loop

Hvordan det fungerer:

  1. Første kall: Klienten kaller endepunktet uten syncToken. Dette initierer en full synkronisering fra starten.
  2. Respons: Serveren returnerer en liste med hendelser (events), et nytt syncToken og et hasMore-flagg.
  3. Neste kall: Klienten lagrer det nye tokenet og sender det med som en query-parameter i neste request.
  4. Loop: Hvis hasMore er true, bør klienten kalle endepunktet på nytt umiddelbart for å hente neste batch.

2. Tilgang og Autentisering

For å bruke API-et må målsystemet være registrert og autorisert i Fiks Forvaltning.

Base URL

Sync API er tilgjengelig på følgende adresser:

  • Produksjon: https://api.fiks.ks.no/brukersynkronisering/sync/api/v1/
  • Test: https://api.fiks.test.ks.no/brukersynkronisering/sync/api/v1/

Autentisering

Synkronisering mot Sync API autentiseres med Fiks-Porten.

(Mer informasjon om teknisk oppsett av integrasjon og sikkerhet i Fiks-Porten kommer).

3. Endepunkter

API-et tilbyr batch-endepunkter for brukere og grupper, samt mulighet for å hente den fulle tilstanden til en enkelt ressurs. Alle endepunkter bruker følgende sti-parametere:

  • fiksOrgId: Kommunens eller organisasjonens unike ID (UUID) på Fiks-plattformen
  • maalSystem: En unik id som identifiserer målsystemet (felles for alle eventuelle instanser av målsystemet)

Endepunktene for brukere og grupper er ikke synkronisert med hverandre. Dette betyr at en gruppe kan referere til et medlem som ennå ikke er mottatt via /brukere. Klienter må implementere robust logikk for å håndtere slike midlertidige avvik.

Batch-synkronisering (Delta)

Disse endepunktene brukes for å hente endringer over tid ved bruk av syncToken.

Synkronisering av brukere

GET /brukersynkronisering/sync/api/v1/{fiksOrgId}/{maalSystem}/brukere

Viktige Query-parametre: syncToken, limit (default 100).

Eksempel på respons:

{
  "events": [
    {
      "id": "2ceb6af3-0f0a-4fa9-b05c-28b6865451b3",
      "changeType": "sync",
      "timestamp": "2023-10-01T12:00:00Z",
      "resource": {
        "id": "2ceb6af3-0f0a-4fa9-b05c-28b6865451b3",
        "userName": "ola.nordmann@kommune.no",
        "displayName": "Ola Nordmann",
        "active": true,
        "fiks": { "identityNumber": "12345678901" }
      }
    }
  ],
  "syncToken": "eyJhbGciOiJIUzI1NiJ9...",
  "hasMore": false
}

Synkronisering av grupper

GET /brukersynkronisering/sync/api/v1/{fiksOrgId}/{maalSystem}/grupper

Viktige Query-parametre: syncToken, limit, maxGroupSize (default 100).

Enkeltoppslag (Full tilstand)

Bruk disse endepunktene for å hente den nyeste og fullstendige tilstanden for en spesifikk ressurs.

  • Hent enkeltbruker: GET /.../bruker/{brukerId}
  • Hent enkeltgruppe: GET /.../gruppe/{gruppeId} (Returnerer fullstendig gruppe inkludert alle medlemmer).

4. Forståelse av respons-data

Hendelsestyper (Events)

Sync API opererer med to hovedtyper endringer:

  1. sync: Brukeren eller gruppen er opprettet eller endret. Feltet resource inneholder den oppdaterte tilstanden.
  2. delete: Brukeren eller gruppen er slettet fra kildesystemet. Feltet resource vil da være null.

Spesialhåndtering av store grupper

Hvis en gruppe har svært mange medlemmer (overstiger maxGroupSize), vil den ikke inkluderes i sin helhet i batch-responsen for å unngå for store payloads.

Sync API Large Group

  • Feltet requiresSeparateFetch vil da være true og resource vil være null.
  • Klienten må da gjøre et manuelt oppslag mot enkeltgruppe-endepunktet for å hente medlemmene.

Beriking med Personidentifikator (FNR/D-nummer)

Sync API støtter automatisk beriking av brukere med fødselsnummer (under feltet fiks.identityNumber). Merk: Hvis en brukers fødselsnummer blir lagt til eller oppdatert i etterkant, vil dette trigge en ny sync-hendelse i API-et, selv om ingen andre SCIM-data har endret seg.

5. Robusthet og Edge Cases

Paging og ufullstendige sider

Når man integrerer mot Sync API-et, er det viktig å følge disse mønstrene:

  1. Ufullstendige sider: Selv om du ber om limit=100, kan du motta færre hendelser selv om hasMore er true.
  2. Tomme sider med hasMore=true: I visse tilfeller kan en respons inneholde 0 hendelser selv om det er flere data i kø. Klienten må alltid se på hasMore-flagget for å avgjøre om den skal fortsette å polle, uavhengig av antall hendelser i responsen.

Feilhåndtering og Statuskoder

  • 200 OK: Alt OK.
  • 400 Bad Request: Ugyldig forespørsel (f.eks. feil format på token).
  • 401 Unauthorized: Manglende eller ugyldig autentisering.
  • 404 Not Found: Ressurs ikke funnet, eller målsystemet er ikke konfigurert.
  • 410 Gone: Viktig! Ditt syncToken er utdatert (f.eks. ved kildebytte). Klienten må kaste tokenet og starte en ny full synkronisering (kall uten token).

Veien videre

  • Kommende funksjonalitet: Vi jobber med å definere en utvidet respons for status 410 som angir hvorfor synkroniseringen må startes på nytt, f.eks dersom kilden som var koblet til målsystemet er byttet.
  • Teknisk referanse: Fullstendig OpenAPI-spesifikasjon finnes i Fiks API-dokumentasjon.