From e378e07c78a40ce3834c7dee24e64bd14b99f6de Mon Sep 17 00:00:00 2001
From: "Rune T. Larsen" <rune.tommeras.larsen@accenture.com>
Date: Thu, 28 Nov 2024 16:42:17 +0100
Subject: [PATCH 1/2] Updates

---
 .../_index.md                                 | 326 ++++++++++++++----
 .../_index.nb.md                              |  11 +-
 2 files changed, 263 insertions(+), 74 deletions(-)

diff --git a/content/authentication/guides/systemauthentication-for-systemproviders/_index.md b/content/authentication/guides/systemauthentication-for-systemproviders/_index.md
index 022251b165c..cccb6a11e14 100644
--- a/content/authentication/guides/systemauthentication-for-systemproviders/_index.md
+++ b/content/authentication/guides/systemauthentication-for-systemproviders/_index.md
@@ -1,46 +1,157 @@
 ---
-title: Ta i bruk systembruker for systemleverandører
-linktitle: Systembruker for SBS
-description: Systembruker er et nytt konsept for API autentisering. Denne guiden beskriver hvordan man som systemleverandør kan benytte seg av dette.
+title: Using System User for System Providers
+linktitle: System User for SBS
+description: System User is a new concept for API authentication. This guide describes how system providers can use it.
 toc: false
 weight: 1
 ---
 
 {{<notice warning>}}
-This functionality is in testing and subject to change.
+ This functionality is in testing and may change.
 {{</notice>}}
 
 ## Background
 
-The background of the systembruker concept can be read about here.
+The background of the system user concept can be read about [here](https://github.com/Altinn/altinn-authentication/issues/200).
 
 ## Prerequisites
 
-To use systembruker as a system provider, the following prerequisites must be met:
+Prerequisites for a system provider to use system user are:
 
-- Agreement with Maskinporten as a client
-- Agreement with Digdir granting access to the system register
+- [Agreement with Maskinporten as a consumer](https://samarbeid.digdir.no/maskinporten/konsument/119)
+- Agreement with Digdir that provides access to the system register
+- Delegated access to scope altinn:authentication/systemregister.write
+- Delegated access to scope altinn:authentication/systemuser.request.read
+- Delegated access to scope altinn:authentication/systemuser.request.write
 
-## Setting Up Maskinporten Integration
+In addition, access to the scope for the API that the system will use is required. This information is held by the service owner.
 
-To consume public APIs with systembruker, you need to register at least one MaskinPorten integration. This can be done through the [collaboration portal](https://docs.digdir.no/docs/Maskinporten/maskinporten_sjolvbetjening_web#opprette-klient-for-%C3%A5-konsumere-api) or via the [API](https://docs.digdir.no/docs/Maskinporten/maskinporten_sjolvbetjening_api#registrere-klient).
+## Setting up Maskinporten integration
 
-## Registering a System
+To consume public APIs with system users, you need to register at least one MaskinPorten integration.
+This can be done in the [collaboration portal](https://docs.digdir.no/docs/Maskinporten/maskinporten_sjolvbetjening_web#opprette-klient-for-%C3%A5-konsumere-api) or via [API](https://docs.digdir.no/docs/Maskinporten/maskinporten_sjolvbetjening_api#registrere-klient).
 
-The first step after gaining access to the system register is to register your system.
+## Registering a system
 
-Typically, the system is web-based software available in the market that end customers (organizations) can use for communication with the public sector.
+The first step after gaining access to the system register is to register the system.
+
+The system is typically web-based software available in the market, which end customers (businesses) can use for communication with the public sector.
 
 The system must be described with the following properties:
 
-### SystemTypeId
+### Id
+
+This is a unique ID used to identify the software. Valid characters are a-z 0-9 and _
+
+The ID must start with the supplier's organization number. The example below shows with the Digitalization Directorate's organization number.
+
+### Vendor
+
+This is information about the supplier.
+ID is in the format 0192:{orgnr}
+
+0192 is a reference to the Entity Register in the [Electronic Address Scheme](https://docs.peppol.eu/poacc/billing/3.0/codelist/eas/)
+
+### Name
+
+The name of the system must be provided in English (en), Bokmål (nb), and Nynorsk (nn). The name can be the same in all languages.
+
+The name is presented on Altinn pages during system user registration.
+
+### Description
+
+Description describes the system. It can be presented on Altinn pages for information to end users.
+
+Provided in English, Bokmål, and Nynorsk.
+
+### Rights
+
+Rights describe which services the system needs rights to function. These are references to applications in the Altinn platform or services outside Altinn registered with Altinn.
+
+The required rights will depend on the use case.
+
+The example below shows a system that needs access to the service [Claims and Payments](https://skatteetaten.github.io/api-dokumentasjon/api/kravogbetalinger) from the Tax Directorate, which is [registered in the Altinn resource register](https://platform.tt02.altinn.no/resourceregistry/api/v1/resource/ske-krav-og-betalinger).
+
+Later, System User will support access packages, which are a collection of rights across services within an area.
+
+### ClientId
+
+These are the client IDs for the integration created in Maskinporten.
+
+Only logins with Maskinporten integrations linked to the specified client IDs are allowed.
+
+### Example from TT02
+
+The example shows the system registered for the demo application SmartCloud in the TT02 test environment.
+
+```json
+{
+  "id": "991825827_smartcloud",
+  "vendor": {
+    "ID": "0192:991825827"
+  },
+  "name": { "en": "SmartCloud", "nb": "SmartCloud", "nn": "Smart SKY" },
+  "description": { "en": "SmartCloud Rocks", "nb": "SmartCloud is the best system in the world.", "nn": "SmartSky is the best system in western Norway" },
+  "rights": [
+    {
+      "Resource": [
+        {
+          "value": "ske-krav-og-betalinger",
+          "id": "urn:altinn:resource"
+        }
+      ]
+    }
+  ],
+  "clientId": ["235ar6-8824-955a-g235-5asfaa446533"]
+}
+```
+
+URL to register
+
+```http
+POST https://platform.tt02.altinn.no/authentication/api/v1/systemregister/system
+```
+
+URL to update this system (ID must be changed for other systems)
+
+```http
+POST https://platform.tt02.altinn.no/authentication/api/v1/systemregister/system/91825827_smartcloud
+```
+
+For production, change the domain to **platform.altinn.no**
+
+See also [example application](https://github.com/TheTechArch/altinn-systemuser/tree/main/src/SystemAdmin) for registering a system.
+
+## Sending a request to create a system user to a business
+
+As a system provider, you can ask your customers to create a system user with the necessary rights.
+This provides easy onboarding of new customers.
+
+To do this, you must be assigned the scope **altinn:authentication/systemuser.request.write**
+
+System User only supports businesses as customers.
+
+### External ref
+
+This is used as an external reference by the system provider. If not set, it is automatically set to the organization number.
 
-This is a unique ID used to identify the software. Valid characters are a-z, 0-9, and _.
+### SystemId
 
-### KlientId
+Reference to the system.
 
-This is the client ID for the integration created in Maskinporten. Only logins with Maskinporten integrations associated with specific client IDs are allowed.
+### PartyOrgNo
 
+Organization number of the system provider's customer.
+
+### Rights
+
+A list of rights the system user needs access to. It is currently described with a reference to the resource.
+
+### RedirectUrl
+
+This URL is used after the end user has accepted the request.
+
+### Example
 
 ```json
 {
@@ -55,8 +166,8 @@ This is the client ID for the integration created in Maskinporten. Only logins w
   },
   "Description": {
     "en": "SmartCloud Rocks",
-    "nb": "SmartCloud er verdens beste system.",
-    "nn": "SmartSky er vestlandets beste system"
+    "nb": "SmartCloud is the best system in the world.",
+    "nn": "SmartSky is the best system in western Norway"
   },
   "Rights": [
     {
@@ -68,80 +179,153 @@ This is the client ID for the integration created in Maskinporten. Only logins w
       ]
     }
   ],
-  "AllowedRedirectUrls": [ "https://smartcloudaltinn.azurewebsites.net/receipt" ],
-  "ClientId": [ "a2ed712d-4244-6671-839f-80ae4a68146b" ]
+  "AllowedRedirectUrls": ["https://smartcloudaltinn.azurewebsites.net/receipt"],
+  "ClientId": ["a2ed712d-4244-6671-839f-80ae4a68146b"]
 }
 ```
 
-## Maskinporten autentisering
-
-Når system skal autentisere seg som systembrukeren til kunden må JWT grant forespørselen til maskinporten inneholde informasjon om kunden
+## Maskinporten authentication
 
+When the system needs to authenticate as the system user for the customer, the JWT grant request to Maskinporten must contain information about the customer.
 
 ### JWT Grant
 
 ```json
 {
-  "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"
+  "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
 
-
 ```json
 {
-  "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"
+  "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"
   }
 }
-
 ```
-
 See also documentation at [Maskinporten](https://docs.digdir.no/docs/Maskinporten/maskinporten_func_systembruker).
 
-## Using Systembruker Tokens with APIs
+## Using system user token against API
+
+The token received from Maskinporten is attached as a bearer token to the APIs being called.
+
+## Testing system user in TT02
+
+To test system user in TT02, the following is required:
+
+- System provider registered in Maskinporten. Done via servicedesk@digdir.no
+- System provider registered in Altinn. Done via servicedesk@altinn.no
+- System integration registered in Maskinporten test.
+
+For creating system users, test users/organizations from Tenor can be used.
+
+### Using system user token against API
+
+The token received from Maskinporten is attached as a Bearer Token to the APIs being called.
+
+### Testing system user in TT02
+
+To test system user in TT02, the following is required:
 
-The token obtained from Maskinporten should be included as a bearer token when making API calls.
+- System provider registered in Maskinporten. This is done via servicedesk@digdir.no.
+- System provider registered in Altinn. This is done via servicedesk@altinn.no.
+- System integration registered in Maskinporten test.
 
-## Testing Systembruker in TT02
+For creating system users, test users/organizations from Tenor can be used.
 
-To test systembruker in TT02, the following steps are required:
+### Reference implementation and setup
 
-- Add the system provider in Maskinporten. (orgnumber/name) This can be done via [servicedesk@digdir.no](mailto:servicedesk@digdir.no).
-- Add the system provider in Altinn test environment.  (orgnumber/name) This can be done via [servicedesk@altinn.no](mailto:servicedesk@altinn.no).
-- Create a system integration in the Maskinporten test environment.
-- For systembruker creation, you can use test users/organizations from Tenor.
+A reference implementation has been developed to demonstrate the use of system user. It is developed in C# and can be run as a console application.
+It does the following:
+
+1. Creates a token based on configured JSON Web Key, client ID, scope, and organization number of the system user creator.
+2. Based on the token received, it makes calls to reference APIs that require system user.
+
+See code with documentation [here](https://github.com/TheTechArch/altinn-systemuser).
+
+### Setting up reference implementation with own configuration
+
+A reference implementation has been developed to demonstrate the use of system user. It is developed in C# and can be run as a console application.
+
+It does the following:
+
+1. Creates a token based on configured JSON Web Key, client ID, scope, and organization number of the system user creator.
+2. Based on the token received, it makes calls to reference APIs that require system user.
+
+See code with documentation [here](https://github.com/TheTechArch/altinn-systemuser).
+
+### Setting up reference implementation with own configuration
+
+The repository contains the necessary test certificate to run the application. The following must be done to set up your own integration as a system provider:
+
+1. Log in to [onboarding Maskinporten](https://onboarding.test.maskinporten.no/). Here you can use a test ID that is the CEO of a test entity.
+
+    ![Onboarding](onboarding1.png "Simplified onboarding")
+
+    ![Onboarding](onboarding2.png "Select entity")
+
+    ![Onboarding](onboarding3.png "Overview of integrations in Maskinporten. Here you can add new ones")
+
+    ![Onboarding](onboarding4.png "Create integration, search for required scope")
+
+    ![Onboarding](onboarding5.png "Add any additional scope and describe the integration")
+
+    ![Onboarding](onboarding6.png "Download generated keys")
+
+    ![Onboarding](onboarding7.png "Integration created")
+
+2. Get the system registered in the System Register with the correct client ID and linkage to necessary resources/access packages.
+
+3. Log in with a test user at tt02.altinn.no. The user must have the access management role in Altinn for a test organization and go to the page [https://authn.ui.tt02.altinn.no/authfront/ui/auth/creation](https://authn.ui.tt02.altinn.no/authfront/ui/auth/creation).
+
+    ![Onboarding](delegation1.png "10. Select system")
+
+    ![Onboarding](delegation2.png "11. Accept creation of system user with rights to it")
+
+    ![Onboarding](delegation3.png "12. Overview of system users for test organization")
+
+4. Configure key, certificate, client ID, and scope in the test application.
+
+```c#
+string clientID = "7ee41fce-9f6e-4c32-8195-0fe2c1517f43";
+string scope = "altinn:systembruker.demo";
+string systemUserOrg = "210493352";
+string pemCertificatePath = @".\mp-key.pem";
+```
diff --git a/content/authentication/guides/systemauthentication-for-systemproviders/_index.nb.md b/content/authentication/guides/systemauthentication-for-systemproviders/_index.nb.md
index fedf7ecf887..e88e4fc4751 100644
--- a/content/authentication/guides/systemauthentication-for-systemproviders/_index.nb.md
+++ b/content/authentication/guides/systemauthentication-for-systemproviders/_index.nb.md
@@ -12,7 +12,7 @@ weight: 1
 
 ## Bakgrunn
 
-Bakgrunnen til systembruker konsept kan leses om her.
+Bakgrunnen til systembruker konsept kan leses om [her](https://github.com/Altinn/altinn-authentication/issues/200).
 
 ## Forutsetninger
 
@@ -21,6 +21,10 @@ Forutsetninger for at man systemleverandør kan benytte seg systembruker er.
 - [Avtale med maskinporten som konsument](https://samarbeid.digdir.no/maskinporten/konsument/119)
 - Avtale med Digdir som gir tilgang til systemregister
 - Delegert tilgang til scope altinn:authentication/systemregister.write 
+- Delegert tilgang til scope altinn:authentication/systemuser.request.read
+- Delegert tilgang til scope altinn:authentication/systemuser.request.write
+
+I tilegg trengs tilgang til scope for API som skal benyttes av systemet. Dette vil være informasjon som tjenesteeier sitter på.
 
 ## Sette opp maskinporten integrasjon
 
@@ -120,7 +124,6 @@ For produksjon endres domenet til **platform.altinn.no**
 
 Se også [eksempelapplikasjon](https://github.com/TheTechArch/altinn-systemuser/tree/main/src/SystemAdmin) 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. 
@@ -149,7 +152,7 @@ En liste over rettigheter systembrukeren trenger tilgang til. Det beskrives for
 
 ### RedirectUrl
 
-Denne urlen 
+Denne urlen benyttes for sluttbruker har akseptert forespørsel. 
 
 
 ### Eksempel
@@ -183,6 +186,8 @@ Denne urlen
   "AllowedRedirectUrls": [ "https://smartcloudaltinn.azurewebsites.net/receipt" ],
   "ClientId": [ "a2ed712d-4244-6671-839f-80ae4a68146b" ]
 }
+```
+
 
 ## Maskinporten autentisering
 

From fb09125d24ebc0ffff37560d568ff6324337c12b Mon Sep 17 00:00:00 2001
From: "Rune T. Larsen" <rune.tommeras.larsen@accenture.com>
Date: Fri, 29 Nov 2024 07:44:44 +0100
Subject: [PATCH 2/2] fix image link

---
 .../systemauthentication-for-systemproviders/_index.md      | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/content/authentication/guides/systemauthentication-for-systemproviders/_index.md b/content/authentication/guides/systemauthentication-for-systemproviders/_index.md
index cccb6a11e14..4d28a50d9e7 100644
--- a/content/authentication/guides/systemauthentication-for-systemproviders/_index.md
+++ b/content/authentication/guides/systemauthentication-for-systemproviders/_index.md
@@ -315,11 +315,11 @@ The repository contains the necessary test certificate to run the application. T
 
 3. Log in with a test user at tt02.altinn.no. The user must have the access management role in Altinn for a test organization and go to the page [https://authn.ui.tt02.altinn.no/authfront/ui/auth/creation](https://authn.ui.tt02.altinn.no/authfront/ui/auth/creation).
 
-    ![Onboarding](delegation1.png "10. Select system")
+    ![Onboarding](delegering1.png "10. Select system")
 
-    ![Onboarding](delegation2.png "11. Accept creation of system user with rights to it")
+    ![Onboarding](delegering2.png "11. Accept creation of system user with rights to it")
 
-    ![Onboarding](delegation3.png "12. Overview of system users for test organization")
+    ![Onboarding](delegering3.png "12. Overview of system users for test organization")
 
 4. Configure key, certificate, client ID, and scope in the test application.