Spesifikasjon

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

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

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

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

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:

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

-----BEGIN RSA PRIVATE KEY-----
MIIEowIBAAKCAQEA3r4mIU7T+nTz4jysSGHuHqMoa41DM7KdJkr2WHOAucvnFcgc
TsX7AYmLNO5fX01lb67kOQnMPfJkpEyjGFn2aLCOdGQwINaHDscwa3/dkyDNYv81
wm9W+rfN6yRIyvyNOK34cS0/6unWIcdvz05cNqRBps/2N58mrSwVrSJzVczbe7no
Lb73pNfWJFpx2mXDQJMyEz+wMGi5V8XlyI748cW25KCgYtqKFY6phBxZsqeXT9t2
LFvAy1oRd1ybue+svwj3QcytptpTd/uechwInzPn3/fTiA7mcL+vXCpiQXpvVhZT
I+bFU3uS5M07ypHazmojGPkSxl3g5TWQUoHV1wIDAQABAoIBAQCAZpaubrWN1Gte
iGE8HI/aw20iir0piRZEI8RcesDC2gLtMHz4//HREgvYSG1cD86gke3n33kIYLmZ
aMA/4mRENzr3Z2XDGEekwjhsT7pX/PnIzpub6Pj38IrYuQLpWKrD+K2V+GK3NXMF
5+TRWTeZHBjoY0tpBuqRuy8HritUUn8EIDT1p3uu6j8BRofmjHQc6RUVFNeraYy5
ztZP+ENDvehTV1kXugvvD6U1SgWiTl3KJ0Kd7KlUNINpMZTPUMYEHGTYPfGSYoQn
97CKlQdtThblb+3BfEX3/V6IomQMIfbqpJnDMM03B7uxq6KBq/LlfoHLsfGisFy2
gooyIhThAoGBAPFdR+WIlJ0o4DcX4x+ImTxH9sR0s5HooPJsGlPuuaZHIL9k555j
2Q5zYUdF02/vaPA5rAssw8vZdH0X1nRGDtAdKj6od6ThqtQObTCXtLZRx/hus1Je
AZFfDWGKd62DMzeC8JrLwGYs91fyAWvEHNAKArFzKth3mcdOneoOzqZHAoGBAOw/
zaba4nLH+9Yu+w62Wymv0bk1EZd/wC/LUQnHP7jWv/aCBaTuOhLfNr1sy6Ji3bl7
DKTP6D807bT4CYS8N7lv7tsLjBzmeEqTGkRk6cAvETogcRBZtZHrB2dDkRPg2AGC
T1gHMmyDrUFsfRW8un6qSt3UQ+wXhqnqn3pge8vxAoGAWZX66ppANvkGB8zo8zpb
TgGT+SUrxXtnybMQLpkL9UivQfrs8WA0H2X59F9ZdFGTTJ7LWbZ60f3be9bONYgP
VXWNyYX0KpHMOztDkeatH4LJS0+jZW4Y/OEf8VVYyGFLME58iagYuJP2FoFvv5Uh
8KHWkBCkFYaG4HAwssBeOV8CgYBflPTMRBSIIdcG8d0LN8YsWID+cLUcWUhVTeoM
jbt/OgtSXYqRDv0Z84s/GkxM97kDOQCFkcRCBlUB+bRIKqpU8S9vGf3nF2ulqFxh
PX7BDYnnvYZg+hqW3cMSCWkh5L8f5SvazpadBq1LIex9pezCIH3HwAB2/ZGzH0TE
i1Kq0QKBgFPP1xUhMje4XKpoxvPPdEyxFX3Yp2sM0Zd5ja9rUJTRB+sN3e/5RQm0
7TExH90gZrvu79ubPLGxgCtdRtIyPsB1ISS7jV1Ww/xvAH/83PCeG1WQYlXBw3he
gXOJrGzMkzI2uGEyrkoFz9ljrSgOVDcf7RM9G5Frtf3PZVNVFnfQ
-----END RSA PRIVATE KEY-----

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:

ssh-keygen -f <<filnavn>>.pub -e -m PEM

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

-----BEGIN RSA PUBLIC KEY-----
MIIBCgKCAQEA3r4mIU7T+nTz4jysSGHuHqMoa41DM7KdJkr2WHOAucvnFcgcTsX7
AYmLNO5fX01lb67kOQnMPfJkpEyjGFn2aLCOdGQwINaHDscwa3/dkyDNYv81wm9W
+rfN6yRIyvyNOK34cS0/6unWIcdvz05cNqRBps/2N58mrSwVrSJzVczbe7noLb73
pNfWJFpx2mXDQJMyEz+wMGi5V8XlyI748cW25KCgYtqKFY6phBxZsqeXT9t2LFvA
y1oRd1ybue+svwj3QcytptpTd/uechwInzPn3/fTiA7mcL+vXCpiQXpvVhZTI+bF
U3uS5M07ypHazmojGPkSxl3g5TWQUoHV1wIDAQAB
-----END RSA PUBLIC KEY-----

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

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

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

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

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)