Hvordan setter jeg opp en systembruker i Altinn, fra registrering til første token?

Steg 1: hva må registreres før noen kunde kan godkjenne?

Forutsetningen er en egen Maskinporten-klient, fordi systemet du skal registrere, delvis defineres av klienten det autentiserer seg som. Med den på plass oppretter du en oppføring i Altinns systemregister. Oppføringen bærer virksomhetens organisasjonsnummer på ISO 6523-form, navn og beskrivelse på bokmål, engelsk og nynorsk, rettighetene og tilgangspakkene systemet ber kundene om, klient-id-listen fra Maskinporten, og eventuelt redirect-adresser og et synlighetsflagg som avgjør om kunder kan finne systemet ved navn.

Registreringskallet er selv et maskin-til-maskin-kall: det er beskyttet av skrivescopet for systemregisteret, så Maskinporten-klienten din må ha det scopet innvilget før registreringen kan skje. Dette er steget der den offisielle dokumentasjonen er mest spredt, fordi klienten hører hjemme i Digdirs verden og registeret i Altinns, og hver side dokumenterer sin egen halvdel.

Valget som betyr mest her, er pakkelisten. Oppsettveiledningen er tydelig på at leverandøren har ansvaret for å registrere de riktige tilgangspakkene, og alt nedstrøms arver beslutningen: kunden godkjenner nøyaktig det registeroppføringen ber om, en for bred liste får godkjenninger til å nøle, og en for smal feller senere kall. Hvilken legitimasjonskonstruksjon som spiller hvilken rolle i denne kjeden, eies av veiledningen om valg av legitimasjon.

Steg 2: hva ser kunden, og hvem godkjenner?

For hver kunde oppretter du en systembruker-forespørsel som navngir pakkene det registrerte systemet ditt ber om. Svaret bærer en godkjenningslenke; ta vare på den når du først mottar den, for en gjentatt oppretting av samme forespørsel er observert å svare uten den. Kunden åpner lenken, logger inn i Altinn, og ser systemet ditt under det registrerte navnet sammen med pakkene det ber om, beskrevet i forretningstermer i stedet for som rå scopes.

Godkjenningen er selv en delegering, og det avgjør hvem som kan utføre den. Kontrollen er alt eller ingenting: godkjenneren må ha myndighet til å delegere hver pakke i forespørselen, så én sensitiv pakke kan felle en godkjenning en daglig leder ellers kunne gitt. Når en godkjenning feiler med 403, eller en 500 som oppfører seg som en, eies årsakene og løsningene symptom for symptom av feilsøkingsveiledningen for systembrukere, som denne gjennomgangen med vilje ikke gjentar.

Én egenskap ved resultatet er verdt å designe for fra dag én. Oppsettveiledningen sier rett ut at Altinn ikke vet hvem den enkelte brukeren bak systembrukeren er: tildelingen navngir systemet ditt, ikke de ansatte dine. Den per-bruker-kontrollen produktet ditt trenger oppå den delegerte myndigheten, er din å bygge, og å late som plattformen leverer den er et etterlevelsesgap som venter på å bli synlig.

Steg 3 og 4: hvordan får jeg tokenet og gjør det første kallet?

Token-forespørselen går til Maskinporten, med det samme signerte JWT-grantet klienten din allerede bruker, med ett tillegg: en authorization_details-oppføring av typen urn:altinn:systemuser der systemuser_org navngir kundens organisasjonsnummer på ISO 6523-form, organisasjonsnummeret bak et 0192:-prefiks. I testmiljøet går forespørselen til token-endepunktet på test.maskinporten.no; en valgfri externalRef peker forespørselen mot én bestemt systembruker når kunden har opprettet flere.

Det som kommer tilbake, er det som skiller systembruker-tokenet fra et vanlig Maskinporten-token. Scopene er de samme, men tokenet som utstedes, bærer et authorization_details-claim med systembruker-id og din system-id, som er slik API-et som mottar kallet, avgjør at klienten din opptrer under kundens delegerte myndighet og ikke sin egen. Claimet utvider ikke hva du kan gjøre; det endrer hvems myndighet kallet bærer.

Siste steg er selve kallet, og det har én forgrening: noen Altinn 3-flater godtar Maskinporten-tokenet direkte, mens Altinn-apper og de klassiske plattform-API-ene krever at det først veksles til et Altinn-token. Den beslutningen, og selve vekslingskallet, eies av veiledningen om tokenveksling. For testing kjører du hele kjeden i testdomenet: test-Maskinporten utsteder tokenet, og TT02, på platform.tt02.altinn.no, evaluerer delegeringen. De to miljøene er atskilte tillitsdomener, så ingenting bevist i det ene følger med inn i det andre.

Gjør det første kallet

Sandkassekallet svarer på hvem som overhodet kan opptre for et selskap, uten nøkkel. TypeScript-eksempelet er den meglede utgaven av hele denne gjennomgangen: Apier holder klienten og systemregistreringen, fullmakt-forespørselen starter kundeleddet, og kundens godkjenning i Altinn forblir det ene menneskelige steget. Den meglede flyten kjører på mock-Altinn-adapteren til reelle legitimasjoner er på plass.

# Nøkkelløs sandkasse: hvem som kan opptre for et selskap, fra registeret.
curl -s https://www.apier.no/api/v1/sandbox/public/company/999999999/authority

// Den meglede varianten: én Apier-nøkkel mot apier.no, ingen offentlig
// legitimasjon i din stack. Steg 1 og 3 kollapser inn i dette kallet;
// steg 2, kundens godkjenning, forblir en menneskelig beslutning i Altinn.
const res = await fetch("https://www.apier.no/api/v1/fullmakt/request", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.APIER_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
    agent_principal_id: "22222222-2222-4222-8222-222222222222",
    org_number: "999999999",
    scopes: ["altinn:accessmanagement/authorizedparties.read"],
  }),
});

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();
// Ta vare på data.delegation_url og legg den foran kunden.
// Handle først når GET /api/v1/fullmakt/999999999 svarer full.
console.log(data.status, data.delegation_url);

Ofte stilte spørsmål

Hva må være på plass før jeg kan registrere et system?

En egen Maskinporten-klient, fordi oppføringen i systemregisteret kobler systemet til klient-id-ene det skal autentisere seg som, og selve registreringskallet er beskyttet av skrivescopet for systemregisteret. Oppføringen bærer så virksomhetens organisasjonsnummer, navn og beskrivelse på tre språk, rettighetene og tilgangspakkene systemet ber om, og eventuelt redirect-adresser og et synlighetsflagg.

Hvem hos kunden kan godkjenne systembruker-forespørselen?

Noen hvis egen myndighet dekker hver pakke forespørselen navngir. Godkjenningen er selv en delegering, og kontrollen er alt eller ingenting: godkjenneren må kunne delegere samtlige pakker, så én pakke utenfor myndigheten feller hele godkjenningen. Registerroller som daglig leder dekker de fleste pakkene; de sensitive krever virksomhetens hovedadministrator.

Hva skiller et systembruker-token fra et vanlig Maskinporten-token?

Claimet authorization_details. Et vanlig token bekrefter din organisasjon og dens scopes. Et systembruker-token bes om med en authorization_details-oppføring som navngir kundens organisasjon, og tokenet som utstedes bærer systembruker-id og system-id tilbake til deg, som er det API-et bruker for å avgjøre hvilken myndighet kallet opptrer under. Scopene utvides ikke av dette.

Hvordan kjører jeg hele sekvensen i et testmiljø?

Bruk testkjeden fra ende til ende: test-Maskinporten utsteder tokenet, og TT02, Altinns testmiljø på platform.tt02.altinn.no, evaluerer delegeringen. Test og produksjon er atskilte tillitsdomener, så ingenting følger med over: verken systemregistreringen, kundens godkjenning eller tokenet. En sekvens bevist i TT02 må etableres på nytt, del for del, i produksjon.

Hva er Apiers utgave av hele denne sekvensen?

Én meglet flyt. Apier holder Maskinporten-klienten og systemregistreringen, så applikasjonen din autentiserer seg med én Apier-nøkkel. request_fullmakt starter kundeleddet og returnerer godkjenningslenken, kunden godkjenner i Altinn som før, og check_fullmakt svarer på om delegeringen er aktiv før du handler. Kundens godkjenning er det ene steget ingen megler kan overta.