Using System User

Guidance for system vendors on how to use a System User after it has been created.

Audience: Developers and system integrators who already have a system access and need to use it in their solutions.

The use of System User towards services occurs in the following way:

Request system access token (JWT Grant)

The OAuth2 Rich Authorization Requests (RAR) extension is used to request a system access token. Altinn defines the type urn:altinn:systemuser for this purpose.

The vendor requests a token for a specific customer by providing the customer’s organization number.
It is important that the organization number is provided according to the following standard:

"systemuser_org" : {
      "authority" : "iso6523-actorid-upis",
      "ID" : "0192:123456789"
    }

If a valid System User exists in Altinn, a Maskinporten token is issued that contains the system user’s identifier.

POST https://test.maskinporten.no/token
Content-Type: application/json

{
  "aud" : "https://maskinporten.no",
  "sub" : "fc9a8287-e7cb-45e5-b90e-123048d32d85",
  "authorization_details" : [ {
    "systemuser_org" : {
      "authority" : "iso6523-actorid-upis",
      "ID" : "0192:123456789"
    },
    "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"
}

HTTP/1.1 200 OK
Content-Type: application/json

{
  "access_token" : "IxC0B76vlWl3fiQhAwZUmD0hr_PPwC9hSIXRdoUslPU=",
  "token_type" : "Bearer",
  "expires_in" : 599,
  "scope" : "difitest:test1"
}

Token contents

The token returns all System Users that the customer has granted to the authenticated system. They are linked to the system through the client_id.

{
  "authorization_details": [
    {
      "type": "urn:altinn:systemuser",
      "systemuser_org": {
        "authority": "iso6523-actorid-upis",
        "id": "0192:123456789"
      },
      "systemuser_id": ["ebe4a681-0a8c-429e-a36f-8f9ca942b59f"],
      "system_id": "123456789_systemid"
    }
  ],
  "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:987654321"
  }
}

The service owner then uses the token against Altinn Authorization (PDP) to determine which operations the system is authorized to perform.

Retrieving parties the system user is authorised for

A system user token (exchanged for an Altinn token) can also be used to call the AuthorizedParties endpoint in the access management API. The endpoint returns the parties the system user is authorised for, so that the end user system can look up the correct partyUuid for subsequent calls.

The Maskinporten token must include the scope altinn:accessmanagement/authorizedparties. See the access management API for the full endpoint description.

Request a token for a specific system user

The vendor can provide externalRef in the request to ask for a token for one specific system user.

externalRef is the external reference the vendor set when the system user was created. If an externalRef was provided in the system user request, it is used to identify the correct system user when the vendor has several system users for the same customer.

{
  "aud": "https://maskinporten.no",
  "scope": "api provider's scope",
  "iss": "my_client_id",
  "authorization_details": [ {
    "type": "urn:altinn:systemuser",
    "systemuser_org": {
      "authority": "iso6523-actorid-upis",
      "ID": "0192:999888777"
    },
    "externalRef": "systembruker #1"
  } ]
}