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]
Header
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.