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 thedecode()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.
See AlsoWhat is an API key?
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
Learn more
I'm an expert in web security and authentication, with a demonstrated depth of knowledge in the concepts surrounding secure data transmission and token-based authentication. My expertise encompasses the use of JSON Web Tokens (JWT) for ensuring the integrity of data transmission and facilitating secure authentication and authorization processes.
In the provided article about Auth0's use of JWT, several key concepts are discussed, and I'll break down each one:
-
JSON Web Token (JWT):
- Used by Auth0 for secure data transmission, authentication, and authorization.
- Tokens need to be parsed and validated to ensure they are not compromised and the signature is authentic.
-
Token Validation:
- Tokens should be verified to reduce security risks, such as tampering, misuse, or expiration.
- Validation involves checking the structure, claims, and signature of the JWT.
-
JWT Signing Algorithms:
- Auth0 supports RS256 (RSA encryption with SHA-256) and HS256 (HMAC with SHA-256) signing algorithms.
- The choice of algorithm impacts token signature generation.
-
JWT Validation Process:
- The validation process involves parsing or decoding the current and original hash values and comparing them to verify the authenticity of the token signature.
-
Middleware and Third-Party Libraries:
- Middleware in web frameworks, such as ASP.NET Core, is recommended for JWT validation.
- Third-party libraries are suggested if not using Auth0 SDKs. Libraries should support the chosen signing algorithm and necessary validations.
-
Library Usage Recommendations:
- Libraries should be chosen based on the supported signing algorithm and required validations.
- General recommendations include using the
verify()method overdecode()for obtaining claims and carefully following library instructions to avoid security risks.
-
Manual JWT Validation:
- Discouraged due to the potential for improper implementation and security vulnerabilities.
- Most JWT libraries handle validation automatically.
-
RS256 Token Verification:
- To visually verify RS256-signed tokens, Auth0 recommends obtaining the public key from the JWKS (JSON Web Key Set) endpoint and using it on JWT.io to verify the token signature.
-
Best Practices and Further Learning:
- The article concludes with a section on recommended best practices for token validation and references to additional resources for learning about JWT claims, validating ID tokens, validating access tokens, and token best practices.
In summary, the article provides a comprehensive guide on using JWT, ensuring secure token validation, and making informed choices when it comes to libraries and algorithms. This information is crucial for developers and security professionals working on web applications and APIs.
