Autorisasjonskontekster

Referanseinformasjon om autorisasjonskontekster

Introduksjon

Se komme i gang med autorisasjonskontekster for en funksjonell oversikt over autorisasjonskontekster og hva de kan brukes til. Denne siden dekker hele skrivekontrakten, valideringsreglene og den nøyaktige effekten på sluttbruker-API-et.

Hvor autorisasjonskontekster kan settes

En authorizationContext kan oppgis på tjenesteeierens endepunkter for opprettelse og oppdatering, på disse feltene:

Alle seks delene deler nøyaktig samme authorizationContext-form - et vedlegg eller en navigasjonshandling kan navngi en action på samme måte som en API- eller GUI-handling kan, selv om det i praksis nesten alltid vil stå usatt (se feltet action under).

Dette gjelder både endepunktene for opprettelse og oppdatering av dialoger, og de egne endepunktene for opprettelse og oppdatering av forsendelser.

Selve konteksten kan bare leses tilbake av tjenesteeieren. authorizationContext er med i tjenesteeierens lese-DTO-er (svaret fra dialog-GET-et og tjenesteeierens forsendelsesendepunkter), men finnes ikke på noen sluttbruker-DTO. Dette er en bevisst konfidensialitetsegenskap: en autorisasjonskontekst kan navngi bestemte parter, og å publisere den listen til en sluttbruker ville avslørt hvilke andre parter som kan ha tilgang til en gitt del av dialogen. Sluttbrukere ser bare effekten av en kontekst: isAuthorized, feltene som maskeres eller det at entiteten utelukkes (beskrevet nedenfor), og entitetens oppføring i dialogtokenets e-claim.

GraphQL følger samme mønster: det eksponerer isAuthorized og excluded*-listene på sluttbrukerentitetene, men ikke selve autorisasjonskonteksten.

Uten autorisasjonskontekst

authorizationContext er valgfritt på alle delene. Utelates den, følger entiteten dialogens egen tilgang, evaluert på vegne av dialogens egen part, akkurat som før autorisasjonskontekster fantes:

En slik entitet er ikke oppført i e-claimet i dialogtokenet; handlinger uttrykkes i a-claimet, som før.

Merk forskjellen på å utelate konteksten og en kontekst med bare parties: utelates den, gis samme tilgang som til dialogen, mens en kontekst med bare parties evaluerer kun de oppgitte partene, og utelukker dialogpartens egne folk med mindre en oppføring i dialogPartyChecks tar dem med.

Felt

serviceResource

Type string, valgfritt.

Overstyrer dialogens egen tjenesteressurs for denne ene sjekken, slik at evalueringen rettes mot en annen ressurs’ policy. Når feltet settes, evalueres konteksten som en forespørsel mot bare den ressursen - dialogens egen instansreferanse følger ikke med, på samme måte som ressursoverstyringen i det gamle autorisasjonsattributtet.

Må starte med urn:altinn:resource: og ellers følge det vanlige formatet for Altinn-ressursidentifikatorer. Maks 255 tegn.

Den autentiserte tjenesteeieren må eie ressursen det refereres til. Å referere til en ressurs som den som kaller ikke eier, feiler hele opprettelsen eller oppdateringen med 403 Forbidden.

additionalResourceAttribute

Type string, valgfritt.

Et underressurs- eller oppgaveattributt som matches innenfor den effektive ressursens policy - for eksempel urn:altinn:task:Task_1 eller urn:altinn:subresource:mycustomresource. I motsetning til et gammelt autorisasjonsattributt overstyrer dette aldri ressursen alene; det legges oppå den ressursen som gjelder (dialogens egen, eller den som er satt med serviceResource).

Et bart navn uten et gjenkjent navnerom-prefiks behandles som urn:altinn:subresource:<navn>.

Må ikke starte med urn:altinn:resource: - bruk serviceResource til det. Det kan heller ikke referere til en app (navnerommet urn:altinn:app:, eller en verdi som utvides til en app_{org}_{appId}-identifikator) eller til en organisasjon (urn:altinn:org:): appen bæres allerede av oppføringen i Ressursregisteret som serviceResource navngir, og organisasjonen som eier den effektive ressursen, utledes fra ressursen selv. Samme format- og lengderegler som serviceResource.

parties

Type liste av string, valgfritt.

Andre parter enn dialogens egen som sjekken evalueres på vegne av, hver på sin egen part og uten tilgangsbegrensning. Tilgang gis hvis PDP-en tillater minst én av de oppgitte partene, eller minst én av dialogPartyChecks (ELLER-semantikk), ikke alle sammen.

• Sammen med dialogPartyChecks minst 1 og maks 4 oppføringer.
• Oppføringene må være unike.
• Kan ikke inneholde dialogens egen part. Bruk en oppføring i dialogPartyChecks med accessRestriction: "None" til det - den evaluerer nøyaktig det samme, og samler dialogens part på ett sted, der en tilgangsbegrensning kan gjelde for den.
• Hver oppføring må være en gyldig partsidentifikator: urn:altinn:organization:identifier-no:{orgnr}, urn:altinn:person:identifier-no:{fnr/dnr}, urn:altinn:party-identifier:username:{username}, eller en ID-porten-e-postidentifikator.

En autorisasjonssjekk uten parter eller dialogpartssjekker å evaluere kan aldri bli autorisert - den feiler lukket i stedet for å gi tilgang implisitt.

dialogPartyChecks

Type liste av objekter, valgfritt.

Sjekker som evalueres på vegne av dialogens egen part. Hver sjekk kan kreve at sluttbrukerens tilgang til dialogens part er oppnådd på en bestemt måte, og kan angi sin egen ressurs og handling. Tilgang gis hvis minst én sjekk, eller minst én oppføring i parties, tillater det. Utelates feltet, eller er listen tom, evalueres ikke dialogens egen part i det hele tatt – da gis tilgang bare gjennom partene i parties. Skal dialogpartens folk ha tilgang, må konteksten ha en sjekk, for eksempel { "accessRestriction": "None" }.

Hver sjekk har disse feltene:

Kontekstens additionalResourceAttribute, hvis satt, legges oppå den effektive ressursen til hver sjekk.

Begrensningen evalueres av Altinn Authorization i den samme beslutningsforespørselen, så en sjekk med begrensning koster én evaluering, akkurat som en uten.

Et typisk bruksområde er en dialog der flere mellommenn opptrer for den samme parten, og hver mellommann bare skal se «sine» forsendelser:

{
  "transmissions": [
    {
      // Synlig for dialogpartens egne folk, og for den som opptrer for den gjennom regnskapsbyrå 1
      "authorizationContext": {
        "dialogPartyChecks": [
          { "accessRestriction": "DirectAndHierarchy" },
          { "accessRestriction": "ClientDelegation", "viaParty": "urn:altinn:organization:identifier-no:912345678" }
        ],
        "unauthorizedPresentation": "Excluded"
      }
    },
    {
      // Synlig for dialogpartens egne folk, og for den som opptrer for den gjennom regnskapsbyrå 2
      "authorizationContext": {
        "dialogPartyChecks": [
          { "accessRestriction": "DirectAndHierarchy" },
          { "accessRestriction": "ClientDelegation", "viaParty": "urn:altinn:organization:identifier-no:987654321" }
        ],
        "unauthorizedPresentation": "Excluded"
      }
    }
  ]
}

Regler for listen som helhet:

• To sjekker kan ikke evaluere det samme: sjekker med samme accessRestriction, viaParty, effektive serviceResource og effektive action avvises som duplikater. Ved sammenligningen faller en sjekks serviceResource og action tilbake til kontekstens, og action videre til read. Dialogens egen ressurs fylles ikke inn, fordi en sjekk som navngir den eksplisitt evalueres uten dialogens instansreferanse, og dermed er en annen forespørsel (se serviceResource).
• En DirectAndHierarchy- eller ClientDelegation-sjekk avvises hvis det også finnes en None-sjekk for den samme effektive ressursen og handlingen, siden None-sjekken allerede gir alt den begrensede ville gitt.

includeDialogParty: true kombinert med additionalResourceAttribute var tidligere den direkte erstatningen for et gammelt underressursattributt; det tilsvarende er nå dialogPartyChecks: [{ "accessRestriction": "None" }] kombinert med additionalResourceAttribute.

action

Type string, valgfritt, på alle delene - det finnes ingen del der feltet er påkrevd eller utilgjengelig.

XACML-handlingen som skal evalueres. Hvis feltet utelates, brukes read som standard.

I motsetning til det gamle autorisasjonsattributtet utledes action aldri fra serviceResource eller additionalResourceAttribute. Å avgrense hvilken ressurs sjekken gjelder, avgrenser ikke hvilken handling den gjelder. En kontekst som setter additionalResourceAttribute og lar action stå usatt, evaluerer likevel et rent read på den avgrensede ressursen, og hvis det allerede finnes en bredere read-regel på hovedressursen, kan den fortsatt matche - XACML-målmatching kontrollerer bare at attributtene en regel krever er til stede, ikke at ingen andre attributter er det, så det ekstra ressursattributtet utelukker ikke i seg selv den bredere regelen. For å faktisk avgrense tilgangen, gi konteksten en egen action - for eksempel elementread - og skriv (eller gjenbruk) en policyregel som matcher på den handlingen sammen med den avgrensede ressursen.

Maks 255 tegn.

I sluttbruker-API-et rapporterer action-feltet på entiteten alltid handlingen som faktisk ble evaluert: kontekstens action når den navngir en, og read når den ikke gjør det. I tjenesteeier-API-et holdes de to fra hverandre - det gamle action-feltet på øverste nivå leses tilbake som en tom streng for en entitet som bruker en kontekst, og den evaluerte handlingen finner du i authorizationContext.action.

tokenRef

Type string, valgfritt. Maksimalt 50 tegn; kan ikke være blankt når det er satt.

En referanse du velger selv, som identifiserer denne konteksten i dialogtokenet. Når sluttbrukeren er autorisert for konteksten, lister tokenets e-claim opp denne verdien i stedet for ID-en til entiteten som har konteksten, slik at en mottakende tjeneste kan gjenkjenne rettigheten uten å holde styr på Dialogportens entitets-ID-er. Flere kontekster kan dele samme tokenRef; det er tillatt, og tokenet lister den da opp én gang - nyttig når den mottakende tjenesten skal sjekke én referanse for en hel gruppe entiteter. Dialogporten sjekker ikke tokenRef for unikhet eller for kollisjoner med entitets-ID-er, siden både kontekstene og sjekken på mottakersiden er dine; pass på å ikke gjenbruke en referanse for entiteter som skal autoriseres hver for seg.

tokenRef leses tilbake på tjenesteeierflaten sammen med resten av konteksten, og eksponeres aldri for sluttbrukere på annen måte enn gjennom tokenet.

unauthorizedPresentation

Type string-enum, verdiene Disabled eller Excluded. Påkrevd.

Selv om feltet ikke er markert som påkrevd i OpenAPI-schemaet, blir det avvist ved validering å utelate det - det finnes ingen standardverdi. Det må settes eksplisitt til en av de to verdiene under.

• Disabled (sperret) lar entiteten bli liggende i listen den hører til, men maskerer URL-ene og de innebygde innholdsreferansene. Dette tilsvarer måten det gamle autorisasjonsattributtet alltid har oppført seg på, og er den anbefalte verdien når du migrerer en eksisterende dialog uten å ønske å endre hva sluttbrukere ser.
• Excluded (utelukket) fjerner entiteten helt fra den listen, og lar bare id og createdAt stå igjen i en excluded*-liste ved siden av. Se de to neste avsnittene for den nøyaktige effekten.

Hva en uautorisert sluttbruker ser

Disabled: blir liggende, URL-ene maskeres

Entiteten blir liggende der den er i listen sin, isAuthorized er false, og entiteten står ikke i dialogtokenets e-claim. Alt entiteten forteller om seg selv, er fortsatt lesbart; bare det som ville latt sluttbrukeren handle på den, erstattes.

URL-er erstattes med én av to plassholderverdier: urn:dialogporten:unauthorized ved nektet tilgang, og urn:dialogporten:expired for en utløpt URL på et vedlegg eller en navigasjonshandling - men plassholderen for utløpt brukes bare når den som spør er autorisert; en URL som både er uautorisert og utløpt, viser plassholderen for uautorisert.

Excluded: fjernet fra listen sin

Entiteten er ikke med i svaret i det hele tatt. Det finnes ingen oppføring med isAuthorized: false å finne, og ingen oppføring i dialogtokenets e-claim. Det eneste som står igjen, er en stubb i en liste ved siden av, med to felt og ikke noe mer:

{
  "id": "0194a1b2-3c4d-7e5f-8a9b-0c1d2e3f4a5b",
  "createdAt": "2026-01-15T09:12:44.512Z"
}

createdAt er det som lar et sluttbrukersystem plassere hullet: systemet kan vise at noe det ikke får se, ligger mellom to forsendelser det får se, i stedet for å vise en liste som stille er blitt kortere.

Hver liste som kan ha en autorisasjonskontekst, har sin egen skyggeliste, oppkalt etter den og plassert rett ved siden av:

Alle seks kan være null og utelates helt fra JSON-en når ingenting er utelukket, noe som er det normale - behandle en liste som mangler, på nøyaktig samme måte som en tom liste. GraphQL eksponerer de samme seks feltene, med typen [ExcludedElement!].

{
  "transmissions": [
    {
      "id": "...",
      "attachments": [ /* ... */ ],
      "navigationalActions": [ /* ... */ ],
      "excludedAttachments": [ { "id": "...", "createdAt": "..." } ],
      "excludedNavigationalActions": [ { "id": "...", "createdAt": "..." } ]
    }
  ],
  "guiActions": [ /* ... */ ],
  "apiActions": [ /* ... */ ],
  "attachments": [ /* ... */ ],
  "excludedTransmissions": [ { "id": "...", "createdAt": "..." } ],
  "excludedGuiActions": [ /* ... */ ],
  "excludedApiActions": [ /* ... */ ],
  "excludedAttachments": [ /* ... */ ]
}

Fire ting som er verdt å ha i bakhodet:

1. isAuthorized: false betyr nøyaktig én ting. Det markerer en entitet som finnes, er beskrevet og ikke kan brukes - aldri en entitet som holdes tilbake. En utelukket entitet er rett og slett borte.
2. En utelukket forsendelse tar med seg de underliggende delene sine. Bare forsendelsens egen stubb dukker opp; vedleggene og navigasjonshandlingene rapporteres ikke separat, verken i skyggelistene til den forsendelsen eller andre steder. Et vedlegg eller en navigasjonshandling med sin egen Excluded-kontekst inni en forsendelse som bare er Disabled (og nektet), utelukkes derimot individuelt, til skyggelisten på den forsendelsen.
3. Innhold på dialognivå (content.mainContentReference) styres ikke av noen autorisasjonskontekst i det hele tatt - dialoginnhold har ingen egen kontekst. Synligheten avhenger utelukkende av om den som spør har lesetilgang til dialogens hovedressurs.

Slik oppfører endepunktene seg for utelukkede forsendelser

Foreldre-først-avgrensing

En underordnet autorisasjonskontekst kan bare avgrense tilgang, aldri utvide den. Tilgang til forelderen er alltid en forutsetning:

• For en forsendelses vedlegg og navigasjonshandlinger er forsendelsens egen autorisasjon forutsetningen - en tillatende underordnet kontekst inni en nektet forsendelse gir ingenting, og den underordnede delen står ikke i dialogtokenets e-claim uansett hva den underordnede konteksten alene ellers ville tillatt.
• For vedlegg på dialogen er forutsetningen lesetilgang til dialogens hovedressurs. Et vedlegg på dialogen uten egen kontekst begrenses aldri individuelt - det arver dialogens egen tilgang.

Hvis den som spør ikke kan lese dialogens hovedressurs i det hele tatt, feiler GET /dialogs/{id} med 403 Forbidden før noen vurdering per entitet kjøres, med mindre listeautorisasjon gir en snevrere form for tilgang - i så fall returneres dialogen med handlingene sine markert som uautoriserte i stedet for at forespørselen avvises helt. De frittstående forsendelsesendepunktene har ingen slik reserveløsning: uten tilgang til hovedressursen svarer de 404 Not Found, som om dialogen ikke fantes.

Evaluering med flere parter

• Tilgang til en sjekk gis hvis minst én av evalueringene tillater det - ELLER-semantikk på tvers av både parties og dialogPartyChecks.
• Hver oppføring i parties og hver dialogpartssjekk er én evaluering. Like evalueringer, innenfor eller på tvers av entiteter, slås sammen til én, men grensen på 4 oppføringer per kontekst er likevel en reell kostnadskontroll: hver distinkte kombinasjon av ressurs, handling, part og tilgangsbegrensning er én evaluering mot Altinn Authorization, og en dialog med mange autorisasjonskontekster øker dette raskt.
• En tilgangsbegrensning gjelder bare evalueringen den er satt på. Siden evalueringene kombineres med ELLER, ville en ubegrenset evaluering av dialogens egen part ved siden av en begrenset gjort begrensningen meningsløs - derfor kan ikke parties inneholde dialogens egen part, og derfor kan ikke en begrenset sjekk kombineres med en None-sjekk for den samme rettigheten.
• Hvis samsvaret mellom forespurte sjekker og returnerte beslutninger av en eller annen grunn ikke stemmer, nektes alle sjekker for den berørte forespørselen - systemet feiler lukket i stedet for å gjette.
• En systembrukers egen part evalueres med systembrukerens egen identitet; parter som er navngitt direkte i en konteksts parties-liste evalueres som seg selv og vil rett og slett bli nektet hvis PDP-en ikke anerkjenner dem som delegerbare til den som kaller - en systembruker kan ikke representere en vilkårlig part ved å navngi den i en kontekst.

Gjensidig utelukkelse med authorizationAttribute

En entitet kan ikke kombinere authorizationContext med det gamle feltet authorizationAttribute:

• På API-handlinger og GUI-handlinger må authorizationAttribute være fraværende når authorizationContext er satt, og det øverste action-feltet må også være fraværende eller tomt - bruk authorizationContext.action i stedet. Motsatt er action påkrevd når det ikke finnes noen kontekst. I tjenesteeier-API-et leses en slik entitet tilbake med action som en tom streng, slik at et GET-svar kan sendes rett tilbake til PUT uendret.
• På forsendelser må authorizationAttribute være fraværende når authorizationContext er satt. Det finnes ikke noe øverste action-felt på forsendelser.
• Vedlegg og navigasjonshandlinger på forsendelser har aldri hatt authorizationAttribute - bare authorizationContext.

De samme reglene gjelder på oppdateringsendepunktene og på de egne endepunktene for opprettelse og oppdatering av forsendelser.

Migrere fra authorizationAttribute

action: "elementread" på rad én, to og fire er et eksempel på et selvvalgt navn, ikke et fast navn - se neste punkt.

Fem ting du bør være klar over ved migrering:

1. Gamle autorisasjonsattributter utleder ikke lenger en egen handling for avgrensing til underressurs eller oppgave. De utledet tidligere transmissionread i det tilfellet, nettopp for at forespørselen ikke skulle treffe en bredere read-regel på hovedressursen ved et uhell; den utledningen er borte, og hvert gammelt attributt utleder nå et rent read, uansett hva det refererer til. En underressurs eller oppgave navngitt i et gammelt attributt kan derfor bare utvide tilgang gjennom en egen policyregel, aldri avgrense den - se bruke autorisasjonsattributter på forsendelser. Hvis du var avhengig av transmissionread for å avgrense en forsendelses synlighet, og vil fortsette med det etter migrering, gi autorisasjonskonteksten en egen, distinkt action (elementread i tabellen ovenfor er bare et eksempelnavn) og oppdater policyen din til å matche på den handlingen i stedet for transmissionread - authorizationContext.action er det eneste stedet en avgrensende handling fortsatt kan navngis.
2. En relatert oppførselsendring gjelder gamle entiteter uansett om du migrerer dem eller ikke. Autorisasjon for en gammel handling uten authorizationAttribute krever nå at handlingen er tillatt på nøyaktig den ressursen entiteten refererer til. Tidligere kunne dette også oppfylles av at en annen entitet i samme dialog hadde den handlingen tillatt på en eller annen ressurs, inkludert dialogens hovedressurs - noe som blant annet betydde at en write-GUI-handling uten autorisasjonsattributt kunne bli tillatt bare fordi en urelatert entitet i dialogen også hadde et tillatt write. Den trenger nå write spesifikt på hovedressursen. Dette er en feilretting snarere enn en levende migreringsrisiko i dag, men en fremtidig policy utformet på den gamle måten ville blitt påvirket - hvis tjenesten din bruker flere ulike handlinger på tvers av entiteter i samme dialog, kan det være verdt å dobbeltsjekke policyene dine.
3. unauthorizedPresentation har ingen tilsvarende gammel verdi og må velges eksplisitt. Den gamle oppførselen (maskere URL-er, beholde innhold) tilsvarer Disabled. Å migrere med Excluded i stedet er en synlig endring for sluttbrukere, og en systemene deres må være forberedt på: entiteten forsvinner ut av listen den lå i.
4. Rettigheten flytter fra a-claimet til e-claimet. Så snart en entitet får en autorisasjonskontekst, forsvinner rettigheten fra listen over autoriserte handlinger i dialogtokenet (a), og entiteten listes i stedet opp i tokenets e-claim ved ID eller tokenRef - en mottakende tjeneste som autoriserer utelukkende ut fra a, vil begynne å nekte forespørsler for den entiteten. Sørg for at mottakersiden sjekker e (se referansen for dialogtoken) før du migrerer.
5. En forskjell på trådnivå i ressursattributtet er lett å overse. For authorizationAttribute har Dialogporten alltid sendt et underressursattributt i den underliggende autorisasjonsforespørselen - en sentinelverdi, main, når det ikke ble oppgitt noe attributt i det hele tatt. En autorisasjonskontekst som verken setter serviceResource eller additionalResourceAttribute (ren avgrensing til part), sender ikke noe underressursattributt i det hele tatt. En policyregel som matcher spesifikt på at underressursattributtet er main, vil slutte å matche etter at du migrerer til en ren partsavgrenset kontekst. Policyer som ikke refererer til attributtet, påvirkes ikke.

Valideringsfeil

Kontraktreferanse

Én oppføring i dialogPartyChecks:

Stubben som brukes i de seks excluded*-listene i sluttbruker-API-et:

Les mer

• Lær hvordan autorisasjonskontekster gir finkornet tilgangskontroll med flere parter på enkelte deler av en dialog
• Referanseinformasjon om dialogtoken
• Referanseinformasjon om autorisasjonsattributter