1 Introduksjon
2 JWT System token
- - 2.1.1 Header
  - 2.1.2 Payload
- 2.2 Eksempel
  - 2.2.1 Encoded
  - 2.2.2 Decoded
- 2.3 Hvordan parse og validere
  - 2.3.1 Endepunkt der signeringssertifikat kjeden kan hentes ut

Introduksjon

I enkelte tilfeller vil Helsenorge eller PVK kalle eksterne systemers API’er på vegne av innbygger uten at innbygger nødvendigvis er logget inn. Se UseCases her: https://helsenorge.atlassian.net/wiki/spaces/HELSENORGE/pages/14745656

I dette tilfellet vil alle API kall inneholde et JWT systemtoken som er uttedt av Helsenorge STS.

JWT System token

Alle metodekall benytter POST og vil inneholde et JWT-token utstedt av Helsenorge STS. For replikeringsmeldinger om endret status på Personverninnstillinger i PVK benyttes et SystemToken (dette fordi endringen ikke nødvendigvis skjer direkte fra innbygger selv via Helsenorge, eller at endringen replikeres ved "retry-situasjoner" etter at innbygger er logget ut.).

For tjenester som ikke benytter seg av basic authentication så overføres tokenet via HTTP headeren:

Authorization: Bearer <<Tokenverdi>>

Authorization: Bearer <<Tokenverdi>>

Dersom basic authentication allerede benyttes, benyttes custom header som bærer av tokenet:

X-Authorization: Bearer <<Tokenverdi>>

X-Authorization: Bearer <<Tokenverdi>>

Claim key	Claim navn	Beskrivelse

Claim key	Claim navn	Beskrivelse
alg	Algorithm	Hvilken algoritme som benyttes. Vil være "RS256" dvs. RSA-SHA256 Ønskelig at denne benyttes aktivt slik at vi senere kan gå sømløst over til evnt. sterkere algoritmer Viktig å validere at denne ikke inneholder en tom verdi (kjent sårbarhet)
kid	Key ID	Thumbprint til sertifikatet som ble benyttet til å generere token. Når JWT-tokenet skal valideres av den som mottar tokenet skal alltid sertifikatkjeden som kommer fra JWK-endepunktet benyttes.
typ	Type	Type token det er, vil alltid være "JWT"
ver	Version	Egendefinert header-verdi som sier hvilken versjon tokenet er
typ_2	Type 2	Egendefinert header-verdi som sier hvilken type JWT som Helsenorge utsteder. Vil være "system_ws_sync"

Payload

Claim key	Claim navn	Beskrivelse

Claim key	Claim navn	Beskrivelse
scp	Scope	Vil inneholde en liste (separert med mellomrom) over hvilke dataområder/opplysninger som tokenet gir klienten (client_id) tilgang til. API/systemet som mottar tokenet fra Helsenorge må validere at det “scope” deres data representerer er inkludert i JWT-tokenet før det gis tilgang. For mulige verdier se: https://helsenorge.atlassian.net/wiki/spaces/HELSENORGE/pages/16056337
client_id	Client Id	En GUID som identifiserer system klienten på Helsenorge som utfører kallet. Mottager trenger ikke forholde seg til denne verdien.
client_name	Client Name	Navnet til system klienten på Helsenorge som utfører kallet. Mottager trenger ikke forholde seg til denne verdien.
endusertype	End user type	Hva slags sluttbruker tokenet er utstedt til. Vil alltid være "system"
aud	Audience	API/systemet som mottar tokenet fra Helsenorge bør validere at verdien i “aud” er lik den identifikator som er avtalt å benytte mellom partene. For PVK er dette den "partKode" som er avtalt mellom partene og som definerer "eier" av den aktuelle personverninnstilling.
nbf	Not Before	Tidspunktet fra når tokenet er gyldig. Vil alltid ha samme verdi som tidspunktet det ble generert på
exp	Expiration Time	Tidspunktet for når tokenet utløper. Standard er 20 minutter
iat	Issued At	Tidspunktet for når tokenet ble generert
iss	Issuer	Hvem som har generert tokenet, vil alltid være "sikkerhet.helsenorge.no"

Eksempel

Encoded

eyJhbGciOiJSUzI1NiIsImtpZCI6IkY0NkVDQjI5RjhCOTk5NEQyMjg2QjA3M0MxQ0VBNkE1MkJCNzQ2RkMiLCJ0eXAiOiJKV1QiLCJ2ZXIiOjEsInR5cF8yIjoic3lzdGVtX3dzX3N5bmMifQ.eyJqdGkiOiI1NmRkMmM2MC1hMTljLTRjODctYTZlNi00YmYxYjJiNTViYTQiLCJzY3AiOiJwZXJzb252ZXJuaW5uc3RpbGxpbmdlciIsImNsaWVudF9pZCI6ImVmNWRjZDA5LTMwMjUtNDJhNC04ZDgyLTE5ZjVmNzMwMDY2ZiIsImNsaWVudF9uYW1lIjoiU2VuZE1lbGRpbmdUaWxBa3RvciBCYXRjaCIsImVuZHVzZXJ0eXBlIjoic3lzdGVtIiwiYXVkIjoiUkYiLCJuYmYiOjE2MDI2NTgzMjUsImV4cCI6MTYwMjY1OTUyNSwiaWF0IjoxNjAyNjU4MzI1LCJpc3MiOiJzaWtrZXJoZXQuaGVsc2Vub3JnZS5ubyJ9.GMhNdOlxrDnI8CaCi3pqpPL4YPAIRpCeXTTNh3YTOnOAO8vYnCCdFJ6OKewv3E0agcGIPPHAmHYuFGuRzuil1AhaGmVjwXFoPjuN1GVa8ZPXWXUGhhYABwRr4di7eDn1WxH3mYLfbK9SxEWHrzsaon1J0HEcVcnZUUxf8v3mSN760cS6YyzJWlT_CMmQHhB5wjbvyNXXj4uiJZdsC26StVCtJ9_fzrU08R9CVnTi6cbJwNGbEg_QZ3eIzBF8l6iQCY7Zwn2fc7o91gbiM2XvOFStOxFfGk4mPh_NbhxakqwpJdkFAAYI3yLKKFCXnj5FtA43sp020BcKXHsa3TT38w

Decoded

Hvordan parse og validere

Det finnes mange 3. parts biblioteker som gjør det enkelt å lese ut data fra tokenet og å validere det. Siden https://jwt.io. har en oversikt over ulike JWT-biblioteker for ulike tekniske plattformen, i tillegg til en fin JWT dekoder. Det eksterne systemet er ansvarlig for å validere innholdet i JWT tokenets payload i henhold til sine forretningsregler (se beskrivelse i tabellen over). Vi anbefaler at det benyttes 5 minutter’s “clock skew” ved validering at “nfb”, “exp” og “iat”.

Endepunkt der signeringssertifikat kjeden kan hentes ut

Dersom ekstrent system har tilgang til Internett:

Dersom eksternt system kun har tilgang til Helsenettet:

Sertifikatet som er benyttet i signeringen av JWT har den key-identifier som finnes i JWT header (“kid” i Header). Dvs. at jwk-endepunktet returnerer dette sertifikatet og resten av sertifikatkjeden opp til “Root-CA”. Det er derfor kun behov for å hente sertifikatkjede på nytt fra JWK-endepunktet dersom “kid” i JWT-tokenet endres.