1 Introduksjon
2 Teknisk skisse
3 Eksternt innbygger access token
- 3.1 Format
  - 3.1.1 Header
  - 3.1.2 Payload
  - 3.1.3 Signatur
- 3.2 Eksempeler
  - 3.2.1 Eksempel 1: Innbygger som seg selv
  - 3.2.2 Eksempel 2: Forelder representerer barn
- 3.3 Hvordan parse og validere tokenet
  - 3.3.1 Endepunkt der signeringssertifikat kjeden skal hentes ut
- 3.4 Hvordan overføres til JWT-tokenet fra Helsenorge til eksternt API
  - 3.4.1 REST
  - 3.4.2 SOAP

Introduksjon

Helsenorge har støtte for en federert sikkerhetsmodell som muliggjør å sende med et identitet/access-token på eksterne API-forespørsler som Helsenorge gjør. Dette tokenet inneholder informasjon om hvilken innbygger som gjør oppslaget, hvilken innbygger det gjøres oppslag på og hvilke informasjonselementer/data tokenet har tilgang til. Se aktuelle UseCase her: https://helsenorge.atlassian.net/wiki/spaces/HELSENORGE/pages/14745656

Innbyggeren som gjør oppslaget vil være basert på ID-porten påloggingen som ble gjort, mens personen det gjøres oppslag på vil kunne være en annen basert på gyldige representasjonsforhold i PVK. PVK gjør sin vurdering av representasjonsforhold på bakgrunn av fullmakter som finnes i Personvernkomponenten og barn som finnes i Folkeregisteret.

Formålet med denne modellen er å heve sikkerheten på API-er som tilbyr sensitive data. Dette ved at man går fra system-til-system hvor det er en trust mellom Helsenorge og integrasjonspartneren, til også å kreve et innbygger token som kun kan bli generert på bakgrunn av en lovlig ID-porten innlogging.

Teknisk skisse

Eksternt innbygger access token

Eksternt access token er av type JSON Web Token også kalt JWT. Tokenet er self contained som betyr at alt av token informasjonen ligger i selve tokenstrengen som sendes over. Mottagende API kan validere gyldigheten av tokenet ved å hente ut sertifikatkjeden for Helsenorge sikkerhetstjeneste fra sikkerhetstjeneste sitt jwk-endepunkt (se nederst på siden).

Format

encodeBase64(json-header) + '.' + encodeBase64(json-payload) + '.' + encodeBase64(signature)

encodeBase64(json-header) + '.' + encodeBase64(json-payload) + '.' + encodeBase64(signature)

Kort claimnavn	Fullt claimnavn	Beskrivelse

Kort claimnavn

Fullt claimnavn

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"

Payload

Kort claimnavn	Fullt claimnavn	Beskrivelse

Kort claimnavn	Fullt claimnavn	Beskrivelse
sub	Subject	Fødselsnummeret til den personen man agerer på vegne av, dvs. enten representert innbygger eller innlogget innbygger dersom innbyggeren representerer seg selv. Ved kall fra Helsenorge er dette også "pasient" kontekst, dvs. den man gjør oppslag på. API/Systemet som mottar JWT-tokenet må alltid kontrollere at de data som forespørres i API-kallet faktisk tilhører den pasient som er “sub” i JWT-tokenet.
birthdate (nytt claim Q2-2024, for å understøtte at fødselsdato ikke lenger kan utledes av fødselsnummer)	Subject Fødselsdato	Fødselsdato til den personen man agerer på vegne av, dvs. enten representert innbygger eller innlogget innbygger dersom innbyggeren representerer seg selv. Eks: "2011-01-07"
act_sub	Actor Subject	Fødselsnummeret til personen som gjør oppslaget, dvs. alltid innlogget innbygger
act_type	Actor Type	Kan inneholde kun en av følgende verdier: segselv : Innbyggeren representerer seg selv fullmakt 1): Innlogget bruker representerer en annen gjennom fullmakt foreldrerepresentasjon 2): Innlogget innbygger representerer et barn man kan representere Det gis i dag ikke informasjon i tokenet om det er ordinær fullmakt eller tildelt fullmakt (for ikke samtykkekompetent innbygger). Helsenorge har to kriterier som begge må være oppfylt for at foreldre kan representere barn: Foreldren må ha Foreldreansvar for barnet i Folkeregisteret. Minst en av foreldrene med foreldreansvar i Folkeregisteret må bo på samme addresse som barnet. (Da vil begge forelder kunne representere barnet, gitt at begge har Foreldreansvaar i folkeregisteret).
act_type_detail (nytt claim Q2-2024, for å gi mer detaljert informasjon om type representasjonsforhold)	Actor Type details	Det er identifisert behov for å gi mer detaljert informasjon om type representasjonsforhold. Det er valgt å innføre et nytt claim for dette i stedet for å utvide lovlige verdier i eksisterene claim for represenatsjonstype. Dette er gjort for å beholde “bakover-kompabilitet”. Eksterne aktører som tar i bruk dette nye claimet (“act_type_detail”), trenger ikke lenger å forhodle seg til det opprinnelige (“act_type”). Claimet kann ha følgende verdier: "ingen_representasjon" : Innlogget og representert innbygger er den samme (dvs. ingen representasjon) "foreldreansvar_ordinar": Tilfredstiller Helsenorge sine krav til å kunne representere barn "foreldreansvar_dagligomsorg": Tilfredstiller Helsenorge sine krav til å kunne representere barn. I tillegg må denne foreldren, som nå representerer barnet, bo på samme adresse som barnet. "fullmakt_ordinar": Innlogget bruker representerer "pasienten" med ordinær fullmakt "fullmakt_tildelt": Inlogget innbygger representerer en pasient som ikke selv har samtykkekompetanse
act_birthdate (nytt claim Q2-2024, for å understøtte at fødselsdato ikke lenger kan utledes av fødselsnummer)	Actor Subject Fødselsdato	Fødseldato til personen som gjør oppslaget, dvs. alltid innlogget innbygger Eks: "1986-07-10"
scp	Scope	Vil inneholde en kommaseparert liste over hvilke dataområder/opplysninger om personen (sub) det gjøres oppslag på, som tokenet gir innlogget bruker (act_sub) 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. Liste over scopes som er definert på Helsenorge finner du her: https://helsenorge.atlassian.net/wiki/spaces/HELSENORGE/pages/16056337
aud	Audience	Kan være med på den enkelte integrasjon. Dette avtales i så fall mellom Aktør og Helsenorge. Derom denne er med: API/systemet som mottar tokenet fra Helsenorge skal validere at verdien i “aud” er lik den identifikator som er avtalt å benytte mellom partene.
nfb	Not Before	Tidspunktet for når tokenet er gyldig. Vil alltid ha samme verdi som tidspunktet det ble generert på. Vi anbefaler at det benyttes 5 minutter “clock skew” slik at man reduserer feilsituasjoner med servere som tidsmessig ikke er i sync.
exp	Expiration Time	Tidspunktet for når tokenet utløper Vi anbefaler at det benyttes 5 minutter “clock skew” slik at man reduserer feilsituasjoner med servere som tidsmessig ikke er i sync.
iat	Issued At	Tidspunktet for når tokenet ble generert. Vil aldri være gyldig i mer enn 30 minutter Vi anbefaler at det benyttes 5 minutter “clock skew” slik at man reduserer feilsituasjoner med servere som tidsmessig ikke er i sync.
iss	Issuer	Hvem som har generert tokenet, vil alltid være "sikkerhet.helsenorge.no

Signatur

Tokenet genereres og signeres i Helsenorge STS ved bruk av et dedikert virksomhetssertifikat for Helsenorge STS. Signeringsalgoritmen som benyttes er RSA-SHA256.

Eksempeler

Eksempel 1: Innbygger som seg selv

Encoded

eyJhbGciOiJSUzI1NiIsImtpZCI6IkU5RTBGQzM3NDhFNDdCNjVFOERENUFFMDk1QzRBOTU5NTM1MkU0QTMiLCJ0eXAiOiJKV1QiLCJ2ZXIiOjIsInR5cF8yIjoiY2l0aXplbl93c19zeW5jIn0.eyJqdGkiOiI1YjQ2Zjk2My1lYWE3LTQ2YTctYjk1Yy1iMmE5NjE3NDVhMGQiLCJzdWIiOiIxMzExNjkwMDIxNiIsImJpcnRoZGF0ZSI6IjE5NjktMTEtMTMiLCJhY3Rfc3ViIjoiMTMxMTY5MDAyMTYiLCJhY3RfdHlwZSI6InNlZ3NlbHYiLCJhY3RfdHlwZV9kZXRhaWwiOiJpbmdlbl9yZXByZXNlbnRhc2pvbiIsImFjdF9iaXJ0aGRhdGUiOiIxOTY5LTExLTEzIiwic2NwIjoicmVzZXB0ZXIiLCJhdWQiOiJyZXNlcHRmb3JtaWRsZXIiLCJuYmYiOjE3MTM0Mjg1MzksImV4cCI6MTcxMzQ0NjUxMywiaWF0IjoxNzEzNDI4NTM5LCJpc3MiOiJzaWtrZXJoZXQuaGVsc2Vub3JnZS5ubyJ9.kSsbW7IOSx7hNMy10HIL6_SExXtEbGbWpvZOMxaKFQkJRBj6nI-2ixkeXwD9TioCdyFLj7AkUCh81eOyGR3uwLGsWf9nEuTcFeDqJ0rje-vfh9R9_xzQ7awTv1dd4nvYFbZ8cld6RT6vbyDbjIhi_L0GLjKfbtxhcW1gPqbCaCkqPWBdWrpmzBSB8jfphJd03teAwDYqoIboqzTlUP_mdi_XSRsbbptvufI2EeXnIQ_-3-P-_Bcx4UFXSI7M0TtYVHlRxsbwDOYDH2MXbsk7WJ8ttI2N9RetZOFBfjWCyHlr8I23oQUEHNeZ-nwqpXJvT5iJn6XErFRCiPWSKPCl5BnlWdlEn-llRzUR8vuqjtE8xBFEZVMbpGfa0MVvYOwDpg7ql9CAHEsegwgDL4F2uFy2CUQsH4Y4lFldesN1G7Yln7CHgUxhXw2CfqzLbnyUKItgraMTdjfO-FGoNP7uDsrZ7yhLD0toGX3_VzpbCYMgA_Yt7ZGdks0qgYdOX-48

Decoded

F.eks. ved å benytte https://jwt.io/

Eksempel 2: Forelder representerer barn

Encoded

eyJhbGciOiJSUzI1NiIsImtpZCI6IkU5RTBGQzM3NDhFNDdCNjVFOERENUFFMDk1QzRBOTU5NTM1MkU0QTMiLCJ0eXAiOiJKV1QiLCJ2ZXIiOjIsInR5cF8yIjoiY2l0aXplbl93c19zeW5jIn0.eyJqdGkiOiI4ZDQyZGVhYS1iZmY0LTRjYTQtYjdjYy0wNTEwNmQyOTYzYzMiLCJzdWIiOiIwMTAxMTE1ODExNyIsImJpcnRoZGF0ZSI6IjIwMTEtMDEtMDEiLCJhY3Rfc3ViIjoiMTMxMTY5MDAyMTYiLCJhY3RfdHlwZSI6ImZvcmVsZHJlcmVwcmVzZW50YXNqb24iLCJhY3RfdHlwZV9kZXRhaWwiOiJmb3JlbGRyZWFuc3Zhcl9kYWdsaWdvbXNvcmciLCJhY3RfYmlydGhkYXRlIjoiMTk2OS0xMS0xMyIsInNjcCI6InJlc2VwdGVyIiwiYXVkIjoicmVzZXB0Zm9ybWlkbGVyIiwibmJmIjoxNzEzNDI4NTQ1LCJleHAiOjE3MTM0NDY1NDAsImlhdCI6MTcxMzQyODU0NSwiaXNzIjoic2lra2VyaGV0LmhlbHNlbm9yZ2Uubm8ifQ.ql-MPh7DlIFlMn7LPTOabS_1HX7eLkuYfPF07MDCBJ4F3kPDWvS7_K_diM5QkHzMJVzBRfMp5pr0-1XTyV6YRwL-9pGs2h2V2nYVnD2MSYF9TeINIIy1Og2MmilRDF61JxIiq_EyRAMiv3GDbW2Rt1dT-1VLEdUaba5D_Q8ue2QwqBLVH6gi7lrUVdZw8vzw4l41pgXZ0DvN2FtmH5voRGF9bVmTODSmdisedmK6nyEaSUotftj__U9AXk_enB2rp-aqLq1dk5uflLQeldewTUZkf74dVlDWuWdra06fKnFctUqZZQSFn6LROWGj-4NpxNHmledkbEHIeXrhbtGoFxtOqdrEblkLB7VZB8-eb9SfFbxlCCW_LMpNsOHRxjTb-FVF9Qpeaz98GAgO5Ecp5OoRW-m6BOQWvgc8tchxlXMuye9zLmMWy3Wcarhzgq0Gs5hs8jokbOlezQLPOrV8REIRbkK9FrfWBfGZEos7tDwSqxgE5blyYRI4BdwuXpQX

Decoded

F.eks. ved å benytte

Hvordan parse og validere tokenet

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 skal 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.

Hvordan overføres til JWT-tokenet fra Helsenorge til eksternt API

REST

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

Authorization: Bearer <<Tokenverdi>>

Authorization: Bearer <<Tokenverdi>>

Dersom basic authentication benyttes så må en custom header benyttes:

X-Authorization: Bearer <<Tokenverdi>>

X-Authorization: Bearer <<Tokenverdi>>

SOAP

For SOAP tjenester så finnes det ulike varianter for å overføre tokenet, den enkleste løsningen er at tjenesten har en egen custom header som en del av tjenetsekontrakten og at denne inneholder et felt hvor tokenet kan legges ved.