Skip to main content

Maskinporten som konsument

For å registrere en klient som konsument av scopes i Maskinporten har du tre muligheter:

  • Bruke Digdir sin selvbetjeningsløsning. Du søker om tilgang til selvbetjeningsløsningen via Pureservice.
  • Bruke Kubernetes-ressursen MaskinportenClient. Denne ressurstypen er tilgjengelig via Kubernetes-operatoren Digdirator, utviklet av NAV sitt plattformteam (NAIS).
  • Bruke Kubernetes-ressursen SecurityConfig, som er en Kartverket-tilpasset abstraksjon på toppen av Digdirator. Les mer om SecurityConfig i dokumentasjonen for Accesserator. Merk at SecurityConfig-ressursen kun støtter å konsumere scopes i Maskinporten, ikke å eksponere scopes.

En vil typisk velge å bruke SecurityConfig fremfor MaskinportenClient dersom en uansett skal bruke førstnevnte til annen funksjonalitet, som Token Exchange, token-uthenting eller validering med Texas, OPA eller annet.

Skal applikasjonen din i stedet eksponere egne scopes til andre organisasjoner, se Maskinporten som API-tilbyder.

🧪 Testmiljø for Maskinporten​

Digdir tilbyr Maskinporten i et testmiljø, der du kan teste applikasjonen din med syntetiske organisasjoner. For å registrere en klient mot Maskinporten sitt testmiljø så kan du enten gjøre det i Digdir sin selvbetjeningsløsning i test eller opprette en MaskinportenClient-ressurs med consumes-feltet satt i dev-clustrene til SKIP, i.e. atgcp1-dev eller atkv3-dev.

🤖 Klientregistrering med MaskinportenClient​

En MaskinportenClient er en Kubernetes-ressurs som lar brukere deklarativt opprette og vedlikeholde Maskinporten-klientregistreringer. Etter å ha fullført opprettelsen, vil Digdirator opprette en Kubernetes-hemmelighet (Secret) i samme namespace med hemmeligheter som kan brukes av applikasjoner til tilgangsstyring, som for eksempel client_id, private_key_jwt, diverse URL-er og lignende.

Spesifikasjon​

spec (object, required) – Spesifikasjon til MaskinportenClient

secretName (string, required) – Navnet på den resulterende Secret-ressursen som vil bli opprettet.

clientName (string, optional) – Navnet på klienten registrert hos DigDir. Vises under innlogging for brukerorienterte flyter, og er ellers en lesbar måte å skille mellom klienter i DigDirs selvbetjeningsportal.

scopes ([]object, optional) – Definerer hvilke scopes applikasjonen konsumerer.
consumes ([]object, optional) – En liste med scopes din klient kan forespørre tilgang til.

name (string, required) – Scopene som applikasjonen konsumerer for å få tilgang til en ekstern organisasjons API.

Eksempel​

Følgende eksempel oppretter en klientintegrasjon mot Maskinporten som konsumerer scopet <organisasjon>:<scope>, eksemplifisert under med et fiktivt scope fra en ekstern tjeneste. Når registrering er fullført vil Digdirator opprette Kubernetes-hemmeligheten du har satt i secretName.

Klientregistrering mot Maskinporten med Digdirator
apiVersion: nais.io/v1
kind: MaskinportenClient
metadata:
  name: test-client
  namespace: test-namespace
spec:
  clientName: mitt-klientnavn
  secretName: test-client-maskinporten-secret
  scopes:
    consumes:
      - name: "altinn:serviceowner/notifications.create"
      - name: "altinn:serviceowner/notifications.read"
      - name: "skatteetaten:formuesobjektfasteiendom"
Hemmelighet opprettet av Digdirator etter fullført klientregistrering
apiVersion: v1
kind: Secret
metadata:
  name: <navn-på-secret>
  namespace: <mitt-namespace>
data:
  MASKINPORTEN_CLIENT_ID: ++++++++
  MASKINPORTEN_CLIENT_JWK: ++++++++
  MASKINPORTEN_ISSUER: ++++++++
  MASKINPORTEN_JWKS_URI: ++++++++
  MASKINPORTEN_SCOPES: ++++++++
  MASKINPORTEN_TOKEN_ENDPOINT: ++++++++
  MASKINPORTEN_WELL_KNOWN_URL: ++++++++
type: Opaque

🔁 Rullering av hemmeligheter​

Digdirator roterer ikke hemmeligheter automatisk. I stedet fornyes den samme hemmeligheten (og tilhørende JWKS) i det uendelige, slik at samme JWKS kan brukes så lenge klientregistreringen eksisterer. Ønsker du likevel å rullere hemmeligheten har du to muligheter:

Opprette en ny hemmelighet med ny JWKS​

Ved å endre secretName i spec vil Digdirator opprette en helt ny Secret-ressurs med et nytt JWKS. Den gamle hemmeligheten, og den tilhørende JWKS-en, vil fortsette å være tilgjengelig og gyldig så lenge den fremdeles refereres til av kjørende workloads. Dette gjør det mulig å rullere hemmeligheten uten nedetid, ved å:

  1. Opprette en ny hemmelighet med nytt JWKS ved å endre secretName i spec.
  2. Oppdatere alle workloads som bruker den gamle hemmeligheten til å bruke den nye.
  3. Digdirator vil automatisk rydde opp den gamle hemmeligheten når ingen workloads lenger refererer til den.

Rullere hemmeligheten in-place​

Du kan tvinge frem en umiddelbar rullering av hemmeligheten ved å legge følgende annotasjon på ressursen:

metadata:
  annotations:
    digdir.nais.io/rotate: "true"
  ...
spec:
  ...
caution

Merk at denne fremgangsmåten invaliderer den gamle JWKS-en umiddelbart, selv om en kjørende pod fortsatt bruker den. Dette kan medføre nedetid for applikasjonen din dersom ikke alle kjørende pods får hentet den nye hemmeligheten med det samme.

Sørge for at applikasjonen plukker opp den nye hemmeligheten​

Uavhengig av hvilken fremgangsmåte du velger, må applikasjonen din laste inn den oppdaterte hemmeligheten for at rulleringen skal ha noen effekt. Legg følgende annotasjon på din Skiperator-Application for at Reloader automatisk skal rulle ut nye pods når hemmeligheten endres:

apiVersion: skiperator.kartverket.no/v1alpha1
kind: Application
metadata:
  ...
spec:
  podSettings:
    annotations:
      reloader.stakater.com/search: "true"
  ...