java-jwt

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

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

Getting Started

Requirements

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:

JWS	Algorithm	Description
HS256	HMAC256	HMAC with SHA-256
HS384	HMAC384	HMAC with SHA-384
HS512	HMAC512	HMAC with SHA-512
RS256	RSA256	RSASSA-PKCS1-v1_5 with SHA-256
RS384	RSA384	RSASSA-PKCS1-v1_5 with SHA-384
RS512	RSA512	RSASSA-PKCS1-v1_5 with SHA-512
PS256	RSA256PSS	RSASSA-PSS with SHA-256
PS384	RSA384PSS	RSASSA-PSS with SHA-384
PS512	RSA512PSS	RSASSA-PSS with SHA-512
ES256	ECDSA256	ECDSA with curve P-256 and SHA-256
ES384	ECDSA384	ECDSA with curve P-384 and SHA-384
ES512	ECDSA512	ECDSA with curve P-521 and SHA-512

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

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

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

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

• java-jwt JavaDocs

Feedback

Contributing

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

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

Vulnerability Reporting

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

---