Client Assertion

Owned by Lars-Erik Kindblad
Last updated: May 21, 2024 by sven.christiansen
2 min read

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

Plassering

Claim

Verdi

Header

alg (string)

RS256

 

typ (string)

JWT

Payload

iss (string)

<<ClientId>> (ApiClientId)

 

jti (string)

Unik GUID

 

sub (string)

<<ClientId>> (ApiClientId)

 

exp (int)

Når tokenet utløper. Helsenorge aksepterer kun tokens som har exp < 2 minutter fra iat

 

aud (string)

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 (int)

Tidspunkt når tokenet opprettes

 

nbf (int)

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:

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)