Autorisasjonsregler

En AuthPolicy beskytter i utgangspunktet alle paths og HTTP-metoder i applikasjonen, og krever et gyldig token. Autorisasjonsreglene bygges opp i følgende rekkefølge:

1. ignoreAuthRules åpner opp paths og HTTP-metoder som skal være tilgjengelige uten token.
2. Alt annet krever et gyldig token.
3. baselineAuth stiller ytterligere krav til claims i tokenet for alle beskyttede endepunkter.
4. authRules stiller ytterligere krav til claims i tokenet for spesifikke paths og HTTP-metoder.

🔑 Hva er et gyldig token?

Et token regnes som gyldig dersom alle følgende krav er oppfylt:

• Signatur: Tokenet er signert med en nøkkel fra tokenutstederens eller identitetstilbyderens JWKS, som hentes fra jwks_uri i discovery-dokumentet på spec.wellKnownURI.
• Utsteder (iss): iss-claimet er nøyaktig lik issuer i discovery-dokumentet på spec.wellKnownURI.
• Audience (aud): aud-claimet inneholder minst én av verdiene i spec.allowedAudiences.
• Utløp (exp): Tokenet er ikke utløpt.
• Ikke før (nbf): Tokenet er ikke tatt i bruk før tidspunktet angitt i nbf-claimet, dersom det er satt.

🧱 Oppbygging av autorisasjonsregler

1. ignoreAuthRules: åpne endepunkter

ignoreAuthRules spesifiserer paths og HTTP-metoder som skal være tilgjengelige uten token, som f.eks. statiske ressurser, helsesjekker eller offentlig API-dokumentasjon. Dersom methods utelates, gjelder regelen for alle HTTP-metoder.

spec:
  ignoreAuthRules:
    - paths:
        - /public/{**}
    - paths:
        - /feedback
      methods:
        - GET
        - POST

Kombinasjoner av path og metode som ikke dekkes av en regel er ikke åpne. I eksemplet over krever f.eks. DELETE /feedback fortsatt et gyldig token.

2. Alt annet krever et gyldig token

Alle paths og HTTP-metoder som ikke er åpnet med ignoreAuthRules krever et gyldig token. Dette gjelder uten at du trenger å konfigurere noe.

3. baselineAuth: krav for alle beskyttede endepunkter

baselineAuth stiller krav til claims i tokenet som gjelder for alle beskyttede endepunkter, altså alt som ikke er åpnet med ignoreAuthRules. Dette inkluderer også endepunkter som dekkes av authRules.

spec:
  baselineAuth:
    claims:
      - claim: groups
        values:
          - my-user-group

4. authRules: krav for spesifikke endepunkter

authRules stiller ytterligere krav til claims i tokenet for spesifikke paths og HTTP-metoder. Kravene i authRules gjelder i tillegg til kravene i baselineAuth, og overstyrer dem ikke.

spec:
  authRules:
    - paths:
        - /admin/{**}
      when:
        - claim: role
          values:
            - admin

caution

Regler i authRules overskriver regler i ignoreAuthRules. Det betyr at du må være påpasselig med at uttrykk for paths i authRules, særlig ved bruk av wildcards, ikke overlapper med paths du ønsker skal være åpne.

Wildcards i paths

paths støtter ikke regulære uttrykk, men såkalte path-templates med to operatorer:

• {*} treffer nøyaktig ett path-segment. /api/{*}/users treffer /api/v1/users, men ikke /api/v1/beta/users.
• {**} treffer null eller flere path-segmenter, og må være siste operator i pathen. /api/{**} treffer bl.a. /api/users og /api/users/123.

Den mest korrekte bruken er å la operatoren utgjøre et helt path-segment bak en /, f.eks. /api/{*}/users og /public/{**}. Da matches paths på segmentgrenser, og du unngår å treffe paths du ikke hadde tenkt å treffe. Ønsker du at også /public skal treffes, legger du den til som en egen path:

paths:
  - /public
  - /public/{**}

Ztoperator støtter også {**} direkte etter en tekst i siste segment, f.eks. /public{**}. Dette tolkes som et prefiks-treff, som betyr at alle paths som starter med /public treffes, uavhengig av segmentgrenser. /public{**} treffer dermed /public og /public/123, men også /publication og /public-admin. Denne syntaksen kan ikke kombineres med andre operatorer i samme path.

OR- og AND-logikk for claims

Kravene i baselineAuth.claims og authRules[].when evalueres likt:

• Innenfor ett krav er det tilstrekkelig at claimet inneholder én av de oppgitte verdiene (OR).
• Mellom flere krav må alle være oppfylt (AND). Dette gjelder også på tvers av baselineAuth og authRules.

OR: flere values i samme claim

Regelen nedenfor vil godta tokenet dersom claimet groups inneholder enten group-a eller group-b:

spec:
  baselineAuth:
    claims:
      - claim: groups
        values:
          - group-a
          - group-b

AND: ulike values under ulike claim-blokker

Regelen nedenfor vil godta tokenet dersom claimet groups inneholder både group-a og group-b:

spec:
  baselineAuth:
    claims:
      - claim: groups
        values:
          - group-a
      - claim: groups
        values:
          - group-b

📋 Komplett eksempel

apiVersion: ztoperator.kartverket.no/v1alpha1
kind: AuthPolicy
spec:
  ignoreAuthRules:
    - paths:
        - /public/{**}
    - paths:
        - /feedback
      methods:
        - GET
        - POST
  baselineAuth:
    claims:
      - claim: groups
        values:
          - my-user-group
  authRules:
    - paths:
        - /admin/{**}
      when:
        - claim: role
          values:
            - admin
        - claim: groups
          values:
            - my-admin-group
  ... # øvrige påkrevde/valgfrie felter

I dette eksemplet vil følgende autorisasjonsregler gjelde:

Forespørsel	Krav
Alle understier av /public/...	Ingen, åpent uten token
GET og POST til /feedback	Ingen, åpent uten token
PUT, PATCH, DELETE m.fl. til /feedback	Gyldig token med groups som inneholder my-user-group
Alle understier av /admin/...	Gyldig token med role: admin, og groups som inneholder både my-user-group og my-admin-group
Alle andre paths	Gyldig token med groups som inneholder my-user-group