Innlogging av virksomhet

Altinns API-er kan også benyttes av virksomheter uten å autentisere en person ved hjelp av Maskinporten og virksomhetsbrukere

På denne siden:

Introduksjon

For noen typer integrasjoner er det uhensiktsmessig å kreve at en person autentiserer seg og lar systemet bruke Altinn med tilgangene personen innehar. Fagsystemer som gjerne har sin egen innloggingsmekanisme internt i virksomheten, eller automatiserte systemer uten brukerinteraksjon kan opprette og benytte seg av en eller flere virksomhetsbrukere for autentisering og autorisasjon. En virksomhetsbruker er som en vanlig sluttbruker i den forstand at den kan tildeles roller og rettigheter i organisasjonen den tilhører.

Selv om de fleste API-ene i Altinn kan benyttes av virksomhetsbrukere, er ikke alle tjenester i Altinn åpnet for bruk av virksomhetsbrukere eller sluttbrukeresystemer i det hele tatt. Dette er opp til hver etat å vurdere for hver av sine tjenester.

En virksomhetsbruker vil kunne bruke de fleste av Altinns REST API-er som normalt krever en autentisert person, og identifiseres med et brukernavn og passord i tillegg til at virksomheten selv autentiseres med enten et virksomhetssertifikat eller et Maskinporten-token.

Enkelte API-er har ikke krav om autentisert bruker, men kan benyttes med kun virksomhetssertifikat eller Maskinporten-token.

Autentisering med virksomhetsbruker og Maskinporten

Dette er funksjonalitet som vil komme i versjon 21.8 av Altinn

Virksomhetsbrukere gjennom Maskinporten lar deg bruke de fleste API-er i Altinn, både de som krever en bruker og de som kun krever virksomhetsautentisering. En Maskinporten-klient settes opp med ønskede scopes, og det hentes ut et token fra Maskinporten som igjen må veksles hos Altinn sammen med virksomhetsbrukerens brukernavn og passord. Dette gir ut et beriket token som kan brukes mot Altinns API-er.

Forutsetninger for bruk

  • Organisasjonen din har registrert systemet og mottatt en API-nøkkel fra Altinn.
  • Det er opprettet en Maskinporten-klient som er provisjonert med ønskede scopes. Les mer om hvordan din organisasjon kan ta i bruk Maskinporten.
  • Det er opprettet en virksomhetsbruker gjennom portalen eller API som du har et brukernavn og passord for.
  • Virksomhetsbrukeren er blitt gitt roller og rettigheter i virksomheten din av en tilgangsstyrer/hovedadministrator

1. Hent token fra Maskinporten

Token hentes fra Maskinporten via et JWT Bearer Grant, som da signeres med eget virksomhetssertifikat.

Eksempel på payload for bearer grant mot testmiljø (TT02) som forventer tokens fra VER2-miljøet av Maskinporten (merk at kommentarene er kun for veiledning og må fjernes før evt bruk):

{
  /* Maskinporten-miljø som forespørsel sendes til */
  "aud": "https://ver2.maskinporten.no/",

  /* Altinn-miljø som skal benyttes */
  "resource": "https://tt02.altinn.no/",

  /* Ønskede scopes, må være provisjonert på klient */
  "scope": "altinn:instances.meta altinn:rolesandrights",

  /* Klient-ID for Maskinporten-klient opprettet i samarbeidsportalen */
  "iss": "806e1e80-e3a7-4a73-980e-f92ba1c2bf86",  

  /* Når JWT-grantet utløper. Påvirker ikke levetid på mottatt token. */
  "exp": 1592896775, 

  /* Når JWT-grantet ble lagd */
  "iat": 1592896655, 

  /* Unik identifikator for grantet */
  "jti": "bebeb0da-fef3-4b67-a0fc-b08d0b68fddd" 
}

Eksempel på payload for bearer grant mot prodmiljø:

{
  "aud": "https://maskinporten.no/",
  "resource": "https://www.altinn.no/",
  "scope": "altinn:instances.meta altinn:rolesandrights",
  "iss": "806e1e80-e3a7-4a73-980e-f92ba1c2bf86",
  "exp": 1592896775,
  "iat": 1592896655,
  "jti": "bebeb0da-fef3-4b67-a0fc-b08d0b68fddd"
}

Du kan bruke verktøyet MaskinportenTokenGenerator for å teste generering av bearer grants og for å få ut access tokens fra Maskinporten.

2. Veksle inn token og motta beriket virksomhetsbrukertoken

Tokenet mottatt fra Maskinporten kan ikke brukes direkte mot Altinn for en virksomhetsbruker. Tokenet må veksles inn mot et nytt token som er beriket med informasjon om virksomhetsbrukeren. Dette gjøres mot Altinns tokenutvekslingspunkt, hvor samtidig virksomhetsbrukerens brukernavn og passord oppgis.

  • Token utstedt fraMaskinporten legges inn som Authorization-header en Bearer-prefix.
  • Brukernavn/passord for virksomhetsbrukeren legges inn i headeren X-Altinn-EnterpriseUser-Authentication med verdi tilsvarende BASE64(brukernavn + “:” + passord) hvor BASE64 her er en funksjon som Base64-enkoder brukernavnet og passordet, tilsvarende måten brukt i Basic HTTP-autentisering som beskrevet i RFC761

Man gjør så en GET-request mot ønsket miljø og får tilbake et gyldig Altinn3-token dersom det opprinnelige tokenet er gyldig, og oppgitt brukernavn og passord er gyldig.

GET /authentication/api/v1/exchange/maskinporten HTTP/1.1
Host: platform.altinn.no
Authorization: Bearer {maskinporten-token}
X-Altinn-EnterpriseUser-Authentication: {base64-enkodet brukernavn og passord}
Accept: application/hal+json

Response:

"{altinn-beriket-token}"

3. Hent ut informasjon fra Altinn

Tokenet mottatt i forrige trinn benyttes mot Altinns API sammen med API-nøkkel, f.eks.:

GET /api/my/messagebox HTTP/1.1
Host: www.altinn.no
Accept: application/hal+json
ApiKey: {min-api-nøkkel}
Authorization: Bearer {altinn-beriket-token}

som da returnerer data for organisasjonen virksomhetsbrukeren tilhører.

Autentisering med virksomhetsbruker og virksomhetssertifikat

Altinns REST-API støtter bruk av virksomhetssertifikat som TLS klientsertifikater for to-veis TLS-kommunikasjon kombinert med et brukernavn og passord for virksomhetsbrukeren. Dette belager seg på at man først autentiserer seg for å få en cookie som brukes i påfølgende requester.

Forutsetninger for bruk

  • Organisasjonen din har registrert systemet og mottatt en API-nøkkel fra Altinn.
  • Organisasjonen din har et virksomhetssertifikat utstedt fra en gyldig norsk utsteder.
  • Det er opprettet en virksomhetsbruker gjennom portalen eller API som du har et brukernavn og passord for.
  • Virksomhetsbrukeren er blitt gitt roller og rettigheter i virksomheten din av en tilgangsstyrer/hovedadministrator

1. Autentisere seg mot Altinn API

Forespørselen som gjøres mot Altinn må gjøres med klientsertifikatet oppgitt i forespørselen. Hvordan dette gjøres avhenger av programmeringsspråket og rammeverk som benyttes. Se her for eksempler for bruk ASP.NET 5.

POST https://www.altinn.no/api/authentication/authenticatewithpassword?ForceEIAuthentication HTTP/1.1
Host: www.altinn.no
Content-Type: application/hal+json
ApiKey: {min-api-nøkkel}
{
    "UserName": "{virksomhetsbrukerens brukernavn}",
    "UserPassword": "{virksomhetsbrukerens passord}"
}

Ved korrekt autentisering vil du få status 200 OK som respons fra Altinn REST API. Responsen vil også inneholde en Set-Cookie-header som inneholder autentiseringscookien .ASPXAUTHsom må benyttes i påfølgende kall. Øvrige cookies som returneres kan ignoreres.

2. Hent ut informasjon fra Altinn

Den mottate cookien .ASPXAUTH sendes som en normal Cookie-header i videre på kall til Altinn API. Merk at API-nøkkel også alltid må oppgis:

GET /api/my/messagebox HTTP/1.1
Host: www.altinn.no
Accept: application/hal+json
ApiKey: {min-api-nøkkel}
Cookie: .ASPXAUTH=2AF7F203...

Autentisering med kun Maskinporten

For API-er som kun krever autentisering av virksomhet støtter Altinn bruk av access tokens utstedt av Maskinporten.

Merk at det kun er et fåtall av API-ene som kan benyttes med Maskinporten alene - altså kun med virksomhetsautentisering uten en bruker med tilganger i Altinn. Tjenesteeier-API er ett av disse. Se API-scopes for en oversikt.

Forutsetninger for bruk

1. Hent token fra Maskinporten

Token hentes fra Maskinporten via et JWT Bearer Grant, som da signeres med eget virksomhetssertifikat.

Eksempel på payload for bearer grant mot testmiljø (TT02) som forventer tokens fra VER2-miljøet av Maskinporten (merk at kommentarene er kun for veiledning og må fjernes før evt bruk):

{
  /* Maskinporten-miljø som forespørsel sendes til */
  "aud": "https://ver2.maskinporten.no/",

  /* Altinn-miljø som skal benyttes */
  "resource": "https://tt02.altinn.no/",

  /* Ønskede scopes, må være provisjonert på klient */
  "scope": "altinn:serviceowner/reportees",

  /* Klient-ID for Maskinporten-klient opprettet i samarbeidsportalen */
  "iss": "806e1e80-e3a7-4a73-980e-f92ba1c2bf86",  

  /* Når JWT-grantet utløper. Påvirker ikke levetid på mottatt token. */
  "exp": 1592896775, 

  /* Når JWT-grantet ble lagd */
  "iat": 1592896655, 

  /* Unik identifikator for grantet */
  "jti": "bebeb0da-fef3-4b67-a0fc-b08d0b68fddd" 
}

Eksempel på payload for bearer grant mot prodmiljø:

{
  "aud": "https://maskinporten.no/",
  "resource": "https://www.altinn.no/",
  "scope": "altinn:serviceowner/reportees",
  "iss": "806e1e80-e3a7-4a73-980e-f92ba1c2bf86",
  "exp": 1592896775,
  "iat": 1592896655,
  "jti": "bebeb0da-fef3-4b67-a0fc-b08d0b68fddd"
}

Du kan bruke verktøyet MaskinportenTokenGenerator for å teste generering av bearer grants og for å få ut access tokens fra Maskinporten.

2. Hent ut informasjon fra Altinn

Tokenet legges i Authorization-headeren i requesten av type Bearer. Eksempel:

GET /api/serviceowner/reportees?subject=... HTTP/1.1
Host: www.altinn.no
ApiKey: {din-api-nøkkel-her}
Authorization: Bearer {maskinporten-token}
Accept: application/hal+json

Autentisering med kun virksomhetssertifikat

Altinns REST-API støtter bruk av virksomhetssertifikat som TLS klientsertifikater for to-veis TLS-kommunikasjon. Dette belager seg på at man først autentiserer seg for å få en cookie som brukes i påfølgende requester.

Merk at det kun er et fåtall av API-ene som kan benyttes med virksomhetssertifikat alene - altså kun med virksomhetsautentisering uten en bruker med tilganger i Altinn. Tjenesteeier-API er ett av disse. Se API-scopes for en oversikt.

Forutsetninger

  • Organisasjonen din har registrert systemet og mottatt en API-nøkkel fra Altinn.
  • Organisasjonen din har et virksomhetssertifikat utstedt fra en gyldig norsk utsteder.

1. Hent ut informasjon fra Altinn

Forespørselen som gjøres mot Altinn må gjøres med klientsertifikatet oppgitt i forespørselen. Hvordan dette gjøres avhenger av programmeringsspråket og rammeverk som benyttes. Se her for eksempler for bruk ASP.NET 5.

Alle kall mot Altinn API som skal benytte to-veis TLS krever at queryparameteret ForceEIAuthentication oppgis i URLen som kalles

Den mottate cookien .ASPXAUTH sendes som en normal Cookie-header i videre på kall til Altinn API. Merk at API-nøkkel også alltid må oppgis:

GET /api/serviceowner/reportees?subject=...&ForceEIAuthentication HTTP/1.1
Host: www.altinn.no
Accept: application/hal+json
ApiKey: {min-api-nøkkel}