Hvilken legitimasjon trenger jeg: virksomhetssertifikat, virksomhetsbruker, systembruker eller Maskinporten-klient?

Hva lar hver legitimasjon deg faktisk gjøre?

En Maskinporten-klient er virksomhetens maskinidentitet. Du registrerer den selv, den autentiserer seg ved å signere en kortlevd JWT med en registrert nøkkel, og tokenene den mottar bærer scopene etatene har gitt til din virksomhet. Det den ikke kan, er å opptre for andre på egen hånd: en klient alene bekrefter din identitet, så data en etat knytter til en annen organisasjons samtykke forblir utenfor rekkevidde uansett hvor mange scopes du har.

Systembrukeren fyller nøyaktig det gapet. Den opprettes for en kundeorganisasjon og delegeres av noen med myndighet der, og tokenene klienten din så henter gjennom Maskinporten, identifiserer systembrukeren som opptrer for den kunden. Den kan ikke utvide dine egne scopes, og den finnes ikke før kunden gir den, som er et poeng: myndigheten på kallet er kundens, gitt med vilje, og kunden kan trekke den tilbake.

Virksomhetsbrukeren løste det samme problemet en plattformgenerasjon tidligere: en virksomhetsopprettet bruker for Altinn 2, som logger inn med brukernavn og passord paret med et virksomhetssertifikat. Den lever fortsatt i integrasjoner fra før Altinn 3, og det er den eneste situasjonen som krever den. Selve sertifikatet, til slutt, er ikke tilgangslegitimasjon, men den virksomhetsutstedte nøkkelen som signerer Maskinporten-assertions, og heller ikke den rollen er lenger eksklusiv, som de neste avsnittene dekker.

Hva er gjeldende, og hva er på vei ut?

Den gjeldende modellen er Maskinporten-klienten pluss, når du opptrer for kunder, systembrukeren. Begge er dokumentert som den stående mekanismen: klienten autentiserer seg med en signert JWT og ingenting annet, og systembrukeren er Altinn 3-konstruksjonen for maskintilgang under en organisasjons myndighet. Ingenting ved noen av dem er midlertidig, og nye integrasjoner bør legge dem til grunn.

Virksomhetsbrukeren er den å planlegge seg bort fra. Den hører til Altinn 2, hvis nedstenging er varslet, og overgangen er datert der den berører rettigheter: Skatteetatens veiledning dokumenterer at roller og delegering av roller i Altinn 2 fjernes ved inngangen til 2027, med gamle tildelinger virksomme gjennom et overgangsvindu før det. En integrasjon som autentiserer seg som virksomhetsbruker i dag, virker fortsatt mot de gjenværende Altinn 2-flatene, og hver av de flatene har en migreringsdato et sted på seg.

Sertifikatets status er mer subtil: ikke avviklet, men ikke lenger eneste mulighet. Maskinporten dokumenterer to måter å holde en klients signeringsnøkkel på, forankret i et virksomhetssertifikat fra Buypass eller Commfides, eller registrert direkte som ditt eget nøkkelsett, som dokumentasjonen rammer inn som måten å unngå å spre sertifikater. Valget påvirker hvordan du lagrer og roterer nøkkelen, ikke hva klienten kan gjøre.

Hvordan henger delene sammen i en reell integrasjon?

De stables i stedet for å konkurrere. En leverandør som betjener regnskapskunder, ender med én Maskinporten-klient, forankret i én nøkkel, som henter token som opptrer gjennom én systembruker per kunde. Klienten er din, delegeringene er kundenes, og nøkkelen er det stille laget i bunnen. Det forvirrende spørsmålet om hvilken man trenger, løser seg som regel til alle de gjeldende, hver med sin egen jobb.

Mekanikken i hvert lag eies av egne sider: sertifikat-, assertion- og caching-detaljene av autentiseringsveiledningen, og spørsmålet om hvilket token en gitt Altinn 3-flate vil ha, Maskinportens eget eller det vekslede Altinn-tokenet, av veiledningen om tokenveksling. Denne siden forblir kartet; de sidene er terrenget.

Gjennom en megler kollapser stabelen fra din side. Apier holder klienten, nøklene og token-løkken, og megler systembruker-flyten, så applikasjonen din autentiserer seg med én Bearer-nøkkel mot ett API. Det som forblir ditt, er beslutningen ingen mellommann kan ta: at hver kunde gir, og kan trekke tilbake, myndighet over egne forhold.

Gjør det første kallet

Den første forespørselen trenger ingen legitimasjon i det hele tatt og lister hva én Apier-nøkkel låser opp. Den andre leser et selskaps registrerte signaturrett over den meglede flaten, uten at noen av de fire konstruksjonene over dukker opp i din stack.

# Nøkkelløst: hva én Apier-nøkkel låser opp, inkludert scope-vokabularet.
curl -s https://www.apier.no/api/v1/capabilities

// Meglet: registrert signaturrett for et selskap, uten sertifikat,
// uten klientregistrering og uten offentlig legitimasjon i din stack.
const res = await fetch(
  "https://www.apier.no/api/v1/company/999999999/authority",
  { headers: { Authorization: `Bearer ${process.env.APIER_API_KEY}` } },
);

if (!res.ok) {
  // Alle ikke-2xx-svar bruker den samme strukturerte konvolutten.
  const { error_code, explanation } = await res.json();
  throw new Error(`${error_code}: ${explanation.summary}`);
}

const { data } = await res.json();
// "sole" | "joint" | "by_role" | "prokura_only" | "no_authority"
// | "unknown", pluss innehaverne.
console.log(data.classification, data.signaturrett_holders);

Ofte stilte spørsmål

Hva er forskjellen på en Maskinporten-klient og en systembruker?

Hvems myndighet kallet bærer. En Maskinporten-klient registreres av din egen virksomhet, og tokenene den henter bekrefter din identitet og dine tildelte scopes. En systembruker opprettes for en kundeorganisasjon og delegeres av den kunden, så kall gjort under den opptrer på kundens vegne. En integrasjon som betjener mange kunder, holder typisk én klient og opptrer gjennom én systembruker per kunde.

Er en virksomhetsbruker det samme som en systembruker?

Nei. En virksomhetsbruker er en Altinn 2-konstruksjon: en virksomhetsopprettet bruker som autentiserer seg med brukernavn og passord sammen med et virksomhetssertifikat mot Altinn 2-API-et. Systembrukeren er Altinn 3-mekanismen for maskintilgang under en organisasjons myndighet, med token hentet gjennom Maskinporten. Nye integrasjoner bør ikke bygges på virksomhetsbruker.

Trenger jeg fortsatt virksomhetssertifikat for Maskinporten?

Ikke nødvendigvis. Maskinporten dokumenterer to måter å holde signeringsnøkkelen på: forankret i et virksomhetssertifikat, eller registrert direkte som ditt eget nøkkelsett, som dokumentasjonen beskriver som måten å unngå å spre sertifikater. Uansett autentiserer klienten seg med en signert JWT; noen client secret-variant finnes ikke.

Hvilken av disse er på vei ut?

Virksomhetsbrukeren, sammen med plattformen den hører til. Nedstengingen av Altinn 2 er varslet, og Skatteetatens veiledning dokumenterer at roller og delegering av roller i Altinn 2 fjernes ved inngangen til 2027, etter et overgangsvindu. Maskinporten-klienten, systembrukeren og nøkkelen under dem er den gjeldende modellen.

Hva holder Apier for meg i dette bildet?

Hele venstresiden av beslutningen. Apier holder Maskinporten-klienten, de sertifikatforankrede nøklene og token-livssyklusen, og megler systembruker-flyten per kunde. Applikasjonen din autentiserer seg med én Apier-nøkkel, og det eneste leddet som forblir ditt, er det ingen megler kan ta: at kunden din gir myndighet over egne forhold.