📝 Klientregistrering

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.

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 skal registrere en klient mot en eller flere av identitetstilbyderne, har man tre valg. Man kan benytte seg av Skiperator dersom klientregistreringen hører til en SKIP-applikasjon. Alternativt kan man bruke CRD-ene fra Digdirator og Azurerator direkte.

Skiperator

Skiperator tilbyr et forenklet API i CRD-en Application for å registrere klienter mot ID-porten og Maskinporten. Det jobbes også med et forenklet API for å registrere klienter mot Entra ID, men dette er ikke helt klart ennå.

Fordelen med å benytte Skiperator for klientregistrering er at hemmelighetene som Digdirator oppretter blir automatisk injisert som miljøvariabler i deploymenten til applikasjonen. Dette gjør at applikasjonen enkelt kan få tilgang til hemmelighetene i et kjøretidsmiljø.

Entra ID

🚧 UNDER UTVIKLING 🚧

Opprettelse av app-registrering i Entra ID via spesifikasjonen til Application jobbes med, men er ikke klart helt ennå.

ID-porten

Skiperator tilbyr støtte for å sette opp en klientintegrasjon mot ID-porten via spesifikasjonen til Application.

Eksempelet under setter opp en integrasjon mot ID-porten med følgende konfigurasjon.

• Integrasjonstypen settes til api_klient.
• Redirect path settes til /oauth/callback.
• Scopene openid og profile settes.

Resten av feltene som støttes kan du finne i Skiperator sin API-dokumentasjon.

apiVersion: skiperator.kartverket.no/v1alpha1
kind: Application
metadata:
  name: application
  namespace: tilgangsstyring-main
spec:
  image: image
  port: 8080
  idporten:
    enabled: true
    integrationType: "api_klient"
    redirectPath: "/oauth/callback"
    scopes:
      - "openid"
      - "profile"

Maskinporten

Skiperator tilbyr støtte for å sette opp en klientintegrasjon mot Maskinporten via spesifikasjonen til Application.

Eksempelet under setter opp en integrasjon mot Maskinporten med følgende konfigurasjon.

• Scopet innsyn opprettes og organisasjonene HUSLØS HURTIG TIGER AS og KOSTBAR LEKKER APE AS settes som godkjente konsumenter av dette scopet.

Resten av feltene som støttes kan du finne i Skiperator sin API-dokumentasjon.

apiVersion: skiperator.kartverket.no/v1alpha1
kind: Application
metadata:
  name: application
  namespace: tilgangsstyring-main
spec:
  image: image
  port: 8080
  maskinporten:
    enabled: true
    scopes:
      exposes:
      - name: "innsyn"
        enabled: true
        product: "Produktområde"
        consumers:
        - name: HUSLØS HURTIG TIGER AS
          orgno: "987654321"
        - name: KOSTBAR LEKKER APE AS
          orgno: "123456789"

Digdirator / Azurerator

Hvis en ønsker å opprette en klientintegrasjon uten å knytte den til en Skiperator-applikasjon, kan man benytte seg av CRD-ene som Digdirator og Azurerator introduserer direkte. Dette gjør det mulig å opprette og vedlikeholde klientregistreringen uavhengig av en spesifikk applikasjon i Skiperator.

Fordelen med denne tilnærmingen er at man får full kontroll over konfigurasjonen og stor fleksibilitet ved å frikoble registreringen fra applikasjonen. Ulempen er at det krever mer innsikt i oppsettet, og at injisering av hemmeligheter i deploymenten må håndteres separat.

Entra ID

En kan registrere en klient mot Entra ID ved å opprette en AzureAdApplication-ressurs. Registreringer opprettet med Azureator følger følgende navnekonvensjon basert på AzureAdApplication-manifestet: cluster:namespace:name.

Spesifikasjonen til AzureAdApplication

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.

Eksempel

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

ID-porten

En kan registrere en klient mot ID-porten ved å opprette en IDPortenClient-ressurs.

Spesifikasjonen til IDPortenClient

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.

Eksempel

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

Maskinporten

En kan registrere en klient mot Maskinporten ved å opprette en MaskinportenClient-ressurs.

Spesifikasjonen til MaskinportenClient

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.

Eksempel

Følgende eksempel registrerer 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