Hvorfor får jeg 403 eller 500 på systembruker-forespørsler i Altinn?

Hvorfor feiler godkjenningen av en systembruker-forespørsel med 403?

Fordi godkjenning ikke er en signatur, men en delegering. Når kunden din klikker godkjenn på forespørselen systemet ditt opprettet, delegerer Altinn de navngitte tilgangspakkene til systembrukeren, og personen som gjør det må ha myndighet til å delegere hver av dem. Registerrollene dekker de vanlige tilfellene: en daglig leder eller en annen nøkkelrolle kan delegere de fleste pakker. De sensitive pakkene er fellen, siden de ikke har forhåndstildelte roller, og bare virksomhetens hovedadministrator kan dele dem ut.

Feilen forvirrer i praksis fordi den som godkjenner som regel sitter høyt i virksomheten, og posisjon er ikke det som kontrolleres. Kontrollen kjører per pakke, så én pakke i forespørselen som godkjenneren ikke kan delegere, er nok til en avvisning, selv når de fire andre ville gått gjennom. Integratører observerer også at delegeringskontrollen avviser godkjenninger med en feilkode framfor en lesbar melding, noe som gjør et rettighetsspørsmål om til det som ser ut som en teknisk feil.

Løsningen er å gjøre forespørselen godkjennbar før den sendes. Be om det smaleste pakkesettet integrasjonen faktisk trenger, sjekk hvilke pakker som bærer forhåndstildelte registerroller og hvilke som er forbeholdt administrator, og fortell kunden hvem hos dem som må gjøre godkjenningen. Når en blandet forespørsel fortsetter å feile, del den opp: en forespørsel om de ukontroversielle pakkene som går gjennom i dag, slår én perfekt forespørsel som blir liggende avvist.

Hva betyr 500-ene i denne flyten egentlig?

Offisielt er en 500 en serverfeil og en 403 en avvisning. I denne flyten er linjen mindre skarp enn statuskodene antyder: integratører observerer serverfeil på punkter der den underliggende tilstanden er en avvisning, for eksempel når en tilgangspakke-delegering avslås under godkjenning. Ingenting ved det er dokumentert atferd å lene seg på; det er rett og slett det flyten er observert å gjøre, og det endrer hvordan du bør feilsøke den.

Den praktiske regelen: når en 500 dukker opp på et autorisasjonsformet steg, uttøm 403-hypotesene før avbruddshypotesene. Ettergå godkjennerens myndighet, de forespurte pakkene og delegeringens tilstand som om svaret hadde vært en eksplisitt avvisning, for en blind gjentaksløkke mot en avvisningsformet 500 brenner tid og produserer en kø av identiske feil. Holder myndigheten mål og feilen vedvarer, behandle den da som en hendelse.

To mindre symptomer hører til samme observerte klynge. Å liste leverandørforespørslene dine kan slå feil ved sidegrenser, så herd klienten mot en side som ikke kommer framfor å anta at listen er komplett. Og en gjentatt oppretting av en forespørsel som allerede finnes, er observert å svare uten confirmUrl-en det første svaret bar, så ta vare på den URL-en når du først mottar den i stedet for å utlede den fra et gjentatt kall.

Hvordan gjør jeg hele denne feilklassen udramatisk?

Skill de tre spørsmålene flyten stadig klemmer sammen til én forespørsel: er myndighet bedt om, har et menneske gitt den, og er den aktiv akkurat nå. Håndtert som ett steg ser hver feil lik ut fra utsiden. Håndtert som tre navngir hver feil sin egen årsak, og feilsøkingstabellen over krymper til det steget du faktisk står på. Den oppdelingen er et designvalg du kan ta i din egen klient uansett hva du integrerer gjennom.

Det er også nøyaktig slik Apiers fullmaktsflyt er formet. request_fullmakt starter prosessen og returnerer en godkjennings-URL du legger foran kunden; selve godkjenningen forblir en menneskelig avgjørelse i Altinn; og check_fullmakt svarer om delegeringen er aktiv før integrasjonen din handler, med norske fix_steps du kan vise kunden når den ikke er det. En manglende fullmakt blir en tilstand produktet ditt viser, ikke et unntak det kaster.

Konseptene under, hva en systembruker er, hvorfor kunden eier tildelingen, og hvordan tilbaketrekking oppfører seg, eies av veiledningen om systembruker-delegering, og token-halvdelen av historien av veiledningen om tokenveksling. Denne siden forblir det den er: kartet fra symptom til årsak når flyten sier nei.

Gjør det første kallet

Sandkassekallet svarer på hvem som i det hele tatt kan opptre for et selskap, uten nøkkel. TypeScript-eksempelet starter en fullmaktsforespørsel gjennom den meglede flyten, som kjører på den simulerte Altinn-adapteren til produksjonslegitimasjon er på plass, og viser hvor delegerings-URL-en og oppfølgingssjekken bor.

# 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

// Fullmaktsflyten: forespørsel, menneskelig godkjenning, så sjekk.
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();
// Send data.delegation_url videre til kunden. Etter godkjenning:
//   GET /api/v1/fullmakt/999999999
// og handle først når data.overall_status svarer full.
console.log(data.status, data.delegation_url);

Ofte stilte spørsmål

Hvem kan godkjenne en systembruker-forespørsel?

Noen hvis egen myndighet dekker det de godkjenner. Godkjenningen delegerer de forespurte tilgangspakkene til systembrukeren din, og en person kan ikke delegere en pakke vedkommende ikke har rett til å delegere. Registerroller som daglig leder bærer den myndigheten for de fleste pakker; de sensitive pakkene har ingen forhåndstildelte roller, så der kan bare virksomhetens hovedadministrator godkjenne.

Hvorfor feilet godkjenningen når godkjenneren er daglig leder?

Fordi kontrollen kjører per pakke, ikke per person. En godkjenning som bunter flere pakker, krever at godkjenneren kan delegere hver eneste av dem, så én sensitiv pakke i forespørselen kan senke en godkjenning som ellers ville gått gjennom. Å dele opp forespørselen, eller be om et smalere pakkesett, er som regel den praktiske løsningen.

Hva betyr en 500 under godkjenning egentlig?

Les den som en avvisning først og et driftsavbrudd etterpå. Integratører observerer serverfeil i flyter der den underliggende tilstanden er et autorisasjonsproblem, for eksempel at en pakkedelegering avvises. Før du prøver på nytt i løkke, kontroller godkjennerens myndighet og de forespurte pakkene som om svaret hadde vært 403, for i praksis er det ofte det den sto for.

Tokenet er gyldig og delegeringen aktiv. Hvorfor fortsatt 403?

Sjekk hvilket token du presenterte. Altinn-apper og de klassiske plattform-API-ene evaluerer claims det rå Maskinporten-tokenet ikke bærer, blant annet autentiseringsnivået som vekslingsendepunktet legger til. Et gyldig systembruker-token som aldri gikk gjennom vekslingen, kan stryke i autorisasjonen med hver delegering i perfekt stand. Veksle først, kall etterpå.

Hvordan fjerner Apier denne feilklassen?

Ved å gjøre fullmaktstilstanden til noe du leser framfor noe du oppdager gjennom feil. Fullmaktsflyten kjører forespørsel, menneskelig godkjenning og verifisering som separate steg: request_fullmakt starter den, kunden godkjenner i Altinn, og check_fullmakt svarer om delegeringen er aktiv før det første reelle kallet. Feil kommer da som statuser med fix_steps, ikke som overraskende 403-er i produksjon.