Validating Access Tokens

If an API uses HelseID for authorization purposes, the following rules for validation of Access tokens must be applied:

  • The API must validate the signature of all incoming Access Tokens according to [RFC7515] using the algorithm specified in the alg Header Parameter in the Access Token. The API must reject any Access Token in which the value of alg is "none". The API must use the HelseID public key for signature validation of the Access Token.

  • The API must verify that the typ header value is at+jwt or JWT, and reject tokens carrying any other value.

  • The API must verify that the Issuer Identifier for HelseID (which is obtained from the HelseID metadata endpoint) is an exact match for the value of the iss (issuer) claim.

  • The API must validate that the aud (audience) claim matches the audience ("kortnavn") as it is set up in HelseID Selvbetjening (the self-service portal). The Access token must be rejected if

    • The aud claim is missing
    • The aud claim does not contain an audience value that is an exact match to the audience set up in HelseID Selvbetjening.

  • The API should validate that it is the only audience in the Access Token. Access Tokens with multiple audiences are not recommended but may be acceptable in some cases.

  • The API must verify the exp claim to make sure the Access Token is not expired. You may provide for some small leeway, usually no more than a few seconds, to account for clock skew.

  • The API must verify the nbf to make sure the token is active. Implementers may provide for some small leeway, usually no more than a few seconds, to account for clock skew.

  • If the API uses scopes for access control, it must make sure that the values in the scope claims are consistent with the scope values that are set up in HelseID Selvbetjening (self-service portal).

If the API is requiering information about a logged in user in the Access token:

  • An API that requires information about a logged in user must validate both the users identity (PID or HPR number), as well as the security level of the identity, by inspecting the following claims:
    • Claim for PID: helseid://claims/identity/pid
    • Claim for HPR number: helseid://claims/hpr/hpr_number
    • Claim for security level: helseid://claims/identity/security_level

Have a look at this document for the claim values.