Authentication Bruker guider Systembruker for API

Ta i bruk systembruker for API-leverandører

Systembruker er et nytt konsept for API-autentisering. Denne guiden beskriver hvordan API-leverandører kan beskytte sine API-er med dette konseptet.

Denne funksjonaliteten er i test og kan endres

Bakgrunn

Bakgrunnen til systembruker konsept kan leses om her.

Forutsetninger

For å kunne bruke systembruker som API-leverandør må følgende forutsetninger være oppfylt:

Avtale med Maskinporten som API-leverandør
Avtale med Digdir for tilgang til ressursregisteret for opprettelse av ressurser
Opprettelse av nødvendige ressurser som skal autoriseres
Tildelt scope for PDP-integrasjon
Integrasjon med Altinn PDP

Validering av Maskinporten token

Selve tokenet valideres som et standardisert Maskinporten token. Les mer hos Maskinporten.

Et systembrukertoken inneholder en del flere detaljer enn et vanlig Maskinporten token.

Nedenfor vises et eksempeltoken.

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

Verdiene som er viktige for API leverandør er.

Verdi	Betydning
authorization_details:systemuser_id	Unik id for systembrukeren. Det er denne verdien som Altinn trenger for å kunne autorisere tilgang. Det er denne som har fått delegert tilganger.
authorization_details:systemuser_org:id	Organisasjonen som har opprettet systembrukeren
authorization_details:system_id	Referanse til systemet som systembrukeren peker på
Consumer:id	Organisasjonsnr til systemleverandør (organisasjon som har autentisert seg mot Maskinporten)

Se også dokumentasjon hos Maskinporten.

Autorisasjon av systembruker

API-leverandøren må kalle Altinn PDP for å autorisere tilgangen til systembrukeren. Dette gjøres ved å sende et kall til Altinn PDP.

API-leverandøren må konfigurere hvilke handlinger og ressurser som aksesseres via API-et for å bygge opp den totale forespørselen.

Nedenfor vises et eksempel på et kall utført av systembruker a545ca29-7fb8-4810-a2f2-0be171cb2a26 som prøver å gjøre en read-operasjon på en ressurs av typen kravogbetaling for organisasjonen 923609016.

{
   "Request": {
     "ReturnPolicyIdList": true,
     "AccessSubject": [
       {
         "Attribute": [
           {
             "AttributeId": "urn:altinn:systemuser:uuid",
             "Value": "a545ca29-7fb8-4810-a2f2-0be171cb2a26"
           }
         ]
       }
     ],
     "Action": [
       {
         "Attribute": [
           {
             "AttributeId": "urn:oasis:names:tc:xacml:1.0:action:action-id",
             "Value": "read",
             "DataType": "http://www.w3.org/2001/XMLSchema#string"
           }
         ]
       }
     ],
     "Resource": [
       {
         "Attribute": [
           {
             "AttributeId": "urn:altinn:resource",
             "Value": "kravogbetaling"
           },
           {
             "AttributeId": "urn:altinn:organization:identifier-no",
             "Value": "923609016"
           }
         ]
       }
     ]
   }
}

Altinn PDP returnerer svaret som en XACML Json respons hvor det informeres om request autorisert eller ikke.

API tilbyder må i sitt API ha logikk for å kunne avvise eller godta forespørsel fra system basert på dette.

{
  "Response": [
    {
      "Decision": "Permit",
      "Status": {
        "StatusCode": {
          "Value": "urn:oasis:names:tc:xacml:1.0:status:ok"
        }
      },
      "Obligations": [
        {
          "id": "urn:altinn:obligation:authenticationLevel1",
          "attributeAssignment": [

            {
              "attributeId": "urn:altinn:obligation-assignment:1",
              "value": "2",
              "category": "urn:altinn:minimum-authenticationlevel",
              "dataType": "http://www.w3.org/2001/XMLSchema#integer",
              "issuer": null
            }
          ]
        }
      ]
    }
  ]
}

Se flere eksempler på bruk av Altinn PDP her.