Validate JSON Web Tokens

Overview

Key Concepts

Read about JSON Web Tokens (JWTs) Auth0 uses for access, ID, refresh, and logout tokens.
Review signing algorithms to understand what a signature is on a token.
Validate JWTs to make sure no one has tampered with them.
Use Auth0 SDKs, middleware, or one of the third-party libraries at JWT.io to validate JWTs.

Auth0 uses JSON Web Token (JWT) for secure data transmission, authentication, and authorization. Tokens should be parsed and validated in regular web, native, and single-page applications to make sure the token isn’t compromised and the signature is authentic. Tokens should be verified to decrease security risks if the token has been, for example, tampered with, misused, or has expired. JWT validation checks the structure, claims, and signature to assure the least amount of risk.

To visually inspect a JWT, visit JWT.io or use the JWT Debugger Chrome Extension).

The JWT token signature is generated using a Signing Algorithm. While tokens can use multiple signing algorithms, Auth0 supports RS256, RSA encryption with SHA-256 hash function or HS256, HMAC message authentication code (MAC) with SHA-256. To learn more about Auth0’s recommended algorithm, read Signing Algorithms.

When validating a JWT, generally, the current hash value and the original hash value are parsed, or decoded, then compared to verify the token signature is authentic. All of our backend API quickstarts use SDKs that perform JWT validation and parsing for you.

Parse and validate

If you are not using one of our SDKs that perform JWT validation and parsing for you, you can parse and validate a JWT by:

Using any existing middleware for your web framework.
Choosing a third-party library from JWT.io.
Manually implementing the checks described in specification RFC 7519 > 7.2 Validating a JWT.

We strongly recommend that you use middleware or one of the existing open source third-party libraries to parse and validate JWTs. At JWT.io, you can find libraries for various platforms and languages, such as .NET, Python, Java, Ruby, Objective-C, Swift, and PHP.

Middleware

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.

Third-party libraries

If you choose a third-party library, choose 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 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 none), a 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.

General recommendations for using third-party libraries:

For obtaining claims from JWT, use the verify() method to validate the claims and the signature. Avoid using the decode() method to validate a token, especially if it's coming from a public client.
Carefully follow all instructions on how to use the chosen library. The library could rely on default values or settings that could create security risks.

Manually implement checks

We discourage doing manual JWT validation since it might be easy to improperly implement and miss some important details that will lead to serious security vulnerabilities. Most JWT libraries take care of JWT validation for you. Visit JWT.io to find a JWT library for your platform and programming language.

For instructions on how to manually validate a JWT, see RFC 7519. All Auth0-issued JWTs have a JSON Web Signature (JWS), meaning they are signed rather than encrypted.

Verify RS256-signed tokens

To visually verify RS256-signed tokens:

Go to Dashboard > Applications.
Go to the Settings view, and open Advanced Settings.
Go to the Certificates view, locate the Signed Certificate field, and copy the Public Key.
Navigate to the JWT.io website, locate the Algorithm dropdown, and select RS256.
Locate the Verify Signature section, and paste the Public Key you previously copied in place of the content in the field that begins with -----BEGIN PUBLIC KEY-----.

To verify the signature of a token from one of your applications:

We recommend that you get the Public Key from your tenant's JWKS here: https://{yourDomain}/.well-known/jwks.json

Secure