java-jwt Documentation

Technical Documentation: auth0/java-jwt

ℹ️ Provenance: Hybrid Fusion: auth0/java-jwt + auth0/docs · CodeWiki Reference · Recency: Active (< 180 days)

1. Project Overview & Quickstart (auth0/java-jwt) Copy Chapter

Note
As part of our ongoing commitment to best security practices, we have rotated the signing keys used to sign previous releases of this SDK. As a result, new patch builds have been released using the new signing key. Please upgrade at your earliest convenience.

While this change won't affect most developers, if you have implemented a dependency signature validation step in your build process, you may notice a warning that past releases can't be verified. This is expected, and a result of the key rotation process. Updating to the latest version will resolve this for you.

:books: Documentation - :rocket: Getting Started - :computer: API Reference :speech_balloon: Feedback

Documentation Copy Chapter

• Examples - code samples for common java-jwt scenarios.
• Docs site - explore our docs site and learn more about Auth0.

Getting Started Copy Chapter

Requirements Copy Section

This library is supported for Java LTS versions 8, 11, 17 and 21. For issues on non-LTS versions above 8, consideration will be given on a case-by-case basis.

java-jwt is intended for server-side JVM applications. Android applications should use JWTDecode.Android.

java-jwt supports the following algorithms for both signing and verification:

Note - Support for ECDSA with curve secp256k1 and SHA-256 (ES256K) has been dropped since it has been disabled in Java 15

Note - The RSASSA-PSS algorithms (PS256, PS384, PS512) rely on the JVM for RSASSA-PSS support, which is available natively from Java 11 onwards via the SunRsaSign provider (JDK-8146293). On Java 8, a security provider that implements RSASSA-PSS (such as BouncyCastle) must be registered on the classpath; no additional provider is bundled by this library.

:warning: Important security note: JVM has a critical vulnerability for ECDSA Algorithms - CVE-2022-21449. Please review the details of the vulnerability and update your environment.

Installation Copy Section

Add the dependency via Maven:

<dependency>
  <groupId>com.auth0</groupId>
  <artifactId>java-jwt</artifactId>
  <version>4.6.0</version>
</dependency>

or Gradle:

implementation 'com.auth0:java-jwt:4.6.0'

Create a JWT Copy Section

Use JWT.create(), configure the claims, and then call sign(algorithm) to sign the JWT.

The example below demonstrates this using the RS256 signing algorithm:

try {
    Algorithm algorithm = Algorithm.RSA256(rsaPublicKey, rsaPrivateKey);
    String token = JWT.create()
        .withIssuer("auth0")
        .sign(algorithm);
} catch (JWTCreationException exception){
    // Invalid Signing configuration / Couldn't convert Claims.
}

Verify a JWT Copy Section

Create a JWTVerifier passing the Algorithm, and specify any required claim values.

The following example uses RS256 to verify the JWT.

String token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXUyJ9.eyJpc3MiOiJhdXRoMCJ9.AbIJTDMFc7yUa5MhvcP03nJPyCPzZtQcGEp-zWfOkEE";
DecodedJWT decodedJWT;
try {
    Algorithm algorithm = Algorithm.RSA256(rsaPublicKey, rsaPrivateKey);
    JWTVerifier verifier = JWT.require(algorithm)
        // specify any specific claim validations
        .withIssuer("auth0")
        // reusable verifier instance
        .build();
        
    decodedJWT = verifier.verify(token);
} catch (JWTVerificationException exception){
    // Invalid signature/claims
}

If the token has an invalid signature or the Claim requirement is not met, a JWTVerificationException will be thrown.

See the examples and JavaDocs for additional documentation.

API Reference Copy Chapter

• java-jwt JavaDocs

Feedback Copy Chapter

Contributing Copy Section

We appreciate feedback and contribution to this repo! Before you get started, please see the following:

• Auth0's general contribution guidelines
• Auth0's code of conduct guidelines

Raise an issue Copy Section

To provide feedback or report a bug, please raise an issue on our issue tracker.

Vulnerability Reporting Copy Section

Please do not report security vulnerabilities on the public Github issue tracker. The Responsible Disclosure Program details the procedure for disclosing security issues.

2. Official Technical Reference & Guides (auth0/docs) Copy Chapter

Auth0 Documentation

This repository contains the Auth0 Quickstarts, but most other documentation content in this repository is no longer up to date, and is not the source of content at https://auth0.com/docs. Pull requests and issues for Quickstarts can still be submitted here, but most other content is no longer hosted on GitHub and therefore no longer open-source. If you are an Auth0 employee trying to make a change to other documentation, please submit a ticket or contact the Documentation Team to request access to our content management system.

Please review the Contributing Guidelines before sending a PR or opening an issue.

• If you are looking for the application that hosts the Docs content, see auth0-docs.
• If you would like to modify the Management API v2 API docs, they are generated from the api2 repository.

Both of the above repositories require team access.

Editing Docs Content Copy Chapter

Auth0 Docs are no longer maintained in this Github repository. Employees can request access to our content management system to update Docs directly. Outside contributors can submit requests under the Issues section in this repository.

Editing Quickstart Content Copy Chapter

• You can edit the Quickstarts by using the GitHub web editor and editing a file. This is best suited for typos and small changes.
• You can also pull down the /docs repo to your computer via Git and edit files in your local editor before pushing a new branch (or a branch to your own fork of the project). You can then go to GitHub.com and start a PR. We will be able to review the changes in a Heroku test application prior to merging.
• Lastly, you can run and test the docs site locally (access available to Auth0 employees only). This option is best suited for repeat contributors or for complex contributions. You gain the benefit of locally testing and viewing your changed or added pages, navigation, and config, but you also gain the complexity of dealing with the local docs app, setting it up, and keeping it updated.

Regardless of which option you use, please review any relevant sections of the Contributing Guidelines before sending a PR.

Issue Reporting Copy Chapter

If you find a bug or inaccuracy in the documentation content, please report it in this repository's issues section. Please do not report security vulnerabilities on the public GitHub issue tracker. The Responsible Disclosure Program details the procedure for disclosing security issues.

Author Copy Chapter

Auth0

License Copy Chapter

This project is licensed under the MIT license. See the LICENSE file for more info.

--- METRICS ---

• Files Extracted: 2
• Estimated Token Budget: ~2155 tokens
• Recency Window: Active (< 180 days)
• Canonical Reference: https://codewiki.google/github.com/auth0/java-jwt