Utilize system user for API providers
System user is a new concept for API authentication. This guide describes how API providers can protect their APIs using this concept.
Background
You can read about the background of the system user concept here.
Prerequisites
To use a system user as an API provider, the following prerequisites must be met:
- Agreement with Maskinporten as an API provider
- Agreement with Digdir for access to the resource registry for resource creation
- Creation of necessary resources to be authorized
- Assigned scope for PDP integration
- Integration with Altinn PDP
Validation of Maskinporten Token
The token itself is validated as a standardized Maskinporten token. Read more at Maskinporten.
A system user token contains more details than a regular Maskinporten token.
Below is an example token.
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) |
See also the documentation at Maskinporten.
Authorization of System User
The API provider must call Altinn PDP to authorize access for the system user. This is done by sending a request to Altinn PDP.
The API provider must configure which actions and resources are accessed via the API to build the complete request.
Below is an example of a request made by the system user a545ca29-7fb8-4810-a2f2-0be171cb2a26, attempting to perform a read operation on a resource of type kravogbetaling for the organization 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.