HelseID requires that all clients authenticate using the private_key_jwt mechanism as described in the OpenID Connect specificationDokumentet har blitt flyttet til Utviklerportalen.
This document summarizes how a client application should build the client assertion object and what requirements HelseID has for the content.
The structure of a client assertion
A client assertion is a signed JWT (Json Web Token) that is structurally equivalent to any token issued by HelseID. It consists of a header that describes the object, a payload that contains the actual claims and finally a signature made with the clients private key.
The following is an example of a typical client assertion:
| Code Block |
|---|
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 |
When we decode the Base64 encoded values we get the following:
| Code Block | ||
|---|---|---|
| ||
{
"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] |
As you can see the client assertion is a standard JWT. The header should contain claims that describe the JWT itself:
...
alg
...
The signing algorithm used to create the signature part of the JWT. HelseID only supports asymmetric signing algorithms.
...
kid
...
The Key ID for the key used to create the signature part of the JWT
...
typ
...
The type of object this JWT is. Should be set to “JWT”
The body of the JWT should contain the following claims:
...
sub
...
Subject ID. Should be set to the Client ID of your client
...
iat
...
The time the JWT was issued. Expressed in seconds
...
jwt
...
A unique id for the JWT. A client assertion should only be used once and this value will be used to enforce that rule in the future
...
nbf
...
The earliest time that the JWT can be used. Expressed in seconds
...
exp
...
The last time the JWT can be used. Expressed in seconds. Must be no more than 60 seconds in the future.
...
iss
...
The issuer of the JWT. Should be set to the Client ID of your client
...
aud
...
Audience for the JWT. Should be set to either the url of the HelseID environment your client is calling or the token endpoint of that enviroment.
The signature of the JWT should be created using an assymetric signing algorithm and must be one of the following: RS256, RS384, RS512, ES256, RS384, ES512, PS256, PS384, PS512. The list of accepter signing algorithms may change in the future, and updated list of accepted algorithms is maintained in the HelseID Security Profile for Clientshas been moved. Please see the document at this page (English).