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. Verdien må være den samme som klient-ID-verdien for klienten som skal autentiseres.
`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 1.
`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.
`iss`	Utstederen av JWT-en. Verdien må settes til 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. For bakoverkompatibilitet kan klienten også bruke Token-endepunktet for det samme HelseID-miljøet.

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.

^{1Dette er ennå ikke en funksjonalitet i HelseID, men funksjonaliteten vil bli tatt i bruk i nær framtid.}