"Invalid JOSE Header, 'kid' is Required" Error During Token Validation

Knowledge Articles
1

Overview

This article explains the following error, which occurs when an application or API receives a JSON Web Token (JWT) that is missing the Key ID (kid) in its header, but the application is configured to expect one for signature validation.

“Invalid token: invalid jose header, ‘kid’ is required”

Applies To

  • JSON Web Token (JWT)
  • JSON Object Signing and Encryption (JOSE) Header
  • RS256 and HS256 Signing Algorithms

Cause

The root cause of this error is a mismatch between the token signing algorithm used by the issuer (Auth0) and the validation algorithm expected by the receiving application or API.

The kid (Key ID) is a header claim in a JWT that specifies which key should be used to validate the token’s signature.

  • RS256 (Asymmetric Algorithm): When a token is signed with RS256, it uses a private key. The kid is included in the token’s header so the receiving application can look up the corresponding public key from the issuer’s JSON Web Key Set (JWKS) endpoint to verify the signature.
  • HS256 (Symmetric Algorithm): When a token is signed with HS256, it uses a shared secret. Since the same secret is used for both signing and validation, a kid is not necessary and is not included in the token’s header.

The error occurs when the application is configured to validate tokens using the RS256 algorithm (and therefore requires a kid), but it receives a token that was signed using the HS256 algorithm.

Solution

To resolve this issue, ensure that the signing algorithm configured in the Auth0 application settings matches the algorithm the client application or API is configured to validate.

The recommended solution is to use the RS256 signing algorithm, which is more secure and the standard for modern applications.

  1. Update Auth0 Application Settings:
  • Navigate to the Auth0 Dashboard.
  • Go to Applications > Applications and select the relevant application.
  • Scroll to the bottom of the Settings page and select Show Advanced Settings.
  • Select the OAuth tab.
  • In the JsonWebToken Signature Algorithm field, select RS256.
  • Select Save Changes.
  1. Update Client Application/API:
  • Ensure the client application or API is configured to validate the incoming JWT using the RS256 algorithm.
  • The application should be configured to fetch the public keys from your Auth0 tenant’s JWKS endpoint (e.g., https://<AUTH0_DOMAIN>/.well-known/jwks.json) to perform the signature validation.

By aligning the signing and validation algorithms to RS256, the kid will be present in the token header, allowing the application to perform the validation successfully.