Authentication Bruker guider Systembruker for SBS

Ta i bruk systembruker for systemleverandører

Systembruker er et nytt konsept for API autentisering. Denne guiden beskriver hvordan man som systemleverandør kan benytte seg av dette.

Denne funksjonaliteten er i test og kan endres

Bakgrunn

Bakgrunnen til systembruker konsept kan leses om her.

Forutsetninger

Forutsetninger for at man systemleverandør kan benytte seg systembruker er.

Avtale med maskinporten som konsument
Avtale med Digdir som gir tilgang til systemregister
Delegert tilgang til scope altinn:authentication/systemregister.write

Sette opp maskinporten integrasjon

For å konsumere offentlige API med systembrukere trenger man å registrere minst en MaskinPorten integrasjon. Dette kan gjøres i sammarbeidsportalen eller via API.

Registrere system

Det første steget etter at man har fått tilgang til systemregisteret, er å registrere systemet.

Systemet er typisk en nettbasert programvare som er tilgjengelig i markedet, og som sluttkunder (virksomheter) kan benytte for kommunikasjon med det offentlige.

Systemet må beskrives med følgende egenskaper:

Id

Dette er en unik ID som vil benyttes for å identifisere programvaren. Gyldige tegn er a-z 0-9 og _

Id må starte med organisasjonsnr til leverandør. Eksempelet nedenfor viser med Digitialiseringsdirektorates organisasjonsnr

Vendor

Dette er informasjon om leverandør. ID er på formatet 0192:{orgnr}

0192 er referanse til Enhetsregisteret i Electronic Adress Scheme

Name

Navn på systemet må oppgis på engelsk (en), bokmål (nb) og nynorsk (nn). Navn kan settes likt på alle språk.

Navn presenteres på Altinn sider under registrering av systembruker.

Description

Description beskriver systemet. Vil kunne presenteres på Altinn sider for informasjon til sluttbrukere.

Oppgis på engelsk, bokmål og nynorsk.

Rights

Rights beskriver hvilke tjenester systemet trenger rettighet for å kunne fungere. Dette er referanser til applikasjoner i Altinn plattformen eller tjenester utenfor Altinn som er registrert hos Altinn.

Hvilke rettigheter som kreves vil avhengig av bruksscenario.

Eksempelet nedenfor viser et system som har behov for tilgang til tjenesten Krav og betalinger fra Skattedirektoratet som er registrert i Altinn ressursregister.

Senere vil Systembruker støtte tilgangspakker som er en samling av rettigheter på tvers av tjenester innfor et område.

ClientId

Dette er klientidene for integrasjonen som er opprettet i Maskinporten.

Det er kun pålogginger med Maskinportenintegrasjoner som er knyttet mot oppgitte klientider.

Eksempel fra TT02

Eksempelet viser systemet som er registrert for demoapplikasjonen SmartCloud i TT02 testmiljø.

{
  "id": "991825827_smartcloud",
  "vendor": {
    "ID": "0192:991825827"
  },
  "mame": { "en": "SmartCloud", "nb":  "SmartCloud", "nn":  "Smart SKY"  },
  "description": { "en": "SmartCloud Rocks", "nb":  "SmartCloud er verdens beste system.", "nn":  "SmartSky er vestlandets beste system" },
  "rights": [
    {
      "Resource": [
        {
          "value": "ske-krav-og-betalinger",
          "id": "urn:altinn:resource"
        }
      ]
    }
  ],
  "clientId": ["235ar6-8824-955a-g235-5asfaa446533"]
}

Url for å regsistrere

POST https://platform.tt02.altinn.no/authentication/api/v1/systemregister/system

Url for å opppdatere dette systemet (ID må endres for andre system)

POST https://platform.tt02.altinn.no/authentication/api/v1/systemregister/system/91825827_smartcloud

For produksjon endres domenet til platform.altinn.no

Se også eksempelapplikasjon for å registrere system.

Sende forespørsel om opprettelse av systembruker til virksomhet

Som systemleverandør kan man be sine kunder om å opprette systembruker med nødvendige rettigheter. Dette gir en enkel onboarding av nye kunder.

For å kunne gjøre dette må man være tildelt scopet altinn:authentication/systemuser.request.write

Systembruker støtter kun virksomheter som kunde.

External ref

Denne benyttes som ekstern refernase hos systemleverandør. Hvis den ikke er satt blir den automatisk satt til orgnr

SystemId

Referanse til system

PartyOrgNo

Organiasjonsnr til systemleverandørens kunde.

Rights

En liste over rettigheter systembrukeren trenger tilgang til. Det beskrives for øyeblikket med referanse til ressurs

RedirectUrl

Denne urlen

Eksempel

{
  "externalRef": "213544942",
  "systemId": "991825827_smartcloud",
  "partyOrgNo": "213544942",
  "rights": [
    {
      "resource": [
        {
          "value": "ske-krav-og-betalinger",
          "id": "urn:altinn:resource"
        }
      ]
    }
  ],
  "redirectUrl": "https:\\smartcloud.azurewebsites.net/receipt"
}

Maskinporten autentisering

Når system skal autentisere seg som systembrukeren til kunden må JWT grant forespørselen til maskinporten inneholde informasjon om kunden

JWT Grant

{
  "aud" : "https://maskinporten.no",
  "sub" : "fc9a8287-e7cb-45e5-b90e-123048d32d85",
  "authorization_details" : [ {
    "systemuser_org" : {
      "authority" : "iso6523-actorid-upis",
      "ID" : "0192:310385980"
    },
    "type" : "urn:altinn:systemuser"
  } ],
  "scope" : "krr:global/kontaktinformasjon.read",
  "iss" : "fc9a8287-e7cb-45e5-b90e-123048d32d85",
  "exp" : 1718124835,
  "iat" : 1718124715,
  "jti" : "89365ecd-772b-4462-a4de-ac36af8ef3e2"
}

JWT Token

{
  "authorization_details" : [ {
    "type" : "urn:altinn:systemuser",
    "systemuser_org" : {
      "authority" : "iso6523-actorid-upis",
      "id" : "0192:314168267"
    },
    "systemuser_id" : [ "ebe4a681-0a8c-429e-a36f-8f9ca942b59f" ],
    "system_id" : "matrix_test"
  } ],
  "scope" : "krr:global/kontaktinformasjon.read",
  "iss" : "https://test.maskinporten.no/",
  "client_amr" : "private_key_jwt",
  "token_type" : "Bearer",
  "exp" : 1718175135,
  "iat" : 1718175015,
  "client_id" : "fc9a8287-e7cb-45e5-b90e-123048d32d85",
  "jti" : "-SpfU--1Zn_Oqvkpjwu3oVn--VLcPzSAwjqyiP6zBEw",
  "consumer" : {
    "authority" : "iso6523-actorid-upis",
    "ID" : "0192:314330897"
  }
}

Se også dokumentasjon hos Maskinporten.

Bruk av systembrukertoken mot API

Tokenet man får fra maskinporten legges ved som et bearer token mot de API man skal kalle.

Test av systembruker i TT02

For å teste systembruker i TT02 kreves følgende

Systemleverandør opprettet i maskinporten. Gjøres via servicedesk@digdir.no
Systemleverandør opprettet i Altinn. Gjøres vie servicedesk@altinn.no
Systemintegrasjon opprettet i maskinporten test.

For opprettelse av systembrukere kan testbrukere/organisasjoner fra Tenor benyttes

Bruk av systembrukertoken mot API

Tokenet man får fra Maskinporten legges ved som et Bearer Token mot de API-ene man skal kalle.

Test av systembruker i TT02

For å teste systembruker i TT02 kreves følgende:

Systemleverandør opprettet i Maskinporten. Dette gjøres via servicedesk@digdir.no.
Systemleverandør opprettet i Altinn. Dette gjøres via servicedesk@altinn.no.
Systemintegrasjon opprettet i Maskinporten test.

For opprettelse av systembrukere kan testbrukere/organisasjoner fra Tenor benyttes.

Referanseimplementasjon og oppsett

Det er utviklet en referanseimplementasjon for å demonstrere bruk av systembruker. Den er utviklet i C# og kan kjøres som en konsollapplikasjon. Den gjør følgende:

Oppretter token basert på konfigurert JSON Web Key, client ID, scope og organisasjonsnummer til den som har opprettet systembruker.
Basert på tokenet den får, gjør den kall mot referanse-API som krever systembruker.

Se kode med dokumentasjon her.

Sette opp referanseimplementasjon med egen konfigurasjon

Det er utviklet en referanseimplementasjon for å demonstrere bruk av systembruker. Den er utviklet i C# og kan kjøres som en konsollapplikasjon.

Den gjør følgende:

Oppretter token basert på konfigurert JSON Web Key, client ID, scope og organisasjonsnummer til den som har opprettet systembruker.
Basert på tokenet den får, gjør den kall mot referanse-API som krever systembruker.

Se kode med dokumentasjon her.

Sette opp referanseimplementasjon med egen konfigurasjon

I repoet ligger nødvendig testsertifikat for å kjøre applikasjonen. Følgende må gjøres for å sette opp egen integrasjon som systemleverandør:

Logg inn på onboarding Maskinporten. Her kan du bruke en test-ID som er daglig leder for en testenhet.
Forenklet onboarding
Velg enhet
Oversikt over integrasjoner i Maskinporten. Her kan du legge til nye
Opprett integrasjon, søk etter scope som kreves
Legg til eventuell ekstra scope og beskriv integrasjon
Last ned nøkler som genereres
Integrasjon opprettet
Få opprettet system i Systemregister med riktig client ID og knytning mot nødvendige ressurser/tilgangspakker.
Logg inn med testbruker i tt02.altinn.no. Brukeren må ha tilgangsstyringsrollen i Altinn for en testorganisasjon og gå til siden https://authn.ui.tt02.altinn.no/authfront/ui/auth/creation.
10. Velg system
11. Aksepter opprettelse av systembruker med rettigheter til den
12. Oversikt systembrukere for testorganisasjon
Konfigurer key, nøkkel, client ID og scope i testapplikasjon.

string clientID = "7ee41fce-9f6e-4c32-8195-0fe2c1517f43";
string scope = "altinn:systembruker.demo";
string systemUserOrg = "210493352";
string pemCertificatePath = @".\mp-key.pem";