Skip to main content

Maskinporten som API-tilbyder

For å eksponere egne scopes i Maskinporten, og gi andre organisasjoner tilgang til å konsumere dem, har du fire muligheter:

Hvilket alternativ som passer best avhenger av bruksområdet ditt:

  • Vi ønsker å gå bort fra bruk av selvbetjeningsløsningen til Digdir, ettersom tilgangsmodellen der gir brede tilganger utover kun teamets egne scopes.
  • Den deklarative MaskinportenClient-ressursen (via Digdirator) egner seg best når scopet hører naturlig sammen med én spesifikk applikasjon, og du ønsker at opprettelse og vedlikehold av scopet skal følge samme GitOps-baserte arbeidsflyt som resten av applikasjonens Kubernetes-ressurser. Dette er alternativet som er dokumentert i resten av denne siden.
  • REST-APIet egner seg godt dersom du f.eks. ønsker å tilby administrasjon av scopes via et brukergrensesnitt, eller ellers trenger å administrere scopes og konsument-tilgang programmatisk eller dynamisk fra en applikasjon.

Skal applikasjonen din i stedet konsumere scopes fra andre organisasjoner, se Maskinporten som konsument.

🧪 Testmiljø for Maskinporten​

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

🤖 Opprette scopes med MaskinportenClient​

En MaskinportenClient er en Kubernetes-ressurs som lar brukere deklarativt opprette og vedlikeholde Maskinporten-scopes. Når ressursen opprettes, vil scopes opprettes i Maskinporten, og de ønskede konsumentene vil få tilgang til scopet. Dersom ressursen endres, vil endringene bli reflektert i Maskinporten.

Ved ønske om å deaktivere scopes holder det ikke å slette MaskinportenClient-ressursen. Se Deaktivering av scopes. for mer informasjon.

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 eksponerer.
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 det konfigurerte 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, påkrevd) – Produktområde tilknyttet scopet, f.eks. matrikkel eller geodata. Dette vil inkluderes i resultatet: <prefix>:<product><separator><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. Settes denne (kun altinn er gyldig), må separator samtidig settes til /.

separator – Tegnet som skiller product og name i det endelige scopet, se egen seksjon under for forklaring og eksempler. Må være ett enkelt tegn: :, / eller ..

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 oppretter en klientintegrasjon mot Maskinporten og definerer scopet kartverk:matrikkel/eiendom.read, med to eksterne organisasjoner som godkjente konsumenter.

Opprettelse av scope 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:
    exposes:
      - enabled: true
        product: "matrikkel"
        name: "eiendom.read"
        separator: "/"
        consumers:
          - name: "Asker Kommune"
            orgno: "920125298"
          - name: "Drammen Kommune"
            orgno: "921234554"
Om kombinasjon av prefiks, product, name og separator

Prefiks for scopes registrert via MaskinportenClient er alltid kartverk. Dersom feltet separator enten fjernes eller settes til :, vil det endelige scopet bli kartverk:matrikkel:eiendom.read.

🗑️ Deaktivering av scopes​

Deaktivering av scopes i Maskinporten skjer ikke automatisk bare fordi MaskinportenClient-ressursen slettes fra Kubernetes:

  • Dersom du endrer enabled fra true til false på en eksisterende ressurs med exposes-feltet satt, vil scopet bli deaktivert hos Digdir. Konsumentene vil ikke lenger kunne hente token for scopet, men scopet vil fortsatt eksistere i Maskinporten, registrert med de samme konsumentene som før.
  • Dersom du sletter hele MaskinportenClient-ressursen mens et scope fortsatt har enabled: true, vil scopet hverken deaktivere eller fjernes hos Digdir. Scopet forblir aktivt, og de konsumentene som var registrert da ressursen ble slettet beholder tilgangen.

Riktig fremgangsmåte for å både få deaktivert et scope og fjernet MaskinportenClient-ressursen er derfor:

  1. Først endre enabled til false, og la endringene bli reflektert i Maskinporten.
  2. Deretter slette MaskinportenClient-ressursen.

Det er ikke mulig å slette scopes fra Maskinporten permanent, av hensyn til sporbarhet.