Sist endret: 3. jul. 2025

Integrasjon av Altinn-app med Maskinporten

Hvordan sette opp en integrasjon mellom en Altinn-app og Maskinporten.

Denne veiledningen viser hvordan du setter opp en Altinn-applikasjon til å bruke den innebygde Maskinporten-klienten (IMaskinportenClient) for å utføre autoriserte forespørsler på vegne av eieren av applikasjonen, i stedet for den aktive brukeren.

For å sette dette opp, må følgende gjøres:

  1. Sørg for at organisasjonen har tilgang til Azure Key Vault.
  2. Opprett integrasjonen mot Maskinporten i Samarbeidsportalen.
  3. Lagre autentiseringsnøkkelen for integrasjonen i Azure Key Vault.
  4. Sett opp applikasjonen til å bruke Maskinporten-klienten og hente hemmeligheter fra Azure Key Vault.

Tilgang til Azure Key Vault

Før du går videre med denne veiledningen, må du forsikre deg om at du har tilgang til Azure Key Vault for organisasjonen din. Dette sikrer at nøklene som opprettes senere i veiledningen kan lagres riktig som hemmeligheter i Azure.

Hvis tilgang mangler, se Tilgang til logger og hemmeligheter.

Maskinporten-integrasjon

I denne delen skal vi sette opp Maskinporten-klienten. En del av oppsettet inkluderer opprettelse av nøkler som senere skal lagres i Azure Key Vault. Hvis ulike personer i organisasjonen har tilgang til forskjellige ressurser som trengs i denne prosessen, anbefales det å samarbeide og utføre disse trinnene på samme maskin. Dette er for å unngå å sende hemmeligheter mellom maskiner.

Når tilgang til å opprette hemmeligheter i Azure Key Vault er bekreftet, kan du fortsette med å opprette integrasjonen.

Prerequisites

Register new integration through Samarbeidsportalen

  • Login to Samarbeidsportalen in Test or Production

  • Choose Selvbetjening and then Integrasjoner for the environment you want. Ver2 is test and Produksjon is production.

    “Samarbeidsportalen”
    Samarbeidsportalen

  • Choose Ny integrasjon

    “New integration”
    New integration

  • To fill out the form, provide all required properties:

    • Scopes: Choose Legge til scopes and include all the scopes necessary for the integration to generate tokens containing
    • Navn på integrasjonen: Add a descriptive name that allows you to identify the application that will be using the integration
    • Beskrivelse: Add a short description, not only for yourself but for everyone that administers integrations on behalf of your organization.

    “Add values for integration”
    Add values for integration

    The example above shows an integration used by an Altinn CLI Client which will need to generate tokens containing one or more of the three selected scopes; altinn:serviceowner, altinn:serviceowner/instances.read and altinn:serviceowner/instances.write

  • Choose Opprett in the top right corner when you have completed the configuration

The final steps of this guide cover creating a Json Web Key (JWK) for the integration to use to authenticate towards maskinporten, as well as noting down important values that can be used to configure the client that will integrate with Maskinporten.

Generate and register JWK for authentication towards Maskinporten

To avoid spreading the business certificate across many systems, we opt for creating an asymmetric key (JSON Web Key) and associate it to the newly created integration. In this example we use mkjwk.org.

  • Navigate to mkjwk.org in a browser

  • Fill in values like the example below and click Generate

    “New JWK”
    New JWK

    The output should look like this:

    “The JWK”
    The JWK

Now, the public part of the key should be added to the newly created integration in Samarbeidsportalen.

  • Navigate back to the integration in Samarbeidsportalen

  • Choose Egne public nøkler

    “Own public keys”
    Own public keys

  • Add two empty square bracets to the empty text box as shown below

    “Add array”
    Add array

  • Navigate back to the JWK generator site

    “The JWK”
    The JWK

  • Copy the public key of the JWK (marked 1 in the picture) and paste this into the array in Samarbeidsportalen.

    “Add public key”
    Add public key

  • Choose Legg til

The registration and configuration in Samarbeidsportalen is now complete, and the integration is ready to generate Maskinporten tokens on request from any client that can provide the private and public parts of the JWK.

Important values for client configuration

From samarbeidsportalen:

  • Integrasjonens identifikator

    This will be used in your client configuration. In Altinn libraries, this value is referred to as the client identifikator

From the JWK generation tool:

  • Public and private key pair (marked 2 in the picture below) This is what your client will use when calling the Maskinporten integration.

    “The JWK”
    The JWK

In Altinn applications this key pair is referenced as JwkBase64 and must be base64 encoded before it is included in application configuration or uploaded to a Key Vault.

Base64encode.org can be used for encoding.

Konfigurasjon av Azure Key Vault

Når applikasjonen forberedes til å bruke hemmeligheter fra Azure Key Vault, må følgende trinn utføres:

  1. Legg til hemmelighetene som ble hentet under konfigurasjon av Maskinporten-klienten, i Azure Key Vault:

    • Base64-kodet JWT offentlig og privat nøkkelpar
    • Klient-ID for integrasjonen

    Det er viktig at navnet på disse hemmelighetene i Azure Key Vault tilsvarer navnet på seksjonen i appsettings-filen i kodebasen til applikasjonen.

    For eksempel, hvis seksjonen for Maskinporten-integrasjonen ser slik ut:

    {
      "MaskinportenSettings": {
        "Authority": "https://test.maskinporten.no/",
        "ClientId": "",
        "JwkBase64": ""
      }
    }
    

    Må hemmelighetene i Azure Key Vault ha navn som dette:

    MaskinportenSettings--Authority
    MaskinportenSettings--ClientId
    MaskinportenSettings--JwkBase64
    
  2. For at applikasjonen skal kunne lese hemmelighetene fra Azure Key Vault, må konfigureres først. Se seksjoner om hemmeligheter for hvordan dette oppnås.

  3. Legg til appsettings-eksempelet ovenfor i appsettings.{env}.json-filen.

NB: Hemmelighetene leses av applikasjonen ved oppstart, så hvis du endrer hemmelighetene etter at applikasjonen er publisert, må du publisere applikasjonen på nytt før endringene trer i kraft.

Sett opp applikasjonen til å bruke Maskinporten-integrasjonen

Applikasjonen inkluderer automatisk den innebygde IMaskinportenClient som kan brukes i tjenestene dine. Klienten finner og bruker automatisk MaskinportenSettings-konfigurasjonen.

Hvis du trenger å bruke en annen konfigurasjonsbane enn standardbanen, kan du konfigurere den i RegisterCustomAppServices-metoden:

void RegisterCustomAppServices(IServiceCollection services, IConfiguration config, IWebHostEnvironment env)
{
    // ...

    services.ConfigureMaskinportenClient(
        "YourCustomMaskinportenSettingsPath"
    );
}

For typede HTTP-klienter som trenger Maskinporten-autorisasjon, kan du bruke utvidelsesmetodene:

void RegisterCustomAppServices(IServiceCollection services, IConfiguration config, IWebHostEnvironment env)
{
    // ...

    // For eksterne API-er som krever rå Maskinporten-tokens
    services.AddHttpClient<YourCustomClient>().UseMaskinportenAuthorisation("scope:1", "scope:2");
    
    // For Altinn API-er som krever Altinn-tokens (veksler Maskinporten-token)
    services.AddHttpClient<YourCustomClient2>().UseMaskinportenAltinnAuthorisation("scope:1", "scope:2");
}

Deretter må vi legge til Azure Key Vault som konfigurasjonsleverandør til vår host. Dette gjøres ved å legge til den markerte koden etter ConfigureWebHostBuilder metoden:

ConfigureWebHostBuilder(IWebHostBuilder builder);

// Add Azure KV provider for TT02 & Prod environments
if (!builder.Environment.IsDevelopment())
{
    builder.AddAzureKeyVaultAsConfigProvider();
}