Ztoperator

Deprecation warnings

Ztoperator har aktive deprecation warnings, se deprecation warnings for mer informasjon.

• Bruk av wildcards * i paths vil fjernes til fordel for eksplisitt syntaks med {*} og {**}

Ztoperator er en Kubernetes-operator som lar deg deklarativt definere hvordan tilgang til en applikasjons endepunkter skal styres. Dette gjøres med en AuthPolicy-ressurs, som peker på en tilhørende Skiperator-applikasjon. Den gir støtte for å

• definere hvilke endepunkter som skal være åpne.
• definere hvilke endepunkter som krever et gyldig OAuth 2.0-token.
• definere hvilke endepunkter som krever spesifikke claims.
• definere hvilke endepunkter som skal omdirigere brukeren til innlogging.

Ztoperator konfigureres opp mot en identitetstilbyder med feltet spec.wellKnownURI, som peker til et OpenID Connect Discovery Document. Dette dokumentet inneholder informasjon om hvordan Ztoperator skal kommunisere med identitetstilbyderen, slik som endepunkter for autentisering, tokenvalidering og utlogging. Hvilke identitetstilbydere Ztoperator støtter per nå kan ses under Støttede identitetstilbydere.

Hvordan du definerer autorisasjonsregler er dokumentert under Autorisasjonsregler. Hvilke felter som eksisterer og deres oppførsel er dokumentert i API Reference. Hvordan du kan teste og verifisere oppførselen til en AuthPolicy finner du under Test din Ztoperator-AuthPolicy.

🧩 Forutsetninger

Før du kan bruke Ztoperator til å beskytte tjenesten din må følgende være på plass:

• Du må vite hvilken OAuth 2.0-identitetstilbyder som passer for din tjeneste og registrere en klient hos denne. Se her for en oversikt over hvilke identitetstilbydere som støttes av Ztoperator på SKIP.
• Du må vite hvilket well-known endepunkt, audience og eventuelle claims som gjelder for applikasjonen din.
• Den beskyttede applikasjonen må kjøre på SKIP.

caution

Ztoperator registrerer ikke en OIDC-klient for deg. Du må selv ha etablert en integrasjon mot valgt identitetstilbyder, og Ztoperator brukes kun til å beskrive hvordan appen skal beskyttes og håndtere eventuelle innloggingsflyter.

🔐 Verifiser at Ztoperator beskytter din Skiperator-applikasjon

Siden Ztoperator er en kritisk komponent mtp. sikkerheten og tilgangsstyringen til en applikasjon finnes det mekanismer på SKIP som hindrer oppstart av applikasjonen dersom tilhørende AuthPolicy-ressurs ikke er klar. Du aktiverer dette ved å legge en annotasjon på din Skiperator-applikasjon:

apiVersion: skiperator.kartverket.no/v1alpha1
kind: Application
metadata:
  name: my-app
spec:
  podSettings:
    annotations:
      ztoperator.kartverket.no/verify-authpolicy: "true"
  ...

Tilfeller der mekanismen hindrer oppstart vil utarte seg ved at Skiperator-applikasjonen sitt ReplicaSet er unhealthy, og det ikke dukker opp noen Pod-ressurser for applikasjonen.

Merk at dette kun vil hindre oppstart av nye pods, og ikke hindre eksisterende pods fra å fungere som før. Dette er altså mest nyttig i tilfeller der en applikasjon spinnes opp for første gang. Team Tilgangsstyring håper å utvide valideringen i fremtiden til å verifisere kontinuerlig, også under kjøring, at en pod har korreket konfigurasjon i henhold til dens tilhørende AuthPolicy-ressurs.

🚀 Innlogging og utlogging med Ztoperator

Det går an å konfigurere Ztoperator til å håndtere innlogging og utlogging av sluttbrukere på vegne av applikasjonen din. Dette gjøres ved å sette opp spec.autoLogin og spec.oAuthCredentials i Ztoperator-AuthPolicy-ressursen din. spec.autoLogin konfigurerer ulike endepunkter brukt i innloggings -og utloggingsflyten, mens spec.oAuthCredentials peker til en Kubernetes-hemmelighet som inneholder klient-ID client_id og klienthemmelighet client_secret for en registrert OIDC-klient hos identitetstilbyderen.

En annen ting å merke seg er at Ztoperator ikke har lov til å laste inn hemmeligheter som brukes for innlogging i den beskyttede applikasjonen. For å løse dette er man nødt til å legge til en konfigurasjon på den beskyttede Skiperator-applikasjonen for at innloggingshemligheter som Ztoperator håndterer skal kunne lastes inn. Følgende eksempel viser hvordan dette kan gjøres i en Skiperator-applikasjon. Det er viktig at <NAVN PÅ AUTHPOLICY> erstattes med navnet på din Ztoperator-AuthPolicy. Hvis din AuthPolicy for eksempel heter my-auth-policy, så må du sette secretName: my-auth-policy-envoy-secret.

OBS

For at innlogging skal fungere med Ztoperator, må den beskyttede Skiperator-applikasjonen oppdateres med spec.podSettings.annotations.sidecar.istio.io/userVolume og spec.podSettings.annotations.sidecar.istio.io/userVolumeMount.

Skiperator-applikasjon med Ztoperator-innlogging

apiVersion: skiperator.kartverket.no/v1alpha1
kind: Application
metadata:
  name: myapp
spec:
  podSettings:
    annotations:
      sidecar.istio.io/userVolume: |
        [
          {
            "name": "istio-oauth2",
            "secret": {
              "secretName": "<NAVN PÅ AUTHPOLICY>-envoy-secret"
            }
          }
        ]
      sidecar.istio.io/userVolumeMount: |
        [
          {
            "name": "istio-oauth2",
            "mountPath": "/etc/istio/config",
            "readonly": true
          }
        ]
  image: ghcr.io/kartverket/myapp:latest
  port: 8080
  ingresses:
    - myapp.atkv3-dev.kartverket-intern.cloud
  redirectToHTTPS: true
  accessPolicy:
    inbound: 
      rules:
        - application: myjob-skipjob

Lengre brukersesjoner med offline_access og refresh-tokens

Som standard vil en brukersesjon utløpe når access-tokenet fra identitetstilbyderen utløper. For applikasjoner som krever lengre sesjoner uten at brukeren skal måtte logge inn på nytt, kan scopet offline_access legges til i spec.autoLogin.scopes. Dette ber identitetstilbyderen om å utstede et refresh-token i tillegg til access-tokenet.

Ztoperator vil automatisk bruke refresh-tokenet til å hente nye access-tokens i bakgrunnen når det eksisterende utløper, slik at brukeren holdes innlogget uten avbrudd.

Sikkerhetshensyn

Refresh-tokens gir langvarig tilgang, som kan ha konsekvenser og muliggjøre misbruk. Sørg for at du kun bruker offline_access når det er et reelt behov for lengre sesjoner.

Du kan ta i bruk offline_access i din AuthPolicy ved å legge det til i spec.autoLogin.scopes-listen:

AuthPolicy med offline_access for lengre sesjoner

apiVersion: ztoperator.kartverket.no/v1alpha1
kind: AuthPolicy
metadata:
  name: min-authpolicy
spec:
  autoLogin:
    enabled: true
    logoutPath: /logout
    redirectPath: /oauth2/callback
    scopes:
      - offline_access
      ...
  ...

Når offline_access er inkludert i scopes, vil flyten se slik ut:

1. Brukeren logger inn og identitetstilbyderen returnerer både et access-token og et refresh-token.
2. Ztoperator lagrer refresh-tokenet kryptert i session-cookien på klientsiden.
3. Når access-tokenet er utløpt eller ikke lenger tilgjengelig, bruker Ztoperator automatisk refresh-tokenet til å hente et nytt access-token via token refresh-flyten (RFC 6749) – uten at brukeren merker noe.
4. Sesjonen varer inntil refresh-tokenet selv utløper eller trekkes tilbake av identitetstilbyderen.

🎬 Tutorials

I denne docsen finner du en rekke tutorials på hvordan du tar i bruk Ztoperator for å beskytte en applikasjon på SKIP.

• Eksempeloppsett av Ztoperator: Microsoft Entra ID
• Eksempeloppsett av Ztoperator: ID-Porten
• Eksempeloppsett av Ztoperator: Ansattporten

🛠 Støttede identitetstilbydere

Miljø	Identitetstilbyder	wellKnownURI
PROD	Microsoft Entra ID (Kartverket)	https://login.microsoftonline.com/7f74c8a2-43ce-46b2-b0e8-b6306cba73a3/v2.0/.well-known/openid-configuration
TEST	ID-porten	https://test.idporten.no/.well-known/openid-configuration
PROD	ID-porten	https://idporten.no/.well-known/openid-configuration
TEST	Maskinporten	https://test.maskinporten.no/.well-known/oauth-authorization-server
PROD	Maskinporten	https://maskinporten.no/.well-known/oauth-authorization-server
TEST	Ansattporten	https://test.ansattporten.no/.well-known/openid-configuration
PROD	Ansattporten	https://ansattporten.no/.well-known/openid-configuration

⚠️ Deprecation warnings

Ny syntaks for wildcards i paths

Støtte for frittstående wildcards * i paths vil fjernes innen kort tid. Bruk eksplisitt syntaks som enten matcher èn {*} eller flere {**} path-segmenter:

kind: AuthPolicy
spec:
  ignoreAuthRules:
    - paths:
        # vilkårlig mange path-segmenter
        - /{**}
        # ett vilkårlig path-segment
        - /{*}
        # komplett eksempel
        - /api/{*}/endpoint/{**}