Validating Identity Tokens
If the client support user logon, the following rules for validation of Identity Tokens must be applied:
The client must validate the token signature
- All HelseID Identity Tokens are signed using the key material found at https://helseid-sts.nhn.no/.well-known/openid-configuration/jwks. Tokens signed with other keys must be rejected.
If the client has local user identities, it must ensure that the locally signed in user is the same person as the user signing in to HelseID. This can be achieved by using the either of the following claims:
helseid://claims/identity/pid
,sub
(a hash of the PID), orhelseid://claims/hpr/hpr_number
.The client should assure that the user is authenticated by the identity provider at a valid security level. This can be achieved by checking the value of the
helseid://claims/identity/security_level
claim.The Issuer for the OpenID Provider, obtained from the Discovery endpoint, must exactly match the value of the
iss
claim.- If the client supports more than one identity provider, it must inspect the iss parameter from the token response, and correlate the value from this parameter to the
issuer
-value from the Discovery endpoint.
- If the client supports more than one identity provider, it must inspect the iss parameter from the token response, and correlate the value from this parameter to the
The Client must validate that the
aud
(audience) claim matches itsclient_id
value. This implies that only the client ID is a valid audience.The client must inspect the
exp
claim, and validate that the token has not yet expired.The Client should check the
auth_time
claim value and request re-authentication if it determines too much time has elapsed since the user logged in.The
iat
claim can be used to reject tokens that were issued too far away from the current time. The acceptable time range is up to the Client to decide.If a nonce value was sent in the call to either the PAR endpoint, or to the Authorization endpoint, the Client must check that a nonce claim is present, and that its value correlates to the one that was sent in the request. The Client should check the nonce value for replay attacks. The precise method for detecting replay attacks is Client specific.
Considerations about the lifetime of Identity Tokens
The lifetime of the Identity token should not be used to specify the lifetime of the user session. This means that the client should not correlate the value of the exp
claim to the user session. If the lifetime of the user session is to be checked, the value of the auth_time
claim can be applied.
General considerations
Identity Tokens are meant for the client, and should not be passed on to other parties, specifically APIs.
Identity Tokens should be persisted in the client to allow for a seamless sign-out experience
ℹ️ The use of libraries
If a client library is available for your software, you must use it. However, it is up to you to ensure that the library actually mangages the steps cited above.
⚠️ A note about Access tokens
The client must not inspect, nor validate the Access token that is returned from HelseID. As the client is concerned, the Access token is opaque, and is only for the API to inspect.