Sist endret: 29. okt. 2026
Preview: Dette er dokumentasjonen for Altinn Studio v9, som er en forhåndsversjon. Gjeldende versjon er v8. For å se dokumentasjonen for gjeldende versjon, velg v8 i versjonsvelgeren i menyen til venstre.

API Scopes-konfigurasjon

Slik konfigurerer du tilpassede API-scopes for tjenesten.

Tilpassede API-scopes lar deg definere API-nivå klienttilgang til tjenestens instansrelaterte API-er.

Tilgjengelig fra v8.9.0-preview.0
Scope-konfigurasjon håndheves ikke ennå i Storage-API-er. Dette kommer i en fremtidig utgivelse, og dokumentasjonen oppdateres da. Vi varsler på Slack når dette er tilgjengelig.

Oversikt

Mens XACML muliggjør granulær tilgangskontroll til de faktiske underliggende ressursene (instanser), implementerer API-scope-autorisasjonen enkel autorisasjon av klienter for instansrelaterte API-er i appen din. Den inntreffer før XACML-autorisasjonen.

Det finnes innebygde scopes for brukere og tjenesteeiere:

  • altinn:instances.read og altinn:instances.write for brukere (og systembrukere)
  • altinn:serviceowner/instances.read og altinn:serviceowner/instances.write for tjenesteeiere

Disse er “globale”, i den forstand at de gir en klient tilgang til app-API-ene for alle Altinn-apper. Vi støtter konfigurasjon for å gjøre det mulig for apper å ha app-spesifikke scopes, slik at en gitt klient kan hente tilgangstokens som har scopes som er spesifikke for en eller flere apper.

Konfigurasjon

App-spesifikke API-scopes konfigureres i applicationmetadata.json-filen som ligger i App/config/ i app-lageret ditt.

Eksempel

Her er et eksempel på konfigurasjon med en lignende scope-struktur, men med et tilpasset ID-porten scope-prefiks og med [app]-plassholderstøtte (den vil bli erstattet med app-navnet under kjøring).

App/config/applicationmetadata.json
{
  "apiScopes": {
    "users": {
      "read": "<ID-porten prefix>:[app].instances.read",
      "write": "<ID-porten prefix>:[app].instances.write",
      "errorMessageTextResourceKey": "authorization.scopes.insufficient"
    },
    "serviceOwners": {
      "read": "<ID-porten prefix>:[app]/serviceowner/instances.read",
      "write": "<ID-porten prefix>:[app]/serviceowner/instances.write",
      "errorMessageTextResourceKey": "authorization.scopes.insufficient"
    },
    "errorMessageTextResourceKey": "authorization.scopes.insufficient"
  }
}

errorMessageTextResourceKey spesifisert ovenfor er standardverdiene. De kan overstyres på begge nivåer, og de indre nøklene har prioritet hvis de er satt (de er valgfrie). Verdien som løses gjennom tekstressursene blir satt i details-egenskapen i ProblemDetails 403-responsen når scope-autorisasjon ikke lykkes.

Konfigurasjonsegenskaper

EgenskapBeskrivelse
usersDefinerer API-scopes for vanlige brukere
serviceOwnersDefinerer API-scopes for tjenesteeier-klienter
readScope påkrevd for leseoperasjoner
writeScope påkrevd for skriveoperasjoner
errorMessageTextResourceKeyTilpasset feilmeldingsnøkkel (valgfritt)

API-respons

Når scope-autorisasjon feiler, returnerer appen en 403-respons med ProblemDetails-format:

{
    "title": "Forbidden",
    "status": 403,
    "detail": "Insufficient scope",
    "instance": "<request-path>"
}

detail-egenskapen til responsen overstyres gjennom errorMessageTextResourceKey-konfigurasjonen.

Feilsøking

Appen beregner og bufrer nødvendige scopes per API-endepunkt under oppstart av appen. Hvis du vil se resultatene av dette, kan du aktivere Debug-logger i appsettings JSON-filen og kjøre appen på nytt. Da vil den logge en liste over endepunkter og nødvendige scopes per bruker/tjenesteeier. Disse loggene kommer fra ScopeAuthorizationService i bibliotekskoden.

Relatert dokumentasjon