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

  • 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), or helseid://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 Identifier for the OpenID Provider (which is obtained from the metadata / discovery endpoint) must exactly match the value of the iss (issuer) 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 Identifier.

  • The Client must validate that the aud (audience) Claim matches its client_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 on.

  • 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 Authentication Request, a nonce Claim must be present and its value checked to verify that it is the same value as the one that was sent in the Authentication 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.