Bruk av client assertion for klientautentisering i HelseID

Dette dokumentet oppsummerer hvordan en klientapplikasjon må bygge et client assertion-objekt, og hvilke krav som stilles for innholdet i et slikt objekt.

Termer
Klient En klient (client) som definert i RFC 6749. I kontekst av HelseID er en klient en programvareinstallasjon som følger denne sikkerhetsprofilen.
JWT Json Web Token er en åpen standard (RFC 7519) som definerer en kompakt og selvstendig måte for sikker overføring av informasjon mellom parter som et JSON-objekt. Informasjonen kan bli verifisert som gyldig ettersom den er signert digitalt.
Nøkkelord Nøkkelordene må, må ikke, skal, skal ikke, bør, and kan i dette dokumentet må tolkes slik som nøkkelordene must, must not, shall, shall not, should, og may i RFC2119.

HelseID krever at alle klienter blir autentisert med bruken av private_key_jwt-mekanismen, som beskrevet på denne siden.

Vær oppmerksom på at HelseID ikke vil autentisere klienter ved bruk av andre autentiseringsmetoder, som for eksempel «Mutial TLS» eller «Client Secret».

Strukturen på en client assertion

En client assertion er en signert JWT (Json Web Token). Den består av

  • En header som beskriver objektet
  • Et innhold (payload) som inneholder claims
  • En signatur som har blitt generert med klientens privatnøkkel

Den følgende strengen viser et eksempel på en typisk client assertion, Base64-enkodet:

eyJhbGciOiJSUzI1NiIsImtpZCI6IkFFMTZGQUFBQUFDM0U1OTk4QkQxOUNCODk1REI5NUU5IiwidHlwIjoiSldUIn0.eyJzdWIiOiI3ZjQwMzU0My1lN2JmLTRlNDItOTk4OC1mYzI5ZDYxYTI1NjMiLCJpYXQiOiIxNjc3NzQzODAzIiwianRpIjoiODkyYmEzZDQ0YTM3NDExZWJjOTI0ODIyMzQxNzYxNTciLCJuYmYiOjE2Nzc3NDM4MDMsImV4cCI6MTY3Nzc0Mzg2MywiaXNzIjoiN2Y0MDM1NDMtZTdiZi00ZTQyLTk5ODgtZmMyOWQ2MWEyNTYzIiwiYXVkIjoiaHR0cHM6Ly9oZWxzZWlkLXN0cy50ZXN0Lm5obi5uby9jb25uZWN0L3Rva2VuIn0.P9kMUfLjuT67ZXoppCDKH_8YUvgv_7pZCyi_QQV_c-ntz9XcNciQ7_4Wrbq_b2AxiyF7sM3jQUMH6PaQF96h9FYJ2_S8uLzCKMee8zzH_ku3pvQ7_qQFWXAZ30_vmLVPDAhEfcT2VzFkvH8IwiqVfl-0iSKbwsOsSTSRsApyWy7QXJsFxxEiRDDCad6N3Se_nLRVRfeY3FqhHxua4-JwyObcHGuHaCF8kBZ94FMQTyQXOQI2Vz61jk05KRb29sUjlbYT2gK_No1Zb361Od6uiFV-X4cAub-zkcVK4TXhUvVOkMEWftKsOd8VHtucMuJS6ZoHmzBatHfzBgWmeF4AJQ7MtJGZEvpwDmWvil6T4ETk4ABT-kgPqVHNNyVgzq3QiAURiW77KZJZeGH2c1oP8MITRrGPa1FZTBwcdq_59Jibfdiu2az6bBI2BF0W_CzWLEULmz5JED1ak2hRX1hXeU7g2Qi8vrg290vALeHb4KovbOuutSCAoe5_uKIbvzUIVqLvAWLUfNnyQkZNoy-15-jI7RNzUdq3xfQbqiS7aCVyxc8vGmv6VXo3WsP1G6EX5hDbA0yaC03k1xCcZO-Zl7hXn16VOuDNOlo3xXcUjLQt8FLQMizXfTsfEDpwi1W7Y7utMR3kXqXynwq8DMHw_9-riOr-qg62dJWNjUXakjw

Når vi dekoder denne strengen, får vi den følgende JWT-strukturen:

{
  "alg": "RS256",
  "kid": "AE16FAAAAAC3E5998BD19CB895DB95E9",
  "typ": "JWT"
}.{
  "sub": "YOUR CLIENT ID",
  "iat": 1677743803,
  "jti": "892ba3d44a37411ebc92482234176157",
  "nbf": 1677743803,
  "exp": 1677743863,
  "iss": "YOUR CLIENT ID",
  "aud": "https://helseid-sts.test.nhn.no/"
}.[Signature]

Headeren i denne JWT-en må inneholde følgende claim, som beskriver trekk ved JWT-en:

Claim-type Beskrivelse
alg Signeringsalgoritmen som har blitt brukt for å lage signaturen for JWT-en. HelseID godtar bare asymmetriske signeringsalgoritmer (se delen om bruk av signatur under).
kid Nøkkel-ID for nøkkelen som ble brukt for å lage signaturen for JWT-en.
typ JWT-objektets type. Verdien må settes til JWT.

Innhold

Innholdet i JWT-en må inneholde følgende claim:

Claim-type Beskrivelse
sub Subjekt-ID for JWT-en. Verdien må være den samme som klient-ID-verdien for klienten som skal autentiseres.
iss Utstederen av JWT-en. Verdien må være den samme som klient-ID-verdien for klienten som skal autentiseres.
aud Mottaker (audience) av JWT-en. Verdien må settes til URL-en for HelseID-miljøet som klienten skal kalle. I testmiljøet til HelseID vil denne URL-en være https://helseid-sts.test.nhn.no, og i produksjonsmiljøet til HelseID vil denne URL-en være https://helseid-sts.nhn.no. For bakoverkompatibilitet kan klienten også bruke URL-en for Token-endepunktet i det samme HelseID-miljøet, men dette anbefalses ikke.
iat Tidspunktet når JWT-en ble utstedt. Verdien blir gitt i sekunder som «epoch time».
jti En unik ID for JWT-objektet. En client assertion skal bare brukes én gang, og det at denne verdien er unik, blir brukt for å verifisere at denne regelen blir opprettholdt. Verdien kan for eksempel bli satt som en UUID. (Dette er ennå ikke en funksjonalitet i HelseID, men funksjonaliteten vil bli tatt i bruk i nær framtid.)
nbf Det tidligste tidspunktet når JWT-en kan brukes. Verdien blir gitt i sekunder som «epoch time».
exp Det seneste tidspunktet når JWT-en kan brukes. Verdien blir gitt i sekunder som «epoch time». Denne verdien skal ikke bli satt til mer enn 60 sekunder i fremtiden.

Bruk av signatur

JWT-signaturen må genereres med bruk av en asymmetrisk algoritme, og denne algoritmen må være en av algoritmene som finnes i dokumentet Krav til kryptografi.