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.