JWT Verification

/**
 * Returns a Verification builder with the algorithm to be used to validate token signature.
 * @param algorithm that will be used to verify the token's signature
 * @return Verification builder
 * @throws IllegalArgumentException if the provided algorithm is null
 */
public static Verification require(Algorithm algorithm) throws IllegalArgumentException;

import com.auth0.jwt.JWT;
import com.auth0.jwt.algorithms.Algorithm;
import com.auth0.jwt.interfaces.JWTVerifier;

Algorithm algorithm = Algorithm.HMAC256("secret");
JWTVerifier verifier = JWT.require(algorithm)
    .withIssuer("auth0")
    .build();

/**
 * Require a specific Issuer ("iss") claim.
 * @param issuer the required Issuer value. If multiple values are given, the claim must match one of them
 * @return this same Verification instance
 */
Verification withIssuer(String... issuer);

/**
 * Require a specific Subject ("sub") claim.
 * @param subject the required Subject value
 * @return this same Verification instance
 */
Verification withSubject(String subject);

/**
 * Require a specific Audience ("aud") claim.
 * @param audience the required Audience value. If multiple values are given, the claim must contain all of them
 * @return this same Verification instance
 */
Verification withAudience(String... audience);

/**
 * Require a specific Audience ("aud") claim.
 * @param audience the required Audience value. If multiple values are given, the claim must contain at least one of them
 * @return this same Verification instance
 */
Verification withAnyOfAudience(String... audience);

/**
 * Require a specific JWT Id ("jti") claim.
 * @param jwtId the required JWT Id value
 * @return this same Verification instance
 */
Verification withJWTId(String jwtId);

// Single issuer verification
JWTVerifier verifier = JWT.require(algorithm)
    .withIssuer("https://my-app.com")
    .withSubject("user123")
    .build();

// Multiple allowed issuers
JWTVerifier verifier = JWT.require(algorithm)
    .withIssuer("https://app1.com", "https://app2.com")
    .build();

// Audience verification - must contain all specified values
JWTVerifier verifier = JWT.require(algorithm)
    .withAudience("api1", "api2")
    .build();

// Audience verification - must contain at least one specified value
JWTVerifier verifier = JWT.require(algorithm)
    .withAnyOfAudience("api1", "api2", "api3")
    .build();

// JWT ID verification
JWTVerifier verifier = JWT.require(algorithm)
    .withJWTId("unique-token-id")
    .build();

/**
 * Set a specific leeway window in which the Not Before, Issued At and Expires At Claims will still be valid.
 * @param leeway the window in seconds in which the Not Before, Issued At and Expires At Claims will still be valid
 * @return this same Verification instance
 */
Verification acceptLeeway(long leeway);

/**
 * Set a specific leeway window in which the Expires At Claim will still be valid.
 * @param leeway the window in seconds in which the Expires At Claim will still be valid
 * @return this same Verification instance
 */
Verification acceptExpiresAt(long leeway);

/**
 * Set a specific leeway window in which the Not Before Claim will still be valid.
 * @param leeway the window in seconds in which the Not Before Claim will still be valid
 * @return this same Verification instance
 */
Verification acceptNotBefore(long leeway);

/**
 * Set a specific leeway window in which the Issued At Claim will still be valid.
 * @param leeway the window in seconds in which the Issued At Claim will still be valid
 * @return this same Verification instance
 */
Verification acceptIssuedAt(long leeway);

/**
 * Skip the Issued At ("iat") date verification.
 * @return this same Verification instance
 */
Verification ignoreIssuedAt();

// General time leeway (applies to exp, nbf, iat)
JWTVerifier verifier = JWT.require(algorithm)
    .acceptLeeway(60) // 60 seconds leeway
    .build();

// Specific time claim leeway
JWTVerifier verifier = JWT.require(algorithm)
    .acceptExpiresAt(120)    // 2 minutes leeway for expiration
    .acceptNotBefore(30)     // 30 seconds leeway for not-before
    .acceptIssuedAt(60)      // 1 minute leeway for issued-at
    .build();

// Ignore issued-at validation entirely
JWTVerifier verifier = JWT.require(algorithm)
    .ignoreIssuedAt()
    .build();

/**
 * Require a custom Claim to be present in the token.
 * @param name the Claim's name
 * @return this same Verification instance
 */
Verification withClaimPresence(String name);

/**
 * Require a custom Claim to have a null value.
 * @param name the Claim's name
 * @return this same Verification instance
 */
Verification withNullClaim(String name);

/**
 * Require a specific Claim value of type Boolean.
 * @param name the Claim's name
 * @param value the expected Claim's value
 * @return this same Verification instance
 */
Verification withClaim(String name, Boolean value);

/**
 * Require a specific Claim value of type Integer.
 * @param name the Claim's name
 * @param value the expected Claim's value
 * @return this same Verification instance
 */
Verification withClaim(String name, Integer value);

/**
 * Require a specific Claim value of type Long.
 * @param name the Claim's name
 * @param value the expected Claim's value
 * @return this same Verification instance
 */
Verification withClaim(String name, Long value);

/**
 * Require a specific Claim value of type Double.
 * @param name the Claim's name
 * @param value the expected Claim's value
 * @return this same Verification instance
 */
Verification withClaim(String name, Double value);

/**
 * Require a specific Claim value of type String.
 * @param name the Claim's name
 * @param value the expected Claim's value
 * @return this same Verification instance
 */
Verification withClaim(String name, String value);

/**
 * Require a specific Claim value of type Date.
 * @param name the Claim's name
 * @param value the expected Claim's value
 * @return this same Verification instance
 */
Verification withClaim(String name, Date value);

/**
 * Require a specific Claim value of type Instant.
 * @param name the Claim's name
 * @param value the expected Claim's value
 * @return this same Verification instance
 */
Verification withClaim(String name, Instant value);

/**
 * Require a custom Claim to be verified with a BiPredicate function.
 * @param name the Claim's name
 * @param predicate the predicate to test the Claim value
 * @return this same Verification instance
 */
Verification withClaim(String name, BiPredicate<Claim, DecodedJWT> predicate);

import java.util.function.BiPredicate;
import com.auth0.jwt.interfaces.Claim;
import com.auth0.jwt.interfaces.DecodedJWT;

// Basic claim verification
JWTVerifier verifier = JWT.require(algorithm)
    .withClaimPresence("role")          // Must have "role" claim
    .withClaim("isActive", true)        // Must be active
    .withClaim("level", 5)              // Must be level 5
    .withClaim("department", "engineering")
    .withNullClaim("temp")              // "temp" claim must be null
    .build();

// Date-based claim verification
Date requiredDate = new Date(1234567890000L);
JWTVerifier verifier = JWT.require(algorithm)
    .withClaim("lastLogin", requiredDate)
    .build();

// Custom predicate verification
BiPredicate<Claim, DecodedJWT> agePredicate = (claim, jwt) -> {
    Integer age = claim.asInt();
    return age != null && age >= 18;
};

JWTVerifier verifier = JWT.require(algorithm)
    .withClaim("age", agePredicate)
    .build();

// Complex custom validation
BiPredicate<Claim, DecodedJWT> rolePredicate = (claim, jwt) -> {
    String role = claim.asString();
    String department = jwt.getClaim("department").asString();
    return "admin".equals(role) || "engineering".equals(department);
};

JWTVerifier verifier = JWT.require(algorithm)
    .withClaim("role", rolePredicate)
    .build();

/**
 * Require a specific Array Claim to contain at least the given String items.
 * @param name the Claim's name
 * @param items the expected Claim's items
 * @return this same Verification instance
 */
Verification withArrayClaim(String name, String... items);

/**
 * Require a specific Array Claim to contain at least the given Integer items.
 * @param name the Claim's name
 * @param items the expected Claim's items
 * @return this same Verification instance
 */
Verification withArrayClaim(String name, Integer... items);

/**
 * Require a specific Array Claim to contain at least the given Long items.
 * @param name the Claim's name
 * @param items the expected Claim's items
 * @return this same Verification instance
 */
Verification withArrayClaim(String name, Long... items);

// Array claim verification - must contain specified items
JWTVerifier verifier = JWT.require(algorithm)
    .withArrayClaim("roles", "admin", "user")        // Must contain both "admin" and "user"
    .withArrayClaim("permissions", "read", "write")   // Must contain both permissions
    .withArrayClaim("scores", 100, 85)               // Must contain both scores
    .build();

/**
 * Creates a JWTVerifier for the given Algorithm and configured verification options.
 * @return a JWTVerifier instance
 */
JWTVerifier build();

/**
 * Performs the verification against the given Token, using any previous configured options.
 * @param token A String containing a JWT token
 * @return a verified and decoded JWT
 * @throws JWTVerificationException if any of the verification steps fail
 */
DecodedJWT verify(String token) throws JWTVerificationException;

/**
 * Performs the verification against the given decoded JWT, using any previous configured options.
 * @param jwt A decoded JWT
 * @return a verified and decoded JWT
 * @throws JWTVerificationException if any of the verification steps fail
 */
DecodedJWT verify(DecodedJWT jwt) throws JWTVerificationException;

import com.auth0.jwt.exceptions.JWTVerificationException;

try {
    // Verify token string
    DecodedJWT jwt = verifier.verify(tokenString);
    
    // Access verified claims
    String subject = jwt.getSubject();
    String issuer = jwt.getIssuer();
    Date expiration = jwt.getExpiresAt();
    
    System.out.println("Token verified successfully for user: " + subject);
    
} catch (JWTVerificationException exception) {
    // Invalid signature/claims
    System.err.println("Token verification failed: " + exception.getMessage());
}

// Verify already decoded JWT
try {
    DecodedJWT decodedToken = JWT.decode(tokenString);
    DecodedJWT verifiedToken = verifier.verify(decodedToken);
    
    // Use verified token
    String role = verifiedToken.getClaim("role").asString();
    
} catch (JWTVerificationException exception) {
    System.err.println("Verification failed: " + exception.getMessage());
}

/**
 * Verification builder interface for configuring JWT verification rules.
 */
public interface Verification {
    // All verification configuration methods documented above
}

/**
 * JWT verifier interface for performing token verification.
 */
public interface JWTVerifier {
    /**
     * Performs verification against a JWT token string
     * @param token JWT token string to verify
     * @return verified and decoded JWT
     * @throws JWTVerificationException if verification fails
     */
    DecodedJWT verify(String token) throws JWTVerificationException;
    
    /**
     * Performs verification against a decoded JWT
     * @param jwt decoded JWT to verify
     * @return verified and decoded JWT
     * @throws JWTVerificationException if verification fails
     */
    DecodedJWT verify(DecodedJWT jwt) throws JWTVerificationException;
}