Hvorfor får jeg 403 på API-delegering i Maskinporten?

Hvem må ha hva før en delegering kan lykkes?

Modellen har tre parter og en streng rekkefølge. API-tilbyderen gir et Maskinporten-scope til sine konsumentorganisasjoner, og tilbyderen gir aldri leverandøren tilgang direkte. En kunde som har tilgangen, kan så delegere den videre til en leverandør gjennom Altinn, og leverandørens klient ber om token som navngir kundeorganisasjonen og får et token som bærer begge identiteter. Hvert hopp er en reell autorisasjonsbeslutning, og derfor kan feilen sitte i hvilket som helst av dem.

To betingelser må holde før personen som delegerer i det hele tatt når skjermbildet. Scopet må være delegerbart: et Maskinporten-scope uten delegeringskilde kan ikke bruke Altinn til delegering, punktum, og å åpne for det er tilbyderens registreringsarbeid, ikke kundens. Og ressursen bak scopet bærer en policy som avgjør hvem som kan delegere den, så personen som opptrer for kunden må ha en rolle policyen godtar. Portalflyten er dokumentert som en jobb for en nøkkelrolle-innehaver, typisk daglig leder.

Dette er takregelen i praksis. En leverandør kan ikke be om mer enn kunden har, kunden kan ikke delegere mer enn tilbyderen ga, og personen som klikker deleger kan ikke gi videre rettigheter utenfor sin egen rolle. Når en delegering feiler, gå kjeden fra venstre mot høyre og spør ved hvert steg: har denne parten faktisk det den neste trenger?

Hvorfor avvises selve delegeringsforespørselen?

Symptomet integratører rapporterer ser slik ut: en POST av en maskinportenschema-delegering, med den delegerende organisasjonens nummer i headeren, besvart med en autorisasjonsavvisning før noe er opprettet. Forespørselen er velformet, organisasjonen finnes, og svaret sier likevel nei. Den formen betyr at policykontrollen på delegatorsiden strøk, ikke at innholdet var feil, så å revalidere forespørselskroppen er tid brukt på feil sted.

Det som gjør denne feilen dyr, er at feilmeldingen sier at tilgang er avslått uten å navngi rollen som mangler. Personen har en senior tittel, organisasjonen bruker åpenbart API-et, og ingenting i svaret skiller en manglende rolle fra en manglende tildeling fra et ikke-delegerbart scope. Integratører observerer nøyaktig denne ugjennomsiktigheten, og den gjør et rettighetsspørsmål om til det som ser ut som en plattformfeil.

Feilsøk det som et rettighetsspørsmål likevel, i takrekkefølge. Bekreft først at scopet er delegerbart, for satte tilbyderen aldri en delegeringskilde, kan ingen person lykkes. Bekreft så at kundeorganisasjonen faktisk har tilgangen den prøver å gi videre. La deretter delegeringen utføres av noen ressurspolicyen godtar, som i portalflyten betyr en nøkkelrolle-innehaver. Å dele opp spørsmålet slik finner det sviktende hoppet med tre kontroller i stedet for en supportsak.

Hvorfor dukker ikke Altinn 2-tildelinger og ferske portaltildelinger opp?

Æragrensen er den strukturelle. Delegeringer gjort i Altinn 2 løses ikke pålitelig opp for mottakeren i Altinn 3-flyter, og for noen tildelinger er det dokumentert snarere enn tilfeldig: Skatteetatens overgangsveiledning navngir gamle tildelinger som utgår og må delegeres på nytt, og når Altinn 2 stenger, kan bare de nye tilgangspakkene delegeres. Insisterer en kunde på at tilgangen ble gitt for flere år siden mens integrasjonen din ikke ser den, tro begge, og deleger på nytt under den nye modellen.

Forsinkelsesfellen er mindre, men skarpere. Integratører observerer at en delegering som lyktes i portalen, kan ta tid før den blir synlig for API-et som evaluerer den, så den første autorisasjonskontrollen etter en tildeling kan stryke selv om ingenting er galt. Bygg for det: bekreft at delegeringen navnga riktig organisasjonsnummer hos leverandøren, sjekk så på nytt etter en pause før du konkluderer med at tildelingen feilet, og hold gjentakene avgrenset så en reell feil fortsatt kommer til syne.

Hvilke pakker som erstattet hvilke Altinn 2-roller, og hvorfor den nye modellen delegerer bunter framfor enkeltrettigheter, eies av veiledningen om rollemapping. Og sitter feilene dine rundt en systembruker-forespørsel snarere enn en scope-delegering mellom organisasjoner, går veiledningen om systembrukerfeil gjennom den klyngen symptom for symptom.

Hvordan ser jeg den manglende retten i stedet for en naken 403?

Avvisningen oppstrøms kommer ikke til å begynne å navngi roller for deg, så det praktiske grepet er å slutte å lene seg på den. Still myndighetsspørsmålet separat, før kallet som trenger den, og behandle en manglende rett som en tilstand produktet ditt viser framfor et unntak det fanger. Kjeden over slutter da å være en feilsøkingsøvelse, fordi hvert hopp er noe du kan lese.

Det er det Apiers fullmakt-flate gjør. Statusendepunktet returnerer delegeringstilstanden for et selskap som data: en samlet vurdering som full, partial eller none, scopene som er aktive, de som mangler per prinsipal, og norske fix_steps du kan gi kunden, som navngir hva som skal gis og hvor. En delegering som ville feilet lenger nede som en uforklart 403, dukker opp her som et navngitt gap med en eier.

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 leser delegeringstilstanden for ett selskap, med manglende scopes og fix_steps i kroppen i stedet for i en avvisning.

# 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

// Fullmaktstilstanden som noe du leser: aktive scopes, manglende
// scopes og norske fix_steps, i stedet for en naken 403 lenger nede.
const res = await fetch("https://www.apier.no/api/v1/fullmakt/999999999", {
  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();
// "full" | "partial" | "none", med gapet navngitt per prinsipal.
for (const p of data.principals) {
  console.log(p.display_name, p.delegation_status, p.missing_scopes);
}
console.log(data.overall_status, data.fix_steps);

Ofte stilte spørsmål

Hvem kan delegere et API-scope til en leverandør?

Noen hos kundeorganisasjonen hvis egen myndighet dekker API-et som delegeres. Portalflyten utføres av en nøkkelrolle-innehaver, typisk daglig leder, og ressursen bak scopet bærer en policy som avgjør hvem som kan delegere det. En person kan ikke gi videre en tilgang organisasjonen ikke har, og kan ikke delegere forbi grensene for sin egen rolle.

Hvorfor er scopet ikke delegerbart i det hele tatt?

Fordi API-tilbyderen ikke har åpnet for delegering av det. Et Maskinporten-scope kan bare delegeres gjennom Altinn når tilbyderen har satt en delegeringskilde for det og registrert en tilhørende delegerbar ressurs. Finnes ikke det oppsettet, hjelper verken rolle eller myndighet hos kunden; løsningen ligger hos tilbyderen, ikke hos deg.

Kunden delegerte i portalen. Hvorfor sier API-et fortsatt nei?

Integratører observerer et vindu der en tildeling som er synlig i portalen ennå ikke har nådd API-flaten som evaluerer den. Før du eskalerer, bekreft at delegeringen peker på riktig organisasjonsnummer hos leverandøren, og sjekk så på nytt etter en pause i stedet for å anta at tildelingen feilet. Vedvarer gapet, behandle det som en hendelse og ikke som et rettighetsproblem.

Følger delegeringer fra Altinn 2 med over til Altinn 3?

Ikke pålitelig, og noen er dokumentert å falle bort. Skatteetatens overgangsveiledning navngir tildelinger som utgår over plattformgrensen og må delegeres på nytt, og når Altinn 2 stenger, kan bare de nye tilgangspakkene delegeres. Når en mottaker ikke ser en gammel tildeling i en Altinn 3-flyt, er ny delegering under den nye modellen det første du bør prøve.

Hvordan viser Apier den manglende retten i stedet for en naken 403?

Ved å skille myndighetsspørsmålet fra kallet som trenger den. Fullmakt-endepunktene returnerer delegeringstilstanden som data: en samlet status som full, partial eller none, scopene som er aktive, de som mangler, og norske fix_steps skrevet for å vises til kunden. Integrasjonen din leser hvem som mangler hva før den handler, i stedet for å oppdage det som en uforklart avvisning.