0
# JWT Decoding
1
2
JWT decoding functionality for accessing token header, payload, and claims without signature verification. Use only when token trust has been established through other means.
3
4
## Capabilities
5
6
### Static Token Decoding
7
8
Decode a JWT token without verifying its signature to access header and payload information.
9
10
```java { .api }
11
/**
12
* Decode a given Json Web Token.
13
* Note that this method doesn't verify the token's signature!
14
* Use it only if you trust the token or if you have already verified it.
15
* @param token with jwt format as string
16
* @return a decoded JWT
17
* @throws JWTDecodeException if any part of the token contained an invalid jwt or JSON format of each of the jwt parts
18
*/
19
public static DecodedJWT decode(String token) throws JWTDecodeException;
20
```
21
22
**Usage Example:**
23
24
```java
25
import com.auth0.jwt.JWT;
26
import com.auth0.jwt.interfaces.DecodedJWT;
27
import com.auth0.jwt.exceptions.JWTDecodeException;
28
29
try {
30
String token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c";
31
32
DecodedJWT jwt = JWT.decode(token);
33
34
// Access header information
35
String algorithm = jwt.getAlgorithm();
36
String keyId = jwt.getKeyId();
37
38
// Access payload claims
39
String subject = jwt.getSubject();
40
String issuer = jwt.getIssuer();
41
Date expiration = jwt.getExpiresAt();
42
43
System.out.println("Algorithm: " + algorithm);
44
System.out.println("Subject: " + subject);
45
46
} catch (JWTDecodeException exception) {
47
System.err.println("Invalid JWT format: " + exception.getMessage());
48
}
49
```
50
51
### Instance Token Decoding
52
53
Decode JWT tokens using a reusable JWT instance, optimized for high-throughput scenarios where many tokens need to be decoded.
54
55
```java { .api }
56
/**
57
* Decode a given Json Web Token using a JWT instance.
58
* Note that this method doesn't verify the token's signature!
59
* Use it only if you trust the token or if you have already verified it.
60
* @param token with jwt format as string
61
* @return a decoded JWT
62
* @throws JWTDecodeException if any part of the token contained an invalid jwt or JSON format of each of the jwt parts
63
*/
64
public DecodedJWT decodeJwt(String token) throws JWTDecodeException;
65
```
66
67
**Usage Example:**
68
69
```java
70
import com.auth0.jwt.JWT;
71
import com.auth0.jwt.interfaces.DecodedJWT;
72
import com.auth0.jwt.exceptions.JWTDecodeException;
73
74
// Create reusable JWT instance for high-throughput decoding
75
JWT jwtDecoder = new JWT();
76
77
// Decode multiple tokens efficiently
78
for (String token : tokenList) {
79
try {
80
DecodedJWT jwt = jwtDecoder.decodeJwt(token);
81
String subject = jwt.getSubject();
82
processToken(subject);
83
} catch (JWTDecodeException exception) {
84
System.err.println("Invalid JWT: " + exception.getMessage());
85
}
86
}
87
88
**Usage Example:**
89
90
```java
91
import com.auth0.jwt.JWT;
92
import com.auth0.jwt.interfaces.DecodedJWT;
93
94
// Create reusable decoder instance
95
JWT jwtDecoder = new JWT();
96
97
// Decode multiple tokens efficiently
98
String[] tokens = {
99
"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
100
"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
101
"eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9..."
102
};
103
104
for (String token : tokens) {
105
try {
106
DecodedJWT jwt = jwtDecoder.decodeJwt(token);
107
System.out.println("Token subject: " + jwt.getSubject());
108
} catch (JWTDecodeException e) {
109
System.err.println("Failed to decode token: " + e.getMessage());
110
}
111
}
112
```
113
114
### Token Component Access
115
116
Access the raw JWT components (header, payload, signature) as base64-encoded strings.
117
118
```java { .api }
119
/**
120
* Getter for the Token used to create this JWT instance.
121
* @return the Token used to create this JWT instance
122
*/
123
String getToken();
124
125
/**
126
* Getter for the Header contained in this JWT as a Base64 encoded String.
127
* @return the Header contained in this JWT as a Base64 encoded String
128
*/
129
String getHeader();
130
131
/**
132
* Getter for the Payload contained in this JWT as a Base64 encoded String.
133
* @return the Payload contained in this JWT as a Base64 encoded String
134
*/
135
String getPayload();
136
137
/**
138
* Getter for the Signature contained in this JWT as a Base64 encoded String.
139
* @return the Signature contained in this JWT as a Base64 encoded String
140
*/
141
String getSignature();
142
```
143
144
**Usage Example:**
145
146
```java
147
DecodedJWT jwt = JWT.decode(token);
148
149
// Access raw components
150
String originalToken = jwt.getToken();
151
String headerB64 = jwt.getHeader();
152
String payloadB64 = jwt.getPayload();
153
String signatureB64 = jwt.getSignature();
154
155
System.out.println("Original token: " + originalToken);
156
System.out.println("Header (Base64): " + headerB64);
157
System.out.println("Payload (Base64): " + payloadB64);
158
System.out.println("Signature (Base64): " + signatureB64);
159
160
// Reconstruct token manually if needed
161
String reconstructed = headerB64 + "." + payloadB64 + "." + signatureB64;
162
assert originalToken.equals(reconstructed);
163
```
164
165
### Header Claim Access
166
167
Access JWT header claims including standard and custom header parameters.
168
169
```java { .api }
170
/**
171
* Getter for the Algorithm "alg" claim contained in the Header.
172
* @return the Algorithm defined or null if it's not defined in the Header
173
*/
174
String getAlgorithm();
175
176
/**
177
* Getter for the Type "typ" claim contained in the Header.
178
* @return the Type defined or null if it's not defined in the Header
179
*/
180
String getType();
181
182
/**
183
* Getter for the Content Type "cty" claim contained in the Header.
184
* @return the Content Type defined or null if it's not defined in the Header
185
*/
186
String getContentType();
187
188
/**
189
* Getter for the Key Id "kid" claim contained in the Header.
190
* @return the Key Id defined or null if it's not defined in the Header
191
*/
192
String getKeyId();
193
194
/**
195
* Get a custom Claim given its name from the Header.
196
* @param name the name of the Claim to retrieve
197
* @return a valid Claim instance if the Claim was found or a NullClaim if not
198
*/
199
Claim getHeaderClaim(String name);
200
```
201
202
**Usage Example:**
203
204
```java
205
DecodedJWT jwt = JWT.decode(token);
206
207
// Standard header claims
208
String algorithm = jwt.getAlgorithm(); // e.g., "HS256", "RS256"
209
String type = jwt.getType(); // typically "JWT"
210
String contentType = jwt.getContentType(); // e.g., "application/json"
211
String keyId = jwt.getKeyId(); // key identifier for verification
212
213
System.out.println("Algorithm: " + algorithm);
214
System.out.println("Type: " + type);
215
216
// Custom header claims
217
Claim customClaim = jwt.getHeaderClaim("custom");
218
if (!customClaim.isMissing()) {
219
String customValue = customClaim.asString();
220
System.out.println("Custom header claim: " + customValue);
221
}
222
```
223
224
### Payload Claim Access
225
226
Access JWT payload claims including standard registered claims and custom claims.
227
228
```java { .api }
229
/**
230
* Getter for the Issuer "iss" claim contained in the Payload.
231
* @return the Issuer value or null if it's not defined in the Payload
232
*/
233
String getIssuer();
234
235
/**
236
* Getter for the Subject "sub" claim contained in the Payload.
237
* @return the Subject value or null if it's not defined in the Payload
238
*/
239
String getSubject();
240
241
/**
242
* Getter for the Audience "aud" claim contained in the Payload.
243
* @return the Audience value or an empty list if it's not defined in the Payload
244
*/
245
List<String> getAudience();
246
247
/**
248
* Getter for the Expires At "exp" claim contained in the Payload.
249
* @return the Expires At value or null if it's not defined in the Payload
250
*/
251
Date getExpiresAt();
252
253
/**
254
* Getter for the Expires At "exp" claim contained in the Payload as an Instant.
255
* @return the Expires At value or null if it's not defined in the Payload
256
*/
257
Instant getExpiresAtAsInstant();
258
259
/**
260
* Getter for the Not Before "nbf" claim contained in the Payload.
261
* @return the Not Before value or null if it's not defined in the Payload
262
*/
263
Date getNotBefore();
264
265
/**
266
* Getter for the Not Before "nbf" claim contained in the Payload as an Instant.
267
* @return the Not Before value or null if it's not defined in the Payload
268
*/
269
Instant getNotBeforeAsInstant();
270
271
/**
272
* Getter for the Issued At "iat" claim contained in the Payload.
273
* @return the Issued At value or null if it's not defined in the Payload
274
*/
275
Date getIssuedAt();
276
277
/**
278
* Getter for the Issued At "iat" claim contained in the Payload as an Instant.
279
* @return the Issued At value or null if it's not defined in the Payload
280
*/
281
Instant getIssuedAtAsInstant();
282
283
/**
284
* Getter for the JWT ID "jti" claim contained in the Payload.
285
* @return the JWT ID value or null if it's not defined in the Payload
286
*/
287
String getId();
288
289
/**
290
* Get a custom Claim given its name from the Payload.
291
* @param name the name of the Claim to retrieve
292
* @return a valid Claim instance if the Claim was found or a NullClaim if not
293
*/
294
Claim getClaim(String name);
295
296
/**
297
* Get all Claims contained in the Payload.
298
* @return a Map containing all the custom Claims defined in the token
299
*/
300
Map<String, Claim> getClaims();
301
```
302
303
**Usage Example:**
304
305
```java
306
DecodedJWT jwt = JWT.decode(token);
307
308
// Standard registered claims
309
String issuer = jwt.getIssuer(); // "iss" claim
310
String subject = jwt.getSubject(); // "sub" claim
311
List<String> audience = jwt.getAudience(); // "aud" claim
312
Date expiresAt = jwt.getExpiresAt(); // "exp" claim
313
Date notBefore = jwt.getNotBefore(); // "nbf" claim
314
Date issuedAt = jwt.getIssuedAt(); // "iat" claim
315
String jwtId = jwt.getId(); // "jti" claim
316
317
System.out.println("Issuer: " + issuer);
318
System.out.println("Subject: " + subject);
319
System.out.println("Expires at: " + expiresAt);
320
321
// Use Instant for modern date handling
322
Instant expiresAtInstant = jwt.getExpiresAtAsInstant();
323
Instant notBeforeInstant = jwt.getNotBeforeAsInstant();
324
Instant issuedAtInstant = jwt.getIssuedAtAsInstant();
325
326
// Custom claims
327
Claim roleClaim = jwt.getClaim("role");
328
if (!roleClaim.isMissing()) {
329
String role = roleClaim.asString();
330
System.out.println("Role: " + role);
331
}
332
333
// All claims
334
Map<String, Claim> allClaims = jwt.getClaims();
335
for (Map.Entry<String, Claim> entry : allClaims.entrySet()) {
336
String claimName = entry.getKey();
337
Claim claimValue = entry.getValue();
338
if (!claimValue.isMissing()) {
339
System.out.println(claimName + ": " + claimValue.asString());
340
}
341
}
342
```
343
344
## Security Considerations
345
346
**Important Security Note:** The decode methods do NOT verify the token's signature. Use these methods only in the following scenarios:
347
348
1. **Already Verified Tokens**: When the token has been previously verified through other means
349
2. **Trusted Sources**: When you completely trust the source of the token
350
3. **Information Extraction**: For extracting claims from tokens that will be verified separately
351
4. **Development/Debugging**: For inspecting token contents during development
352
353
For production security-critical applications, always use the verification methods provided by `JWTVerifier` instead.
354
355
**Usage Example with Security Warning:**
356
357
```java
358
// ⚠️ SECURITY WARNING: This does NOT verify the signature!
359
DecodedJWT jwt = JWT.decode(untrustedToken);
360
361
// ✅ SECURE: This verifies the signature
362
JWTVerifier verifier = JWT.require(algorithm).build();
363
DecodedJWT verifiedJwt = verifier.verify(untrustedToken);
364
```
365
366
## Types
367
368
```java { .api }
369
/**
370
* JWT decoder interface providing access to token components and claims
371
*/
372
public interface DecodedJWT extends Payload, Header {
373
String getToken();
374
String getHeader();
375
String getPayload();
376
String getSignature();
377
}
378
379
/**
380
* JWT header interface providing access to header claims
381
*/
382
public interface Header {
383
String getAlgorithm();
384
String getType();
385
String getContentType();
386
String getKeyId();
387
Claim getHeaderClaim(String name);
388
}
389
390
/**
391
* JWT payload interface providing access to payload claims
392
*/
393
public interface Payload {
394
String getIssuer();
395
String getSubject();
396
List<String> getAudience();
397
Date getExpiresAt();
398
Instant getExpiresAtAsInstant();
399
Date getNotBefore();
400
Instant getNotBeforeAsInstant();
401
Date getIssuedAt();
402
Instant getIssuedAtAsInstant();
403
String getId();
404
Claim getClaim(String name);
405
Map<String, Claim> getClaims();
406
}
407
```