0
# Java JWT
1

2
Java JWT is a comprehensive implementation of JSON Web Token (JWT) as specified in RFC 7519, designed specifically for server-side JVM applications. It provides extensive JWT creation, signing, and verification capabilities with support for multiple cryptographic algorithms including HMAC, RSA, and ECDSA signing methods.
3

4
## Package Information
5

6
- **Package Name**: com.auth0:java-jwt
7
- **Package Type**: maven
8
- **Language**: Java
9
- **Installation**: Add dependency to Maven pom.xml or Gradle build.gradle
10

11
Maven:
12
```xml
13
<dependency>
14
  <groupId>com.auth0</groupId>
15
  <artifactId>java-jwt</artifactId>
16
  <version>4.5.0</version>
17
</dependency>
18
```
19

20
Gradle:
21
```gradle
22
implementation 'com.auth0:java-jwt:4.5.0'
23
```
24

25
## Core Imports
26

27
```java
28
import com.auth0.jwt.JWT;
29
import com.auth0.jwt.algorithms.Algorithm;
30
import com.auth0.jwt.interfaces.DecodedJWT;
31
import com.auth0.jwt.interfaces.JWTVerifier;
32
```
33

34
## Basic Usage
35

36
```java
37
import com.auth0.jwt.JWT;
38
import com.auth0.jwt.algorithms.Algorithm;
39
import com.auth0.jwt.interfaces.DecodedJWT;
40
import com.auth0.jwt.interfaces.JWTVerifier;
41

42
// Create a JWT token
43
Algorithm algorithm = Algorithm.HMAC256("secret");
44
String token = JWT.create()
45
    .withIssuer("auth0")
46
    .withSubject("user123")
47
    .withExpiresAt(new Date(System.currentTimeMillis() + 3600000))
48
    .sign(algorithm);
49

50
// Verify a JWT token
51
JWTVerifier verifier = JWT.require(algorithm)
52
    .withIssuer("auth0")
53
    .acceptLeeway(60) // 60 seconds leeway for time-based claims
54
    .build();
55
DecodedJWT jwt = verifier.verify(token);
56

57
// Decode without verification (use with caution)
58
DecodedJWT decoded = JWT.decode(token);
59
String subject = decoded.getSubject();
60
```
61

62
## Architecture
63

64
Java JWT is built around several key components:
65

66
- **JWT Main Class**: Entry point providing static methods for token creation, verification, and decoding, plus instance methods for high-throughput decoding scenarios
67
- **Algorithm Factory**: Creates algorithm instances for different cryptographic methods (HMAC, RSA, ECDSA)
68
- **Builder Pattern**: Fluent interfaces for JWT creation (`JWTCreator.Builder`) and verification setup (`Verification`)
69
- **Key Providers**: Interfaces for dynamic key resolution supporting key rotation and multi-tenant scenarios
70
- **Claim System**: Type-safe access to JWT claims with automatic conversion and validation
71
- **Exception Hierarchy**: Comprehensive error handling for creation, verification, and decoding failures
72

73
## Capabilities
74

75
### JWT Creation
76

77
Core functionality for creating and signing JWT tokens with comprehensive claim support and multiple signing algorithms.
78

79
```java { .api }
80
public static JWTCreator.Builder create();
81

82
public interface JWTCreator.Builder {
83
    Builder withIssuer(String issuer);
84
    Builder withSubject(String subject);
85
    Builder withAudience(String... audience);
86
    Builder withExpiresAt(Date expiresAt);
87
    Builder withClaim(String name, String value);
88
    String sign(Algorithm algorithm);
89
}
90
```
91

92
[JWT Creation](./jwt-creation.md)
93

94
### JWT Verification
95

96
Comprehensive verification system with configurable claim validation, time leeway, and custom validation predicates.
97

98
```java { .api }
99
public static Verification require(Algorithm algorithm);
100

101
public interface Verification {
102
    Verification withIssuer(String... issuer);
103
    Verification withSubject(String subject);
104
    Verification acceptLeeway(long leeway);
105
    Verification withClaim(String name, String value);
106
    JWTVerifier build();
107
}
108

109
public interface JWTVerifier {
110
    DecodedJWT verify(String token);
111
}
112
```
113

114
[JWT Verification](./jwt-verification.md)
115

116
### JWT Decoding
117

118
Token decoding functionality for accessing JWT header, payload, and claims without signature verification.
119

120
```java { .api }
121
public static DecodedJWT decode(String token);
122

123
public interface DecodedJWT extends Payload, Header {
124
    String getToken();
125
    String getHeader();
126
    String getPayload();
127
    String getSignature();
128
}
129
```
130

131
[JWT Decoding](./jwt-decoding.md)
132

133
### Cryptographic Algorithms
134

135
Factory methods for creating algorithm instances supporting HMAC, RSA, and ECDSA signing methods with key provider support.
136

137
```java { .api }
138
// HMAC Algorithms
139
public static Algorithm HMAC256(String secret);
140
public static Algorithm HMAC384(byte[] secret);
141
public static Algorithm HMAC512(String secret);
142

143
// RSA Algorithms
144
public static Algorithm RSA256(RSAPublicKey publicKey, RSAPrivateKey privateKey);
145
public static Algorithm RSA384(RSAKeyProvider keyProvider);
146
public static Algorithm RSA512(RSAKey key);
147

148
// ECDSA Algorithms
149
public static Algorithm ECDSA256(ECPublicKey publicKey, ECPrivateKey privateKey);
150
public static Algorithm ECDSA384(ECDSAKeyProvider keyProvider);
151
public static Algorithm ECDSA512(ECKey key);
152
```
153

154
[Cryptographic Algorithms](./algorithms.md)
155

156
### Claim Access
157

158
Type-safe claim access system with automatic type conversion and comprehensive getter methods for all standard JWT claims.
159

160
```java { .api }
161
public interface Payload {
162
    String getIssuer();
163
    String getSubject();
164
    List<String> getAudience();
165
    Date getExpiresAt();
166
    Instant getExpiresAtAsInstant();
167
    Claim getClaim(String name);
168
    Map<String, Claim> getClaims();
169
}
170

171
public interface Claim {
172
    String asString();
173
    Integer asInt();
174
    Boolean asBoolean();
175
    Date asDate();
176
    <T> List<T> asList(Class<T> clazz);
177
    <T> T[] asArray(Class<T> clazz);
178
}
179
```
180

181
[Claim Access](./claims.md)
182

183
### Key Providers
184

185
Dynamic key resolution interfaces supporting key rotation, multi-tenant scenarios, and advanced key management patterns.
186

187
```java { .api }
188
public interface RSAKeyProvider extends KeyProvider<RSAPublicKey, RSAPrivateKey> {
189
    RSAPublicKey getPublicKeyById(String keyId);
190
    RSAPrivateKey getPrivateKey();
191
    String getPrivateKeyId();
192
}
193

194
public interface ECDSAKeyProvider extends KeyProvider<ECPublicKey, ECPrivateKey> {
195
    ECPublicKey getPublicKeyById(String keyId);
196
    ECPrivateKey getPrivateKey();
197
    String getPrivateKeyId();
198
}
199
```
200

201
[Key Providers](./key-providers.md)
202

203
## Types
204

205
```java { .api }
206
// Standard JWT claim name constants
207
public class RegisteredClaims {
208
    public static final String ISSUER = "iss";
209
    public static final String SUBJECT = "sub";
210
    public static final String AUDIENCE = "aud";
211
    public static final String EXPIRES_AT = "exp";
212
    public static final String NOT_BEFORE = "nbf";
213
    public static final String ISSUED_AT = "iat";
214
    public static final String JWT_ID = "jti";
215
}
216

217
// JWT header parameter constants
218
public class HeaderParams {
219
    public static final String ALGORITHM = "alg";
220
    public static final String CONTENT_TYPE = "cty";
221
    public static final String TYPE = "typ";
222
    public static final String KEY_ID = "kid";
223
}
224
```