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]
Header
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 |
Subject ID. The value must be set to the Client ID of your client. |
iat |
The time the JWT was issued. Expressed in seconds as "epoch time". |
jti |
A unique ID for the JWT. A client assertion shall only be used once, and the uniqueness of this value is used to enforce this rule 1. |
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. |
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. For backward compatibility, the client may also use the token endpoint of that environment. |
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.
1This is not yet supported in HelseID, but will be utilized in the near future.