HelseID requires that all clients authenticate using the private_key_jwt mechanism as described in the OpenID Connect specification.

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:

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:

{
  "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 Clients.

Using client assertions for client authentication in HelseID

The structure of a client assertion