1 Spesifikasjon
2 Beskrivelse
3 Flyt
4 JWT-struktur
5 RSA offentlig nøkkel
- 5.1 Alternativ med å genereer nytt nøkkelpar for formålet
- 5.2 Alternativ med å trekke ut offentlig nøkkel i korrekt format fra et virksomhetsertifikat

Spesifikasjon

JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants
Assertion Framework for OAuth 2.0 Client Authentication and Authorization Grants

Beskrivelse

For “confidential clients” så er det påkrevd for klienten å autentisere seg mot Helsenorge sikkerhetstjenesten ved å sende med et JWT via “client_assertion”-parameteren.

Dette er JWT (se struktur under) som er signert med klientens private nøkkel. For at autentiseringen kan gjøre i Helsenorge sikkerhetstjeneste, må den tilhørende offentlige nøkkelen på forhånd distribueres til Helsenorge og knyttes til definisjonen av den aktuelle API-klient.

Flyt

Det må generes et RSA-nøkkelpar for formålet. Alternativt kan man benytte et eksisterende nøkkelpar som f.eks. er knyttet til et offentlig virksomhetssertifikat. Det gjøres av aktøren som skal kommunisere med Helsenorge.
Offentlig nøkkel på korrekt format (se under om RSA offentlig nøkkel) distribueres til NHN og NHN må registre den offentlige nøkkel på klienten
Ved kall til Helsenorge sin sikkerhetstjeneste så må et JSON Web Token (JWT) generes og signeres ved bruk av privatnøkkelen. JWT legges ved på requester til de endepunktene i sikkerhetstjenesten som krever det

JWT-struktur

Plassering	Claim	Verdi

Plassering	Claim	Verdi
Header	alg	RS256
	typ	JWT
Payload	iss	<<ClientId>> (ApiClientId)
	jti	Unik GUID
	sub	<<ClientId>> (ApiClientId)
	exp	Når tokenet utløper. Helsenorge aksepterer kun tokens som har exp < 2 minutter fra iat
	aud	Verdi som støttes er: System-til-system: Fast miljøuavhengig verdi: “sikkerhet.helsenorge.no” OIDC, støtter to verdier: Fast miljøuavhengig verdi: “sikkerhet.helsenorge.no” Verdi som ble returnert for “issuer” fra .well-known endepunktet. NB! Denne er forskjellig for de forskjellige test-miljøene (og PROD)! Eks TEST01: https://eksternapi.hn.test.nhn.no/sts/oidcprov/v3
	iat	Tidspunkt når tokenet opprettes
	nbf	Tidspunkt fra når tokenet er gyldig (vanligvis samtidig med det ble opprettet)

RSA offentlig nøkkel

Alternativ med å genereer nytt nøkkelpar for formålet

Det kan gjøres ved å f.eks. benytte ssh-keygen:

ssh-keygen -t rsa -b 2048 -m PEM -C ""

Kommandoen generer 2 filer:

Fil 1: <<filnavn>> som inneholder den private RSA-nøkkelen

Fil 2: <<filnavn>>.pub som inneholder den offentlige (public) RSA-nøkkelen

ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDeviYhTtP6dPPiPKxIYe4eoyhrjUMzsp0mSvZYc4C5y+cVyBxOxfsBiYs07l9fTWVvruQ5Ccw98mSkTKMYWfZosI50ZDAg1ocOxzBrf92TIM1i/zXCb1b6t83rJEjK/I04rfhxLT/q6dYhx2/PTlw2pEGmz/Y3nyatLBWtInNVzNt7uegtvvek19YkWnHaZcNAkzITP7AwaLlXxeXIjvjxxbbkoKBi2ooVjqmEHFmyp5dP23YsW8DLWhF3XJu576y/CPdBzK2m2lN3+55yHAifM+ff99OIDuZwv69cKmJBem9WFlMj5sVTe5LkzTvKkdrOaiMY+RLGXeDlNZBSgdXX

NHN må få tilsendt den offentlige nøkkelen i PKCS#1-format. Konvertering av fil #2 innholdet til riktig format gjøres med kommandoen:

Som gir følgende output som så sendes over til NHN:

Alternativ med å trekke ut offentlig nøkkel i korrekt format fra et virksomhetsertifikat

Dette kan f.eks. gjøres med følgende OpenSSL kommandoer:

Trekke offentlig nøkkel ut fra virksomhetssertifikat (gir annet format enn det som skal distribueres til Helsenorge)

openssl x509 -pubkey -noout -in cert.cer -out pubkey-pem.txt

(Der cert.cer er filnavnet på fila som inneholder virksomhetsertifikatet)

Konvertere output fra forrige kommando til korrekt PubKey-format

openssl rsa -pubin -in pubkey-pem.txt -RSAPublicKey_out -out pubkey-rsa.txt

(Der pubkey-pem.txt er filnavnet som var output fra forrige kommando og pubkey-rsa.txt er fila som skal distribueres til Helsenorge)