0
# JWT Verification
1

2
Comprehensive JWT verification system providing configurable claim validation, time-based verification, and custom validation predicates for secure token validation.
3

4
## Capabilities
5

6
### Verification Builder Creation
7

8
Creates a verification builder with the specified algorithm for token validation.
9

10
```java { .api }
11
/**
12
 * Returns a Verification builder with the algorithm to be used to validate token signature.
13
 * @param algorithm that will be used to verify the token's signature
14
 * @return Verification builder
15
 * @throws IllegalArgumentException if the provided algorithm is null
16
 */
17
public static Verification require(Algorithm algorithm) throws IllegalArgumentException;
18
```
19

20
**Usage Example:**
21

22
```java
23
import com.auth0.jwt.JWT;
24
import com.auth0.jwt.algorithms.Algorithm;
25
import com.auth0.jwt.interfaces.JWTVerifier;
26

27
Algorithm algorithm = Algorithm.HMAC256("secret");
28
JWTVerifier verifier = JWT.require(algorithm)
29
    .withIssuer("auth0")
30
    .build();
31
```
32

33
### Standard Claim Verification
34

35
Configure verification for standard JWT claims with exact matching or multiple allowed values.
36

37
```java { .api }
38
/**
39
 * Require a specific Issuer ("iss") claim.
40
 * @param issuer the required Issuer value. If multiple values are given, the claim must match one of them
41
 * @return this same Verification instance
42
 */
43
Verification withIssuer(String... issuer);
44

45
/**
46
 * Require a specific Subject ("sub") claim.
47
 * @param subject the required Subject value
48
 * @return this same Verification instance
49
 */
50
Verification withSubject(String subject);
51

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

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

66
/**
67
 * Require a specific JWT Id ("jti") claim.
68
 * @param jwtId the required JWT Id value
69
 * @return this same Verification instance
70
 */
71
Verification withJWTId(String jwtId);
72
```
73

74
**Usage Examples:**
75

76
```java
77
// Single issuer verification
78
JWTVerifier verifier = JWT.require(algorithm)
79
    .withIssuer("https://my-app.com")
80
    .withSubject("user123")
81
    .build();
82

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

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

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

98
// JWT ID verification
99
JWTVerifier verifier = JWT.require(algorithm)
100
    .withJWTId("unique-token-id")
101
    .build();
102
```
103

104
### Time-based Verification
105

106
Configure time leeway and validation for time-based claims (exp, nbf, iat).
107

108
```java { .api }
109
/**
110
 * Set a specific leeway window in which the Not Before, Issued At and Expires At Claims will still be valid.
111
 * @param leeway the window in seconds in which the Not Before, Issued At and Expires At Claims will still be valid
112
 * @return this same Verification instance
113
 */
114
Verification acceptLeeway(long leeway);
115

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

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

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

137
/**
138
 * Skip the Issued At ("iat") date verification.
139
 * @return this same Verification instance
140
 */
141
Verification ignoreIssuedAt();
142
```
143

144
**Usage Examples:**
145

146
```java
147
// General time leeway (applies to exp, nbf, iat)
148
JWTVerifier verifier = JWT.require(algorithm)
149
    .acceptLeeway(60) // 60 seconds leeway
150
    .build();
151

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

159
// Ignore issued-at validation entirely
160
JWTVerifier verifier = JWT.require(algorithm)
161
    .ignoreIssuedAt()
162
    .build();
163
```
164

165
### Custom Claim Verification
166

167
Configure verification for custom claims with various validation methods.
168

169
```java { .api }
170
/**
171
 * Require a custom Claim to be present in the token.
172
 * @param name the Claim's name
173
 * @return this same Verification instance
174
 */
175
Verification withClaimPresence(String name);
176

177
/**
178
 * Require a custom Claim to have a null value.
179
 * @param name the Claim's name
180
 * @return this same Verification instance
181
 */
182
Verification withNullClaim(String name);
183

184
/**
185
 * Require a specific Claim value of type Boolean.
186
 * @param name the Claim's name
187
 * @param value the expected Claim's value
188
 * @return this same Verification instance
189
 */
190
Verification withClaim(String name, Boolean value);
191

192
/**
193
 * Require a specific Claim value of type Integer.
194
 * @param name the Claim's name
195
 * @param value the expected Claim's value
196
 * @return this same Verification instance
197
 */
198
Verification withClaim(String name, Integer value);
199

200
/**
201
 * Require a specific Claim value of type Long.
202
 * @param name the Claim's name
203
 * @param value the expected Claim's value
204
 * @return this same Verification instance
205
 */
206
Verification withClaim(String name, Long value);
207

208
/**
209
 * Require a specific Claim value of type Double.
210
 * @param name the Claim's name
211
 * @param value the expected Claim's value
212
 * @return this same Verification instance
213
 */
214
Verification withClaim(String name, Double value);
215

216
/**
217
 * Require a specific Claim value of type String.
218
 * @param name the Claim's name
219
 * @param value the expected Claim's value
220
 * @return this same Verification instance
221
 */
222
Verification withClaim(String name, String value);
223

224
/**
225
 * Require a specific Claim value of type Date.
226
 * @param name the Claim's name
227
 * @param value the expected Claim's value
228
 * @return this same Verification instance
229
 */
230
Verification withClaim(String name, Date value);
231

232
/**
233
 * Require a specific Claim value of type Instant.
234
 * @param name the Claim's name
235
 * @param value the expected Claim's value
236
 * @return this same Verification instance
237
 */
238
Verification withClaim(String name, Instant value);
239

240
/**
241
 * Require a custom Claim to be verified with a BiPredicate function.
242
 * @param name the Claim's name
243
 * @param predicate the predicate to test the Claim value
244
 * @return this same Verification instance
245
 */
246
Verification withClaim(String name, BiPredicate<Claim, DecodedJWT> predicate);
247
```
248

249
**Usage Examples:**
250

251
```java
252
import java.util.function.BiPredicate;
253
import com.auth0.jwt.interfaces.Claim;
254
import com.auth0.jwt.interfaces.DecodedJWT;
255

256
// Basic claim verification
257
JWTVerifier verifier = JWT.require(algorithm)
258
    .withClaimPresence("role")          // Must have "role" claim
259
    .withClaim("isActive", true)        // Must be active
260
    .withClaim("level", 5)              // Must be level 5
261
    .withClaim("department", "engineering")
262
    .withNullClaim("temp")              // "temp" claim must be null
263
    .build();
264

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

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

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

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

288
JWTVerifier verifier = JWT.require(algorithm)
289
    .withClaim("role", rolePredicate)
290
    .build();
291
```
292

293
### Array Claim Verification
294

295
Configure verification for array-typed custom claims.
296

297
```java { .api }
298
/**
299
 * Require a specific Array Claim to contain at least the given String items.
300
 * @param name the Claim's name
301
 * @param items the expected Claim's items
302
 * @return this same Verification instance
303
 */
304
Verification withArrayClaim(String name, String... items);
305

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

314
/**
315
 * Require a specific Array Claim to contain at least the given Long items.
316
 * @param name the Claim's name
317
 * @param items the expected Claim's items
318
 * @return this same Verification instance
319
 */
320
Verification withArrayClaim(String name, Long... items);
321
```
322

323
**Usage Examples:**
324

325
```java
326
// Array claim verification - must contain specified items
327
JWTVerifier verifier = JWT.require(algorithm)
328
    .withArrayClaim("roles", "admin", "user")        // Must contain both "admin" and "user"
329
    .withArrayClaim("permissions", "read", "write")   // Must contain both permissions
330
    .withArrayClaim("scores", 100, 85)               // Must contain both scores
331
    .build();
332
```
333

334
### Verifier Construction
335

336
Build the configured verifier instance for token validation.
337

338
```java { .api }
339
/**
340
 * Creates a JWTVerifier for the given Algorithm and configured verification options.
341
 * @return a JWTVerifier instance
342
 */
343
JWTVerifier build();
344
```
345

346
### Token Verification
347

348
Verify JWT tokens using the configured verifier.
349

350
```java { .api }
351
/**
352
 * Performs the verification against the given Token, using any previous configured options.
353
 * @param token A String containing a JWT token
354
 * @return a verified and decoded JWT
355
 * @throws JWTVerificationException if any of the verification steps fail
356
 */
357
DecodedJWT verify(String token) throws JWTVerificationException;
358

359
/**
360
 * Performs the verification against the given decoded JWT, using any previous configured options.
361
 * @param jwt A decoded JWT
362
 * @return a verified and decoded JWT
363
 * @throws JWTVerificationException if any of the verification steps fail
364
 */
365
DecodedJWT verify(DecodedJWT jwt) throws JWTVerificationException;
366
```
367

368
**Usage Examples:**
369

370
```java
371
import com.auth0.jwt.exceptions.JWTVerificationException;
372

373
try {
374
    // Verify token string
375
    DecodedJWT jwt = verifier.verify(tokenString);
376
    
377
    // Access verified claims
378
    String subject = jwt.getSubject();
379
    String issuer = jwt.getIssuer();
380
    Date expiration = jwt.getExpiresAt();
381
    
382
    System.out.println("Token verified successfully for user: " + subject);
383
    
384
} catch (JWTVerificationException exception) {
385
    // Invalid signature/claims
386
    System.err.println("Token verification failed: " + exception.getMessage());
387
}
388

389
// Verify already decoded JWT
390
try {
391
    DecodedJWT decodedToken = JWT.decode(tokenString);
392
    DecodedJWT verifiedToken = verifier.verify(decodedToken);
393
    
394
    // Use verified token
395
    String role = verifiedToken.getClaim("role").asString();
396
    
397
} catch (JWTVerificationException exception) {
398
    System.err.println("Verification failed: " + exception.getMessage());
399
}
400
```
401

402
## Types
403

404
```java { .api }
405
/**
406
 * Verification builder interface for configuring JWT verification rules.
407
 */
408
public interface Verification {
409
    // All verification configuration methods documented above
410
}
411

412
/**
413
 * JWT verifier interface for performing token verification.
414
 */
415
public interface JWTVerifier {
416
    /**
417
     * Performs verification against a JWT token string
418
     * @param token JWT token string to verify
419
     * @return verified and decoded JWT
420
     * @throws JWTVerificationException if verification fails
421
     */
422
    DecodedJWT verify(String token) throws JWTVerificationException;
423
    
424
    /**
425
     * Performs verification against a decoded JWT
426
     * @param jwt decoded JWT to verify
427
     * @return verified and decoded JWT
428
     * @throws JWTVerificationException if verification fails
429
     */
430
    DecodedJWT verify(DecodedJWT jwt) throws JWTVerificationException;
431
}
432
```