Skip to main content

Klientregistrering

Før du går i gang med å sikre din applikasjon med Ztoperator, så trenger du en klientregistrering hos en identitetstilbyder. Klientregistrering er en sentral del av tilgangsstyring med OAuth 2.0 og OIDC. Når du registrerer en klient, får applikasjonen sin egen identitet og kan autentisere seg mot de valgte identitetstilbyderne.

Når du skal opprette en klientregistrering bør du vurdere hvilken identitetstilbyder som passer best til behovene i din applikasjon. For applikasjoner på SKIP står valget da oftest mellom:

  • Microsoft Entra ID: Brukes når applikasjonen er ment for internt bruk i Kartverket, og brukerne er ansatte i Kartverket.
  • ID-porten: Egnet for borgertjenester som skal brukes av Ola og Kari Nordmann.
  • Maskinporten: Benyttes når applikasjonen tilbyr et API for andre offentlige virksomheter eller når man ønsker å konsumere andre API-er som benytter seg av Maskinporten.
  • Andre: Hvis identitetstilbyderne over ikke treffer dine behov anbefaler vi deg å ta kontakt med Team Tilgangsstyring på #gen-tilgangsstyring på Slack.

Audience er et begrep innen OAuth 2.0 som spesifiserer tiltenkt mottaker av et aksess-token. Det er ofte en unik ID (UID) eller en unik URL. Hver klientregistrering får sitt eget audience, og vi anbefaler å ha et bevisst forhold til hvilke tjenester som skal dele samme audience. Det er ofte mer hensiktsmessig å velge en restriktiv tilnærming, der hver tjeneste får sin egen klientregistrering, fremfor å gruppere flere tjenester under én felles klient. Dette gir bedre kontroll over tilgangsstyring og sikkerhet.

Felles for alle identitetstilbydere på SKIP er at klientregistrering støttes fra plattformen ved hjelp av Kubernetes-operatorer.

  • Digdirator håndterer klientregistrering mot Digdir sine fellesløsninger: ID-Porten og Maskinporten.
  • Azurerator håndterer klientregistrering mot Microsoft Entra ID (tidligere kjent som Azure Active Directory).

Når man bruker Digdirator eller Azurerator for å opprette en klientintegrasjon, blir det opprettet en Kubernetes-hemmelighet (Secret) i samme namespace med integrasjonshemmeligheter. Disse kan brukes av applikasjoner til bl.a. å logge inn brukere, hente maskin-til-maskin-tokens og validere innkommende JWT-er på forespørsler.

🪪 Digdirator​

Digdirator er en Kubernetes-operator utviklet av NAV sitt plattformteam (NAIS) som skal gjøre det enkelt å deklarativt sette opp og vedlikeholde integrasjoner mot Digdir sine systemer. Dette inkluderer ID-Porten-integrasjoner og Maskinporten-integrasjoner.

Digdirator introduserer to CRD-er, IDPortenClient og MaskinportenClient, som automatiserer opprettelse og vedlikehold av integrasjoner mot henholdsvis ID-porten og Maskinporten. Alternativt kan klientregistrering gjøres direkte i et Skiperator-applikasjonsmanifest. Se her for mer informasjon om hvordan du setter opp ID-porten- og/eller Maskinporten-integrasjoner via Skiperator.

IDPortenClient​

En IDPortenClient er en CRD som lar brukere deklarativt opprette og vedlikeholde ID-Porten-klientregistreringer.

spec (object, required) – Spesifikasjon til IDPortenClient

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

integrationType (string, optional) – Definerer integrasjonstypen for klienten. Bestemmer hvilke scopes som kan registreres. Kan ikke endres etter opprettelse. Tillatte verdier: krr, idporten, api_klient.

scopes ([]string, optional) – Definerer OAuth2-scopes for klienten. Begrenset basert på integrationType.

frontchannelLogoutURI (string, optional) – URL som ID-porten omdirigere til når en utlogging utløses av en annen applikasjon.

postLogoutRedirectURIs ([]string, optional) – Liste over gyldige URI-er hvor ID-porten kan omdirigere etter utlogging.

redirectURIs ([]string], optional) – Liste over redirect URI-er som skal registreres hos DigDir.

accessTokenLifetime (integer, optional) – Maksimal levetid i sekunder for access_token som returneres fra ID-porten. Min: 1, maks: 3600.

clientURI (string, optional) – URL til klienten brukt av DigDir når en 'tilbake'-knapp vises eller ved feil.

clientName (string, optional) – Navnet på klienten registrert hos DigDir. Vises under innlogging for brukerorienterte flyter.

sessionLifetime (integer, optional) – Maksimal øktlevetid i sekunder for en innlogget sluttbruker for denne klienten. Min: 3600, maks: 28800.

ssoDisabled (bool, optional) – Kontrollerer Single Sign-On-oppsettet for klienten. Hvis satt til true, er SSO deaktivert.

Følgende eksempel registrerer en klientintegrasjon mot ID-porten av typen idporten. Når registrering er fullført vil Digdirator opprette Kubernetes-hemmeligheten idporten-secret i namespacet tilgangsstyring-main.

apiVersion: nais.io/v1
kind: IDPortenClient
metadata:
  name: test-client
  namespace: tilgansstyring-main
spec:
  clientName: Test Application
  clientURI: https://test-app.atgcp1-sandbox.kartverket-intern.cloud
  frontchannelLogoutURI: https://test-app.atgcp1-sandbox.kartverket-intern.cloud/oauth2/logout
  integrationType: idporten
  redirectURIs:
    - https://test-app.atgcp1-sandbox.kartverket-intern.cloud/oauth2/callback
  scopes:
    - openid
    - profile
  secretName: idporten-secret

MaskinportenClient​

En MaskinportenClient er en CRD som lar brukere deklarativt opprette og vedlikeholde Maskinporten-klientregistreringer.

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 og hvilke den eksponerer.
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.

exposes ([]object, optional) – En liste med scopes din applikasjon ønsker å eksponere til andre organisasjoner hvor tilgang er basert på organisasjonsnummer.

enabled (bool, required) – Hvis true, så er detkonfigurerte scopet tilgjengelig for bruk og til å bli konsumert av organisasjoner som har fått godkjent tilgang.

name (string, påkrevd) – Det faktiske sub-scopet kombinert med product.

product (string, valgfritt) – Produktområde tilknyttet scopet. Dette vil inkluderes i resultatet: org:<product><name>.

atMaxAge (int, valgfritt) – Maksimal tillatt levetid for token i sekunder. Defaulter til 30 sekunder.

allowedIntegrations ([]string, valgfritt) – Liste over tillatte integrasjonstyper for dette eksponerte omfanget. Defaulter til maskinporten.

consumers ([]object, valgfritt) – Liste over eksterne konsumenter som har tilgang til å konsumere dette scopet og som kan forespørre access_token.

orgno – Det eksterne organisasjonsnummeret.

name – Beskrivende felt brukt utelukkende for oversikt.

accessibleForAll – Tillater alle organisasjoner å få tilgang til scopet.

delegationSource – Delegasjonskilde for scopet. Default er tomt, noe som betyr at ingen delegasjon er tillatt.

separator – Tegnet som skiller product og name i det endelige scopet. Resultatet blir da <prefix>:<product><separator><name>. Defaulter til : med mindre name inneholder /, i det tilfellet defaultes det til /.

visibility – Kontrollerer synligheten til scopet. Offentlige scopes er synlige for alle, mens private scopes kun er synlige for organisasjonen som eier scopet og organisasjoner som har fått tilgang som konsumenter. Defaulter til public. Tillatte verdier: private, public.

Følgende eksempel oppretter en klientintegrasjon mot Maskinporten og definerer scopet innsyn. Den setter HUSLØS HURTIG TIGER AS og KOSTBAR LEKKER APE AS som godkjente konsumenter av scopet. Når registrering er fullført vil Digdirator opprette Kubernetes-hemmeligheten maskinporten-secret i namespacet tilgangsstyring-main.

apiVersion: nais.io/v1
kind: MaskinportenClient
metadata:
  name: test-client
  namespace: tilgangsstyring-main
spec:
  clientName: innsikt-secure-deltashare
  scopes:
    exposes:
      - enabled: true
        name: "innsyn"
        product: "Produktområde"
        consumers:
          - name: HUSLØS HURTIG TIGER AS
            orgno: "987654321"
          - name: KOSTBAR LEKKER APE AS
            orgno: "123456789"
  secretName: maskinporten-secret

🔹 Azurerator​

Azurerator er en Kubernetes-operator utviklet av NAV sitt plattformteam (NAIS) som skal gjøre det enkelt å deklarativt sette opp og vedlikeholde integrasjoner mot Microsoft Entra ID.

AzureAdApplication​

Azurerator introduserer CRD-en AzureAdApplication, som håndterer opprettelse og vedlikehold av integrasjoner mot Microsoft Entra ID. Registreringer opprettet med Azureator vil få navn basert på hvor de er plassert i et Kubernetes-cluster, i.e. cluster:namespace:name.

spec (object, required) – Spesifikasjon til AzureAdApplication

allowAllUsers (bool, required) – Bestemmer om alle brukere i tenanten som Azurerator er konfigurert mot skal få tilgang.

claims (object, optional) – Definerer konfigurasjon av claims som inkluderes i tokenene som returneres til Entra ID applikasjonen.
groups ([]object, optional) – En liste over Entra ID gruppe ID-er som skal inkluderes i groups-claimet i tokenene utstedt av Entra ID. Dette tildeler også grupper til app-registreringen brukt for tilgangskontroll. Kun direkte medlemmer av gruppene får tilgang.

id (string, required) – Objekt-ID-en (OID) til en Entra ID-gruppe.

replyUrls ([]object, required) – URL-er som applikasjonen godtar som svaradresser etter autentisering.

url (string, required) – En godkjent svaradresse (reply URL) for applikasjonen.

logoutUrl (string, optional) – URL-en brukere blir omdirigert til når de logger ut av applikasjonen..

preAuthorizedApplications ([]object, optional) – Definerer andre app-registreringer som er forhåndsautorisert til å få tilgang til denne applikasjonen. Her refereres det til tilsvarende AzureAdApplication.

application (string, required) – Navnet på den forhåndsgodkjente applikasjonen.

namespace (string, required) – Namespacet hvor den forhåndsgodkjente applikasjonen befinner seg.

cluster (string, required) – Clusteret hvor den forhåndsgodkjente applikasjonen befinner seg.

permissions (object, optional) – Spesifiserer hvilke claims den forhåndsautoriserte applikasjonen har.

scopes ([]string, optional) – Liste med egendefinerte tilgangs-scopes tildelt til den forhåndsautoriserte appliaksjonen.

roles ([]string, optional) – Liste med egendefinerte tilgangs-roller tildelt til den forhåndsautoriserte appliaksjonen.

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

secretKeyPrefix (string, optional) – Et valgfritt brukerdefinert prefiks som brukes på nøklene i den genererte hemmeligheten, og erstatter standardprefikset (AZURE).

secretProtected (bool, optional) – Angir om hemmeligheten skal tilbaketrekkes selv når den ikke er i bruk.

singlePageApplication (bool, optional) – Angir om denne Entra ID-applikasjonen skal registreres som en single-page-application for bruk i klient-side-applikasjoner uten tilgang til hemmeligheter.

Følgende eksempel oppretter app-registreringen atgcp1-sandbox:tilgangsstyring-main:test-app. Den gir kun tilgang til direkte medlemmer av gruppene med objekt-ID 2720e397-081d-4d9b-852e-0d81f45a304f eller c3c94454-aefc-44f9-9076-58ea47547941. Den forhåndsautoriserer også Entra ID klienten atgcp1-dev:other-namespace:other-app. Når registrering er fullført vil Azurerator opprette Kubernetes-hemmeligheten entraid-secret i namespacet tilgangsstyring-main.

apiVersion: nais.io/v1
kind: AzureAdApplication
metadata:
  name: test-app
  namespace: tilgangsstyring-main
spec:
  allowAllUsers: false
  secretName: entraid-secret
  claims:
    groups:
      - id: 2720e397-081d-4d9b-852e-0d81f45a304f
      - id: c3c94454-aefc-44f9-9076-58ea47547941
  replyUrls:
    - url: https://test-app.atgcp1-sandbox.kartverket-intern.cloud/oauth2/callback
  preAuthorizedApplications:
    - application: other-app
      namespace: other-namespace
      cluster: atgcp1-dev