auth0-java-jwt

Java Versions

• Supported LTS versions: 8, 11, 17, and 21.
• For non-LTS versions above 8, support is provided on a case-by-case basis.

Platform Note

• java-jwt is intended for server-side JVM applications.
• For Android applications, use JWTDecode.Android instead.

Algorithm Implementation Notes

• RSASSA-PSS (PS256, PS384, PS512): Relies on JVM support. Available natively from Java 11+ via SunRsaSign. On Java 8, you must register a security provider like BouncyCastle on the classpath.
• ECDSA (ES256K): Support for secp256k1 with SHA-256 has been dropped because it was disabled in Java 15.

By default, java-jwt validates standard DateTime claims: iat (issued at) must be in the past, exp (expiration) must be in the future, and nbf (not before) must be in the past. If validation fails, a JWTVerificationException is thrown.

You can use acceptLeeway(int seconds) to allow a grace period for all DateTime claims. You can also override the leeway for specific claims using acceptExpiresAt(int seconds).

// Apply 1 second leeway to nbf, iat, and exp
JWTVerifier verifier = JWT.require(algorithm)
    .acceptLeeway(1)
    .build();

// Apply 1 second leeway to nbf and iat, but 5 seconds specifically for exp
JWTVerifier verifier = JWT.require(algorithm)
    .acceptLeeway(1)
    .acceptExpiresAt(5)
    .build();

Add the java-jwt dependency to your project using Maven or Gradle to use JSON Web Tokens (JWT) in your server-side JVM applications.

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

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

Use the JWTCreator.Builder to add custom payload and header claims to a new JWT. Use withHeader(Map<String, Object> header) for headers and withClaim(String name, T value) for payload claims.

String jwt = JWT.create()
        .withHeader(headerMap)
        .withClaim("string-claim", "string-value")
        .withClaim("number-claim", 42)
        .withClaim("bool-claim", true)
        .withClaim("datetime-claim", Instant.now())
        .sign(algorithm);

After successful verification, the verify() method returns a DecodedJWT object. You can use first-class methods to retrieve standard claims (like getSubject() or getAudience()) or use getClaim(String name) to retrieve custom claims. Custom claims return a Claim object, which provides methods like asString() to extract the value in the desired type.

DecodedJWT jwt = JWT.require(algorithm)
        .build()
        .verify("a.b.c");

// standard claims can be retrieved through first-class methods
String subject = jwt.getSubject();
String aud = jwt.getAudience();
// ...

// custom claims can also be obtained
String customStringClaim = jwt.getClaim("custom-string-claim").asString();

To verify a JWT, create a JWTVerifier using JWT.require(algorithm). You can chain methods to specify required claim validations (e.g., .withIssuer("auth0")). Call verifier.verify(token) to validate the token. If the signature is invalid or claim requirements are not met, a JWTVerificationException is thrown.

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
}

When building a JWTVerifier, you can enforce requirements on custom claims using the following methods:

• withClaim(String name, T value): Ensures the claim matches a specific value.
• withClaimPresence(String name): Ensures the claim exists in the token.
• withClaim(String name, BiPredicate<Claim, DecodedJWT> predicate): Allows for custom validation logic based on the claim value and the decoded JWT.

JWTVerifier verifier = JWT.require(algorithm)
        .withClaim("number-claim", 123)
        .withClaimPresence("some-claim-that-just-needs-to-be-present")
        .withClaim("predicate-claim", (claim, decodedJWT) -> "custom value".equals(claim.asString()))
        .build();
DecodedJWT jwt = verifier.verify("my.jwt.token");

To create a JWT, use JWT.create(), configure the desired claims (such as issuer), and then call sign(algorithm) with a valid Algorithm instance. If the signing configuration is invalid or claims cannot be converted, a JWTCreationException will be thrown.

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.
}

Version 4.0 introduces support for java.time.Instant when creating JWT claims. Use the following methods on JWTCreator.Builder to add date/time claims:

• withExpiresAt(Instant expiresAt): Adds the exp claim.
• withNotBefore(Instant notBefore): Adds the nbf claim.
• withIssuedAt(Instant issuedAt): Adds the iat claim.
• withClaim(String claimName, Instant value): Adds a custom claim with an Instant value.
• withNullClaim(String claimName): Adds a claim with the literal value null.

Version 4.0 allows for custom claim validation using BiPredicate. Use the withClaim method on the Verification object to pass a predicate that evaluates the Claim and the DecodedJWT.

Additionally, you can validate that a claim has a specific Instant value using:

• Verification#withClaim(String name, Instant value)