Page Comparison

General advice when using JWTs

• Using JWTs to handle sessions introduces new risks. Allways do a thorough risk assessment before you deploy to your production environment.

• Using JWTs assumes that all involved secrets are handled in a proper way in both API-clients and APIs. Secrets could be both passwords and cryptographic key material. Always make sure your secrets are kept safe!

• Do not accept unsafe JWTs with the JOSE header {"alg": none; }. JWTs should always be signed and should use a valid and correct signature scheme

• If a JWT contains sensitive data it should be encrypted

Things to consider when using Access Tokens

• A "self contained" JWT can not be revoked until it expires. Consider using referenced tokens if the token provides access to sensitive or high-risk data.

• Access Tokens should be opaque to the client, they are meant for the API.

  • The lifetime of an access token is returned as a separate value to the client.

• Access Tokens should have a life-time that is as short as possible.
  As a general principle: the more sensitive data an API exposes the shorter the life-time should be.

• To enhance the user experience sessions with a long life-span should be combined with Access Tokens that have short life-span. You can acheive this by using refresh tokens on the client.

Always verify the integrity of the JWT

• Always validate the token signature

  • All HelseID tokens are signed using the key material found at https://helseid-sts.nhn.no/.well-known/openid-configuration/jwks. Tokens signed using other keys must be rejected.

• Make sure your libraries and frameworks always validates the token signature

• HelseID only offers signatures based on asymmetric algorithms

DO NOT BLINDLY TRUST THE VALUE IN CLAIMS

Examples:

• “kid” - do not perform certificate requests before the values are validated and verified

• “jku” or “x5u” are header values that point to a URL. Do NOT follow these URLs before they are validated in order to avoid SSRF attacks

Always validate claims in the Access Token

• Always verify the "exp" claim to make sure the token hasn’t expired

• Always verify the claim "nbf" to make sure the token actually is "active"

• When verifying claims with timestamps, take into account that there may be some time skew between the token issuer and your internal systems.

• Always verify the claim "iss" to make sure that the token issuer is someone you actually trust

• Always verify the claim "aud" to make sure that the token is intended for you

• Reject the request if the "aud" claim is missing

• Consider rejecting tokens with multiple values in the “aud” claim.

• If you use "scopes" for access control you must always make sure that the values in the “scope” claims are valid and correct.

• Always validate and verify that the value in the claim “helseid://claims/identity/assurance_level“, alternatively “helseid://claims/identity/security_level”, corresponds with the requirements for your API.

• Consider validating and verifying the value in the claim "helseid://claims/identity/pid".

• Consider validating and verifying the value in the claim "helseid://claims/hpr/hpr_number".

• Consider validating and verifying the value in the claims containing organizational identitfiers, e.g. “helseid://claims/client/claims/orgnr_parent“ and “helseid://claims/client/claims/orgnr_child“