REST-forespørsler med Maskinporten-token

Hvordan bruke Postman til å sende REST-forespørsler med Maskinporten-token mot Altinns Virksomhet-API.

Leksjonen er delt opp i 3 hoveddeler:

1. Førstegangsoppsett nødvendig for å hente et Maskinporten-token.
   1. Lage et JSON Web Key (JWK) nøkkelpar.
   2. Registrere en Maskinporten-integrasjon i Samarbeidsportalen.
   3. Registrere den offentlige delen av nøkkelparet på Maskinporten-integrasjonen.
   4. Importere det forhåndslagde Maskinporten VER2 collection og legge til nye environment-variabler.
   5. Laste ned jsrsasign-js javascript via en REST-forespørsel i Postman.
2. Hente et Maskinporten-token
3. Bruke Maskinporten-token som autorisasjon på en forpørsel mot Altinns Virksomhet-API.

1. Førstegangsoppsett for bruk av Maskinporten-token i Postman

Førstegangsoppsettet trenger man bare utføre én gang. Etter at stegene er utført vil man ha verdiene for følgende environment-variabler:

Hvis man allerede har disse verdiene, og den offentlige nøkkelen er registrert på Maskinporten-integrasjonen, så kan man hoppe til [Steg 2] av denne leksjonen.

1.1 Lage et JSON Web Key nøkkelpar

TODO: Powershell-script for å lage JWK.

Etter å ha kjørt scripetet har man 2 filer:

1. JWK-<kid>-keypair.json - som skal brukes til i Postman som en environment-variabel.
2. JWK-<kid>-public-key.json - som skal registreres i Samarbeidsportalen i steg 1.3

1.2 Registrere en Maskinporten-integrasjon i Samarbeidsportalen

Logg inn på Samarbeidsportalen - Integrasjoner VER2. Her skal vi opprette en ny integrasjon med følgende oppsett:

Etter at denne er opprettet skal vi ta vare på

• Integrasjonens identifikator
• Scopes

1.3 Registrere den offentlige nøkkelen

Når du er inne på siden til din Maskinporten-integrasjon i Samarbeidsportalen, så kan man legge til nye nøkler ved å klikke på Egne public nøkler. I dialogen som dukker opp skal man lime inn innholdet av JWK-<kid>-public-key.json og trykke på Legg til.

Etterpå skal man se denne nøkkelen i Nøkler oversikten på siden.

1.4 Importere Maskinporten VER2 collection og lage environment-variabler

Vi har laget en Postman-collection som inneholder 2 forespørsler vi skal bruke i denne leksjonen. Denne kan importeres på samme måte som vi gjorde i en tidligere versjon.

• Importer Maskinporten VER2-collection fra lenken: https://raw.githubusercontent.com/Altinn/postman-examples/master/Collection/Maskinporten%20VER2.postman_collection.json

Forespørselene skal nå være tilgjengelig slik som på bildet under:

For at disse forespørselene skal fungere må vi legge til 3 nye environment-variabler i TT02-environmentet.

• Legg til følgende variabler og verdier:

  VARIABLE	TYPE	VALUE
  maskinporten-jwk	secret	Innholdet fra JWK-<kid>-keypair.json-filen fra steg 1.1
  maskinporten-client_id	default	Integrasjonens identifikator fra steg 1.2
  maskinporten-scope	default	Scopes fra steg 1.2

• Husk å lagre disse endringene.

1.5 Laste ned jsrsasign-js

Forespørselen som henter et Maskinporten-token er avhengig av et JavaScript som ikke er del av det som er tilgjengelig som standard i Postman. Dette løser vi ved å bruke en GET-operasjon som henter jsrsasign-js og legger det til det aktive environment.

1. Velg Last ned jsrsasign-js til environment forespørselen i Maskinporten VER2-collection.
2. Trykk på Send.

Etter å ha fått en respons med status 200 OK kan man finne en ny environment-variabel med navn jsrsasign-js. CURRENT VALUE skal være scriptet man mottok som svar på forespørselen.

Dette skjedde fordi forespørselen har følgende JavaScript under Tests-panelet:

pm.environment.set('jsrsasign-js', responseBody);

2. Hente Maskinporten-token

Forutsatt at alle stegene i engangsoppsettet var vellykkede så trenger man bare gjøre følgende:

1. Velg POST Maskinporten Token forespørselen i Maskinporten VER-collection.
2. Klikk på Send.

Hvis man mottar et svar med status 200 OK så skal man se følgende Body:

{
    "access_token": "<JWT>",
    "token_type": "Bearer",
    "expires_in": 3599,
    "scope": "altinn:enduser altinn:enduser/consentrequests.read"
}

Det er verdien av "access_token" som kalles Maskinporten-token. Verdien blir kopiert inn i det aktive environment som variabelen maskinporten-access_token som en del av denne forespørselen.

3. Bruke Maskinporten-token som autorisasjon

For å demonstrere Maskinporten-token autorisasjon mot Altinns Virksomhet-API har vi valgt ConsentRequests-endepunktet:

1. Velg GET consentRequests?serviceCode…-forespørselen under Altinn/user/ConsentRequests i Altinn-collection.
2. Slå av alle Query Params under Params-panelet.
   • Disse er ikke nødvendige for forespørselen vi skal gjøre nå.

For å bruke Maskinporten-token som autorisasjon på forespørsler i Postman skal man gjøre følgende.

1. I Authorization-panelet:
   1. Velg Type: Bearer Token
   2. Fyll inn {{maskinporten-access_token}} i Token-feltet.
      • Dette vil legge til en header på forespørselen. Authorization: Bearer <access_token>
2. Klikk på Send

Hvis Maskinporten-tokenet man fikk i svaret på del 2 fortsatt er gyldig skal man motta et svar fra Altinn med status 200 OK. I Body vil det da listes ut alle ConsentRequests som din organisasjon har. Det kan godt være at denne listen er tom, men så lenge man får et svar med status 200 OK så har vi klart å bruke Maskinporten-token som autorisasjon.

Hvis svaret derimot har status 401 IDX10223: Lifetime validation failed. The token is expired. ... så har det gått mer en 120 sekunder siden man hentet Maskinporten tokenet. Dette er svært sannsynlig hvis det er første gang man følger denne guiden steg for steg, men det løses enkelt ved å:

1. Sende POST Maskinporten Token fra del 2 på nytt.
2. Sende GET consentRequests?serviceCode…-forespørselen på nytt.

Endepunktene på Tjenesteeier- og Virksomhet-API aksepterer Maskinporten-token direkte, mens man på Sluttbruker-API må hente et Altinn-exchange-token. I neste leksjon vil vi vise hvordan man bruker Maskinporten-token for å hente et Altinn-exchange-token.

Se også

• REST-forespørsler med Altinn-exchange-token
• Hvordan importere Altinn API collection og environment
• Hvordan legge til et virksomhetssertifikat i Postman
• Nødvendig forarbeid - Postman introduksjon
• REST forespørsler mot åpne API-endepunkter