Hvordan autentiserer jeg meg mot norske offentlige API-er?

Trenger jeg virksomhetssertifikat for Altinn 3?

For en direkte integrasjon, ja. Et virksomhetssertifikat er et sertifikat utstedt til en juridisk enhet registrert i Brønnøysund, og selges av Buypass og Commfides. Skillet som ofte overrasker, er at det identifiserer virksomheten og ikke en person: det er ikke BankID-en din, og det er ikke knyttet til hvem som tilfeldigvis er utvikler. Å bestille ett innebærer en identitetskontroll av virksomheten, så regn ledetiden som en prosjektavhengighet og ikke en ettermiddagsoppgave.

Sertifikatet forankrer et nøkkelpar. Du registrerer den offentlige halvdelen hos Digdir og beholder den private halvdelen på egen infrastruktur, der den signerer assertionene beskrevet under. Ingenting av sertifikatet sendes til etatens API ved et vanlig kall, noe som overrasker dem som venter gjensidig TLS: sertifikatet beviser hvem du er overfor tokentjenesten, og tokenet beviser det overfor alle andre.

Apier tar ikke den kjeden av hendene dine. Det Apier svarer på, trenger ikke noe Maskinporten-token i det hele tatt, så et kall til Apier bærer en vanlig Bearer-nøkkel og ingenting annet; for de API-ene hos etatene som trenger kjeden, er den din å bygge. Oversikten over Maskinporten-API-et forklarer hva Maskinporten er og hva Apier tilbyr i stedet, og Maskinporten-guiden for utviklere går gjennom den direkte utvekslingen fra ende til ende, inkludert feilsituasjonene som er lettest å feildiagnostisere.

Hvordan fungerer JWT-utvekslingen for klientlegitimasjon?

Med to kall. Først bygger du et JSON Web Token som sier hvem du er og hva du vil ha: utstederclaimet bærer klientidentifikatoren din i Maskinporten, mottakerclaimet navngir Maskinporten-miljøet du snakker med, et scopeclaim lister tilgangen du ber om, og claimene for utstedelsestidspunkt og utløp holder assertionen gyldig i et kort vindu. Du signerer den med den private nøkkelen som er registrert på klienten din. Den signerte blobben er assertionen.

Deretter sender du assertionen til tokenendepunktet med granttypen JWT bearer definert i RFC 7523. Maskinporten verifiserer signaturen mot den offentlige nøkkelen du registrerte, kontrollerer at scopene du ba om er scopes klienten din har fått tildelt, og returnerer et access token sammen med utløpstiden og scopene som faktisk ble utstedt. Les den scopelisten i stedet for å anta at du fikk det du ba om, for en delvis innvilget respons er ikke en feil og vil ellers feile senere mot etatens API.

Derfra er tokenet en helt vanlig Bearer-legitimasjon på kallet mot etaten. To feilsituasjoner står for det meste av tapt feilsøkingstid. Klokkeavvik ugyldiggjør assertioner stille, så hold signeringsverten synkronisert med reell tid, og utvid ikke assertionvinduet for å skjule drift. Og scopes tildeles per klient av etaten som eier dataene, så en korrekt signatur med et utildelt scope feiler ved tokenendepunktet og ikke ved API-et. Det må rettes et annet sted, i en annen konsoll.

Hvordan bør tokens mellomlagres og roteres?

Mellomlagre access tokenet, og velg nøkkelen til mellomlagringen med omhu. Fordi tokens er kortlevde, legger det å hente ett per API-kall en ekstra rundtur på hver forespørsel og belaster tokenendepunktet uten gevinst. Den vanlige formen er en mellomlagring i prosessen som holder tokenet til like før utløp, med en liten sikkerhetsmargin slik at en forespørsel underveis ikke ankommer med et token som nettopp gikk ut.

Nøkkelen til mellomlagringen er der dette blir farlig. Et rent scopetoken kan trygt deles på tvers av kall, men et token utstedt for å opptre på vegne av en kunde er bundet til den ene organisasjonen. Havner begge i en mellomlagring nøklet bare på scope, kan en forespørsel om én kunde bli servert et token utstedt for en annen. Det er en eksponering av data på tvers av organisasjoner, ikke en ytelsesfeil, så nøkkelen for et token på vegne av noen må inkludere organisasjonen det ble utstedt for.

Rotasjon av nøkler og sertifikat går på en langsommere klokke og krever bevisst overlapp: registrer den nye offentlige nøkkelen før du pensjonerer den gamle, slik at assertioner signert med begge verifiserer i overgangen. Den planen er din så lenge du har en Maskinporten-klient; den eneste måten å bli kvitt den på er å ikke trenge noe offentlig token, og det gjelder alt Apier svarer på.

Gjør det første kallet

Sandkasseforespørselen under krever verken sertifikat eller tokenutveksling. TypeScript-snutten er produksjonsekvivalenten, med 401-grenen skrevet slik den bør håndteres.

# Nøkkelløs sandkasse: ingen sertifikat, tokenutveksling eller nøkkel.
curl -s https://www.apier.no/api/v1/sandbox/public/company/999999999/summary

// Produksjon. Ingen tokenutveksling noe sted: åpne registerdata, én nøkkel.
// Bytt ut {org} med et ekte organisasjonsnummer; 999999999 finnes bare i sandkassen.
const res = await fetch(
  "https://www.apier.no/api/v1/company/{org}/summary",
  { headers: { Authorization: `Bearer ${process.env.APIER_API_KEY}` } },
);

if (!res.ok) {
  // 401 er AUTH_MISSING eller AUTH_INVALID: rett nøkkelen, ikke prøv på nytt.
  // Alle ikke-2xx svarer i samme konvolutt, så én gren dekker dem alle.
  const { error_code, explanation } = await res.json();
  throw new Error(`${error_code}: ${explanation.summary}`);
}

const { data, _meta } = await res.json();
console.log(data.name, _meta.data_freshness);

Ofte stilte spørsmål

Trenger jeg virksomhetssertifikat for å kalle Altinn 3?

For en direkte integrasjon, ja. Maskinporten autentiserer en klient med en signert JWT-assertion, og nøkkelen bak den assertionen er forankret i et virksomhetssertifikat utstedt av Buypass eller Commfides til en enhet registrert i Brønnøysund. Det identifiserer virksomheten, ikke en person. Gjennom en megler som allerede har ett, tilhører sertifikatet megleren og ikke deg.

Er Maskinporten det samme som en API-nøkkel?

Nei. En API-nøkkel er en statisk hemmelighet du sender som den er. En Maskinporten-legitimasjon er et asymmetrisk nøkkelpar: du signerer en kortlevd JWT-assertion med den private nøkkelen, sender den til tokenendepunktet og får et avgrenset access token tilbake. Den private nøkkelen forlater aldri infrastrukturen din, og tokenet du faktisk sender utløper på minutter.

Hvor lenge varer et Maskinporten access token?

Minutter snarere enn timer, og derfor er utvekslingen en løkke og ikke et oppsettssteg. Mellomlagre tokenet til like før det utløper, og signer på nytt når det går ut på dato. Ikke be om et ferskt token per API-kall: det legger en ekstra rundtur på hver forespørsel og belaster tokenendepunktet unødig.

Kan jeg mellomlagre ett token og gjenbruke det for hver kunde?

Bare for kall på scopenivå som ikke er knyttet til en bestemt organisasjon. Et token utstedt for å opptre på vegne av en kunde er bundet til den ene organisasjonen, så en mellomlagring nøklet bare på scope vil gi et token utstedt for én kunde til en forespørsel om en annen. Nøkkelen til mellomlagringen må inkludere organisasjonen, ikke bare scopet.

Hva tar Apier bort fra min side her?

Ingenting av selve utvekslingen, fordi det Apier svarer på aldri trenger den. Signaturrett, selskapsfakta, plikter og frister kommer fra åpne registre og regelboken, så applikasjonen din sender én Bearer-nøkkel, og det finnes ikke noe offentlig token i kallet. Der produktet ditt selv må kalle API-et til en etat, er sertifikatet, nøkkelregistreringen, assertionene og rotasjonen dine; Apier formidler dem ikke, og delegeringen per kunde er fortsatt en beslutning bare kunden kan ta.