1 Spesifikasjon
2 Beskrivelse
3 Flyt
4 JWT-struktur
5 Offentlig nøkkel
- 5.1 Alternativ 1: PEM
- 5.2 Alternativ 2: JWK
6 Valg av algoritme
7 Nøkkelbytte
8 Årsaker til avvisning

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" er det påkrevd at klienten autentiserer seg mot Helsenorge sikkerhetstjeneste ved å sende med et JWT via "client_assertion"-parameteren.

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

Flyt

API-klienten må generere et nøkkelpar for formålet. Det gjøres av aktøren som skal kommunisere med Helsenorge. Se "Offentlig nøkkel" under for hvilke nøkkeltyper og formater som støttes. MERK! Nøkkelparet skal kun benyttes for kommunikasjon mot Helsenorge OIDC-provider, og ikke benyttes mot andre autorisasjonsservere.
Offentlig nøkkel på et av de støttede formatene (se under) distribueres til NHN, og NHN registrerer den offentlige nøkkelen på klienten.
Ved kall til Helsenorge sin sikkerhetstjeneste må et JSON Web Token (JWT) genereres og signeres med privatnøkkelen. JWT legges ved på requester til de endepunktene i sikkerhetstjenesten som krever det.

JWT-struktur

Del	Claim	Beskrivelse

Del	Claim	Beskrivelse
Header	alg (string)	Signeringsalgoritme. PS256 anbefales for nye klienter. Se "Valg av algoritme" under.
	typ (string)	JWT
	kid (string)	Nøkkel-ID. Hvis nøkkelen er registrert med en `kid`, bør `kid` i JWT-headeren settes til samme verdi.
Payload	iss (string)	<<ClientId>>
	jti (string)	Unik GUID
	sub (string)	<<ClientId>>
	exp (int)	Når tokenet utløper. Bør settes til maks 10 sekunder.
	aud (string)	Verdien som returneres fra well-known-endepunktet i claimet "issuer". Det skal kun være én `aud`-verdi. Flere verdier gir avvisning. API-klientsystemet må validere at det er samsvar mellom det som returneres fra well-known i "issuer" og base-URL-en for well-known-endepunktet den kalte (og som er root of trust). Eks: Test01: `https://eksternapi.hn.test.nhn.no/sts/oidcprov/v3` Test02: `https://eksternapi.hn2.test.nhn.no/sts/oidcprov/v3` QA: `https://eksternapi.hn.qa.nhn.no/sts/oidcprov/v3` Prod: `https://eksternapi.helsenorge.no/sts/oidcprov/v3`
	iat (int)	Tidspunkt når tokenet opprettes
	nbf (int)	Tidspunkt fra når tokenet er gyldig (vanligvis samtidig med at det ble opprettet)

Offentlig nøkkel

Helsenorge sikkerhetstjeneste støtter to formater for den offentlige nøkkelen som registreres på klienten:

Format	Nøkkeltype	Minimum nøkkelstørrelse

Format	Nøkkeltype	Minimum nøkkelstørrelse
PEM	RSA	2048 bit
JWK (JSON)	RSA (`"kty": "RSA"`)	2048 bit
JWK (JSON)	EC (`"kty": "EC"`)	256 bit

Merk:

Nøkkelen som sendes inn må være en offentlig nøkkel. Innsending som inneholder privatnøkkel blir avvist.
PEM-formatet støtter kun RSA. Skal du bruke EC-nøkkel, må den sendes inn som JWK. En EC-nøkkel i PEM-format blir avvist.
Send aldri privatnøkkelen til NHN.

Alternativ 1: PEM

Både PKCS#1 (-----BEGIN RSA PUBLIC KEY-----) og SPKI/X.509 SubjectPublicKeyInfo (-----BEGIN PUBLIC KEY-----) aksepteres.

Eksempel på generering med ssh-keygen:

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

Kommandoen genererer 2 filer:

Fil 1: <<filnavn>> som inneholder den private RSA-nøkkelen. Denne skal ikke deles med noen.

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

ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQ...

Konverter fil #2 til PEM med:

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

Output som sendes til NHN ser slik ut:

-----BEGIN RSA PUBLIC KEY-----
MIIBCgKCAQEA...
-----END RSA PUBLIC KEY-----

Alternativ 2: JWK

Den offentlige nøkkelen kan sendes inn som en JWK i JSON-format. Nøkkelen må ikke inneholde privatnøkkel-parametere (for RSA: d, p, q, dp, dq, qi, for EC: d).

Eksempel, RSA med PS256:

{
  "kty": "RSA",
  "use": "sig",
  "alg": "PS256",
  "kid": "hn-api-klient-2026-01",
  "n": "3r4mIU7T-nTz4jysSGHuHqMoa41DM7KdJkr2WHOAucvnFcgcTsX7...",
  "e": "AQAB"
}

EC-nøkler ("kty": "EC") er også støttet. Da brukes feltene crv, x og y i stedet for n og e.

kid i JWK-en bør settes, og må i så fall være lik kid i headeren på client_assertion-JWT-en.

Valg av algoritme

Algoritme	Nøkkeltype	Status

Algoritme	Nøkkeltype	Status
PS256	RSA	Anbefalt for nye klienter
PS384 / PS512	RSA	Godtas
ES256 / ES384 / ES512	EC	Godtas
RS256	RSA	Godtas

Helsenorge ønsker at nye aktører bruker PS256. RS256 godtas fortsatt, av hensyn til eksisterende klienter.

Både RS256 og PS256 bruker samme RSA-nøkkel. Forskjellen ligger i hvordan signaturen beregnes, ikke i nøkkelen. Du trenger derfor ikke nytt nøkkelpar for å gå fra RS256 til PS256, kun endre alg og signeringen.

Nøkkelbytte

Når en ny offentlig nøkkel registreres på en klient, settes en utløpsdato på klientens eksisterende nøkler. Disse er fortsatt gyldige i 24 timer.

Årsaker til avvisning

Symptom	Årsak

Symptom	Årsak
Avvist client_assertion	`exp` er mer enn 2 minutter etter `nbf`
Avvist client_assertion	Mer enn én `aud`-verdi i tokenet
Avvist client_assertion	`aud` er ikke lik "issuer" fra well-known for miljøet du kaller
Avvist client_assertion	`iss` er ikke lik ClientId (GUID)
Avvist client_assertion	Signert med annen nøkkel enn den som er registrert, eller nøkkelen er utløpt

Client Assertion