API Scopes-konfigurasjon

Konfigurer tilpassede API-scopes

Tilpassede API-scopes lar deg definere API-nivå klienttilgang til applikasjonens instans-relaterte API-er.

Oversikt

Mens XACML muliggjør granulær tilgangskontroll til de faktiske underliggende ressursene (instanser), implementerer API scope-autorisasjonen enkel autorisasjon av klienter for instans-relaterte 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 applikasjonsrepositoryet ditt.

Eksempel

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

{
  "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

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 applikasjonen. Hvis du vil se resultatene av dette, kan du aktivere Debug-logger i appsettings JSON-filen og kjøre applikasjonen 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

• Autorisasjonsretningslinjer - Lær om XACML-basert autorisasjon
• Autentisering - Forstå autentiseringsmekanismer
• Tekstressurser - Konfigurer tilpassede tekstmeldinger