Hvordan autentiserer jeg meg mot norske offentlige API-er?
Med et Maskinporten access token for maskin-til-maskin-bruk, hentet ved å signere en kortlevd JWT-assertion med en privat nøkkel forankret i et virksomhetssertifikat (utstedt av Buypass eller Commfides til en enhet registrert i Brønnøysund). Du sender den assertionen til token-endepunktet og får et avgrenset token du presenterer som Bearer-legitimasjon mot etatens API. Apier holder sertifikatet, signerer assertionene og styrer tokenets livsløp bak sin egen Bearer-nøkkel, slik at koden din aldri utfører utvekslingen.
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 token-tjenesten, og tokenet beviser det overfor alle andre.
Gjennom en megler er ingenting av dette ditt. Apier holder sertifikatet, registrerer nøkkelen og signerer assertionene, og applikasjonen din autentiserer seg med en vanlig Bearer-nøkkel. Oversikten over Maskinporten-API-et dekker det meglede oppsettet, 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: utsteder-claimet bærer klient-id-en din i Maskinporten, mottaker-claimet navngir Maskinporten-miljøet du snakker med, et scope-claim 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 token-endepunktet med JWT-bearer-grant-typen 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 scope-listen 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 assertion-vinduet for å skjule drift. Og scopes tildeles per klient av etaten som eier dataene, så en korrekt signatur med et utildelt scope feiler ved token-endepunktet og ikke ved API-et, noe som er en annen rettelse 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 token-endepunktet 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 scope-token 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. Veiledningen om nøkkelrotasjon i Maskinporten dekker rekkefølgen. Gjennom en megler er ikke denne planen din å kjøre, og det er mesteparten av det driftsmessige argumentet for å megle i utgangspunktet.
| Ansvar | Egen drift | Meglet gjennom Apier |
|---|---|---|
| Virksomhetssertifikat | Du bestiller et virksomhetssertifikat fra Buypass eller Commfides og fornyer det før det utløper. | Holdes av Apier. Du skaffer, lagrer eller fornyer aldri et sertifikat. |
| Nøkkelregistrering | Du registrerer den offentlige nøkkelen hos Digdir og beholder den private på infrastruktur du styrer. | Holdes av Apier. Applikasjonen din lagrer én Bearer-nøkkel i stedet for en privat nøkkel. |
| JWT-assertion | Du bygger og signerer en assertion per token-forespørsel, med riktige claims og synkronisert klokke. | Finnes ikke i kodestien din i det hele tatt. |
| Scope-tildelinger | Bes om per klient fra etaten som eier dataene, og godkjennes i deres tempo. | Holdes mot Apiers klient. Nøkkelen din bærer Apier-scopes som read:brreg og read:altinn. |
| Token-mellomlagring og rotasjon | Du mellomlagrer per scope og per organisasjon, fornyer før utløp og faser inn nøkkelbytter med overlapp. | Styres på Apier-siden. Nøkkelen din er langlevd og roteres i ditt eget tempo. |
| Delegering per kunde | Gis av hver kunde til ditt registrerte system i Altinn. | Gis fortsatt av kunden. En megler kan ikke fjerne dette leddet. |
Gjør det første kallet
Sandkasseforespørselen under krever verken sertifikat eller token-utveksling. TypeScript-snutten er produksjonsekvivalenten, med 401-grenen skrevet slik den bør håndteres.
# Nøkkelløs sandkasse: ingen sertifikat, token-utveksling eller nøkkel.
curl -s https://www.apier.no/api/v1/sandbox/public/company/999999999/summary// Produksjon. Token-utvekslingen skjer på Apier-siden.
const res = await fetch(
"https://www.apier.no/api/v1/company/999999999/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 til en enhet registrert i Brønnøysund av Buypass eller Commfides. 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 token-endepunktet 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 token-endepunktet unødig.
- Kan jeg mellomlagre ett token og gjenbruke det for hver kunde?
- Bare for scope-nivå-kall 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?
- Sertifikatet, nøkkelregistreringen, signeringen av assertioner, token-mellomlagringen og rotasjonsplanen. Applikasjonen din sender én Bearer-nøkkel og håndterer aldri et offentlig token. Det en megler ikke kan fjerne, er delegeringen per kunde, fordi den koder en beslutning bare kunden har rett til å ta.