Maskinporten

Mattilsynet har valgt å bruke Maskinporten fra Digitaliseringsdirektoratet som autoritet for autentisering og autorisering. Det betyr at all autentisert bruk av våre API krever et JSON Web Token (JWT) access token fra Maskinporten med scope mattilsynet:sskk.hvittkjoett.write (mattilsynet:sskk.write for rødt kjøtt). Mattilsynet støtter delegering via Altinn.

Kontakt oss i #ext-team-slakt-hvitt-kjøtt for tilgang.

Samarbeidsportalen

Alle tilbydere og konsumenter av Maskinporten må signere Digitaliseringsdirektoratets bruksvilkår, se Samarbeidsportalen.

I Samarbeidsportalen kan API-konsumenter lage en klient med rett scope ved hjelp av selvbetjening i et web-grensesnitt eller på et API. Det er raskt å komme i gang med utprøving i test-miljøet, men brukere som skal vedlikeholde maskinporten-klienter i produksjon må ha delegert myndighet fra "Direktør/Leder/Annen person med rolle “Hovedadministrator” i Altinn".

Se Selvbetjening web for mer informasjon, og det er altså rettigheten "Selvbetjening av integrasjoner i ID-porten/Maskinporten" som er viktig for api-konsumenter.

En typisk klient ser slik ut:

Praktisk bruk

Autentisering mot et av Mattilsynets API skjer i praksis ved å sende med et access token som et JWT bearer token i HTTP-header-en "Authorization" på formen:

Authorization: Bearer <token>

Tokenet inneholder informasjon om hvem som har utstedt det, hvilket scope (område) det gjelder og hvilket organisasjonsnummer det er gyldig for. Et access token får man ved å lage et JWT grant og sende det inn til Maskinportens /token-endepunkt. Dette JWT grant-et viser til en Maskinporten-klient og et eller flere scope og må være signert av et virksomhetssertifikat eller den private delen av et asymmetrisk nøkkelpar.

En oppsummering:

1. Lag en klient i Maskinporten
2. Lag et JWT grant som viser til klienten og scope sskk.hvittkjoett.write
3. Signér grant-et med virksomhetssertifikatet eller en privat nøkkel
4. Send det signerte grant-et inn til Maskinportens /token-endepunkt
5. Bruk det returnerte access token-et til autentisering mot Mattilsynets API

For nye brukere av Maskinporten anbefaler vi å anskaffe et test-virksomhetssertifikat for å komme i gang. Last gjerne ned Digitaliseringsdirektoratets JWT grant generator for å bli bedre kjent med hvordan lage og bruke et JWT grant. Denne demonstrasjonsapplikasjonen vil gjennomføre punkt to, tre og fire i listen over.

Andre ressurser

Det finnes svært mye god informasjon i Maskinportens dokumentasjon, blant annet en egen side om autentisering. Vi vil også anbefale Using Postman with Maskinporten JWT-grants og jwt.io.

Eftanummer, organisasjonsnummer og underenhet

I endepunktene er det path parametere for slakteriets organisasjonsnummer og slakteriets eftanummer. Eksempel:

/v1/slakterier/hvittkjott/{organisasjonsnummer}/{eftanummer}/leveranser

Tjenesten vil kontrollere at innholdet i disse parameterne er i samsvar med det som er registrert i Mattilsynets systemer når kallet til MKI API behandles. Dersom eftanummeret er registrert på en underavdeling, er det likevel organisasjonsnummeret til overordnet enhet som skal brukes som path parameter. Rent konkret må organisasjonsnummeret i access token-et sitt felt consumer være likt organisasjonsnummeret i path parameter-et. Se også avsnittet under.

Delegering

Tjenesten vil også validere at access token-et fra Maskinporten har lov til å gjøre kall for organisasjonsnummeret som brukes i path parameter-et. Det er to måter tokenet kan være gyldig på:

1. Token er opprettet via et virksomhetssertifikat for samme organisasjonsnummer som angis som path parameter
2. Det er satt opp delegering i Altinn fra slakteriets organisasjonsnummer til en annen organisasjonen som sender inn informasjon

Det kan være tilfelle at et selskap med flere slakterier har disse registrert på flere virksomheter som ligger under en overordnet enhet. Dette gjelder for eksempel Nortura. Man kan ikke kjøpe virksomhetsertifikater for slike underenheter. I slike tilfeller er det ikke nødvendig med Altinn-delegering, og avgiver kan benytte et virksomhetsertifikat utstedt til overordnet enhet, og benytte organisasjonsnummeret til denne overordnede enheten i path parameter-et. Mattilsynet vil kontrollere koblingen mellom denne enheten og enheten som eftanummeret er registrert på. Alternativt kan man bruke autentisering med asymmetrisk nøkkelpar der den offentlige nøkkelen er lagt inn i Maskinporten.

Dersom en tjenesteleverandør eller annen organisasjon skal sende inn MKI på vegne av et slakteri, må slakteriet delegere sin tilgang til avgiver i Altinn. Slakteriets organisasjonsnummer brukes i path parameter-et. Avgiver henter inn et access token der slakteriet organisasjonsnummer er angitt i et claim som heter consumer_org.

Mattilsynet må gi de respektive virksomhetene som skal representeres tilgang til vårt scope for hvitt kjøtt: mattilsynet:sskk.hvittkjoett.write.