Validate JSON Web Tokens
To parse and validate a JSON Web Token (JWT), you can:
- Use any existing middleware for your web framework.
- Choose a third-party library from JWT.io.
- Manually implement the checks described in specification RFC 7519 > 7.2 Validating a JWT.
Many web frameworks, such as ASP.NET Core, include JWT middleware that handles JWT validation. Typically, this is the best route to take because the middleware integrates well with the framework's overall authentication mechanisms.
If you choose a third-party library, remember to pick a library that supports the signing algorithm you selected when you registered your application or API with Auth0. Also, be aware that not all libraries validate all JWT claims. At JWT.io, you can see which validations each library supports (look for the green check marks).
Most third-party libraries will implement one method to verify a JWT and build in various arguments to allow you to customize the verification.
For example, if you are using Node.js and the node-jsonwebtoken library, then you would call the jwt.verify() method. This method supports an
algorithms argument to allow you to customize your allowed algorithms (make sure you disallow
secretOrPublicKey argument that you populate with either the secret or the RSA public key (depending on selected signing algorithm), and other input arguments that allow you to customize claim validation. If parsing fails, then the library returns a JsonWebTokenError error with the message
jwt malformed, after which you must reject the associated request.
Manually implement the checks
To validate a JWT, your application needs to:
- Check that the JWT is well formed.
- Check the signature.
- Check the standard claims.
If any of these steps fail, then the associated request must be rejected.
Check that the JWT is well-formed
Ensure that the JWT conforms to the structure of a JWT. If this fails, the token is considered invalid, and the request must be rejected.
- Verify that the JWT contains three segments, separated by two period ('.') characters.
- Parse the JWT using JWT.io to extract its components. The first segment is the Header, the second is the Payload, and the third is the Signature. Each segment is base64url encoded.
- Base64url-decode the Header, ensuring that no line breaks, whitespace, or other additional characters have been used, and verify that the decoded Header is a valid JSON object.
- Base64url-decode the Payload, ensuring that no line breaks, whitespace, or other additional characters have been used, and verify that the decoded Payload is a valid JSON object.
- Base64url-decode the Signature, ensuring that no line breaks, whitespace, or other additional characters have been used, and verify that the decoded Signature is a valid JSON object.
Check the signature
The last segment of a JWT is the Signature, which is used to verify that the token was signed by the sender and not altered in any way. The Signature is created using the Header and Payload segments, a signing algorithm, and a secret or public key (depending on the chosen signing algorithm).
To verify the signature, you will need to:
Check the signing algorithm.
Confirm that the token is correctly signed using the proper key. Check the Signature to verify that the sender of the JWT is who it says it is and that the message wasn't changed along the way.
Remember that the Signature is created using the Header and Payload segments, a signing algorithm, and a secret or public key (depending on the chosen signing algorithm).
To verify that the signature is correct, you need to generate a new Base64url-encoded signature using the public key (RS256) or secret (HS256) and verify that it matches the original Signature included with the JWT:
- Take the original Base64url-encoded Header and original Base64url-encoded Payload segments (Base64url-encoded Header + "." + Base64url-encoded Payload), and hash them with SHA-256.
- Encrypt using either HMAC or RSA (depending on your selected signing algorithm) and the appropriate key.
- Base64url-encode the result.
Locate Public Key
For debugging purposes, you can visually inspect your token at jwt.io; for this purpose, you can also locate your public key in the Auth0 Dashboard. Look in Applications>Settings>Advanced Settings>Certificates and locate the Signing Certificate field.
For HS256: Retrieve the
client_secretfrom Auth0's Management API using the Get a Client endpoint.
For debugging purposes, you can visually inspect your token at jwt.io; for this purpose, you can also locate your secret in the Auth0 Dashboard. For applications, look in Settings and locate the Client Secret field. For APIs, look in Settings and locate the Signing Secret field. (Note that this field is only displayed for APIs using the HS256 signing algorithm.)
If the generated signature does not match the original Signature included with the JWT, the token is considered invalid, and the request must be rejected.
Check standard claims
Before using the token, you should retrieve the following standard claims from the decoded Payload and perform the following checks:
- Token expiration (
exp, Unix timestamp): The expiration date/time must be after the current date/time and should match what you set for your token lifetime.
- Token issuer (
iss, string): The issuing authority inside the token must match the issuing authority (
issuer) identified in your Auth0 tenant's discovery document, which exists at
Additional checks are required depending on whether the JWT you are validating is an ID Token or an Access Token. To learn about the additional requirements, see Validate ID Tokens or Validate Access Tokens.