Using Client Assertions for client authentication in HelseID

This document summarizes how a client application must build the client assertion object and what requirements HelseID demands for this content.

Definitions
Client A Client as defined in RFC 6749. In context of HelseID a client is an installation of a software that follows this security profile.
JWT Json Web Token is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed.
Keywords The keywords must, must not, shall, shall not, should, and may in this document are to be interpreted as described in RFC2119.

HelseID requires that all clients are authenticated by use of the private_key_jwt mechanism as described in this page.

Please be advised that HelseID will not authenticate clients by means of any other authentication method, such as "Mutual TLS", or "Client Secret".

The structure of a client assertion

A client assertion is a signed JWT (Json Web Token). It consists of

  • A header that describes the object
  • A payload that contains the actual claims
  • A signature made with the Client's private key

The following string is an example of a typical client assertion, Base64-encoded:

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 string, we get the following JWT structure:

{
  "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]

The header in this JWT must contain claims that describe the JWT itself:

Claim type Description
alg The signing algorithm used to create the signature part of the JWT. HelseID only supports asymmetric signing algorithms (see the part about signature usage below).
kid The Key ID for the key used to create the signature part of the JWT.
typ The type of object this JWT is. The value must be set to JWT.

Body

The body of the JWT must contain the following claims:

Claim type Description
sub The Subject ID for the JWT. The value must be set to the Client ID of your client.
iss The issuer of the JWT. The value must be set to the Client ID of your client.
aud The audience for the JWT. This value must be set to the URL of the HelseID environment your client is calling. In the test environment for HelseID, this URL will be https://helseid-sts.test.nhn.no, and in the production environment for HelseID, the URL will be https://helseid-sts.nhn.no. For backward compatibility, the client may also use the URL for the Token endpoint for the same HelseID environment, but this is not recommended.
iat The time the JWT was issued. Expressed in seconds as "epoch time".
jti A unique ID for the JWT. It can for example be set as an UUID. A client assertion shall only be used once, and the uniqueness of this value is used to enforce this rule. (This is not yet supported in HelseID, but will be utilized in the near future.)
nbf The earliest time that the JWT can be used. Expressed in seconds as "epoch time".
exp The last time the JWT can be used. Expressed in seconds as "epoch time". This value shall not be set to more than 60 seconds in the future.

Signature usage

The signature of the JWT must be created using an asymmetric signing algorithm, and the algorithm must be one of the algorithms found in the document Requirements for cryptography.