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.

📚 Documentation - 🚀 Getting Started - 💻 API Reference 💬 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, and 17. 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
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

⚠️ 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.4.0</version>
</dependency>

or Gradle:

implementation 'com.auth0:java-jwt:4.4.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 an 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