0
# Authentication
1

2
HTTP authentication support for Jersey Client including Basic authentication, Digest authentication, and Universal authentication modes with both preemptive and non-preemptive options. This functionality provides comprehensive authentication capabilities for securing HTTP requests.
3

4
## Capabilities
5

6
### HTTP Authentication Feature
7

8
Main authentication feature providing Basic, Digest, and Universal authentication modes with configuration options for preemptive authentication and credential management.
9

10
```java { .api }
11
public class HttpAuthenticationFeature implements Feature {
12
    // Property keys for authentication configuration
13
    public static final String HTTP_AUTHENTICATION_USERNAME = "jersey.config.client.http.auth.username";
14
    public static final String HTTP_AUTHENTICATION_PASSWORD = "jersey.config.client.http.auth.password";
15
    public static final String HTTP_AUTHENTICATION_BASIC_USERNAME = "jersey.config.client.http.auth.basic.username";
16
    public static final String HTTP_AUTHENTICATION_BASIC_PASSWORD = "jersey.config.client.http.auth.basic.password";
17
    public static final String HTTP_AUTHENTICATION_DIGEST_USERNAME = "jersey.config.client.http.auth.digest.username";
18
    public static final String HTTP_AUTHENTICATION_DIGEST_PASSWORD = "jersey.config.client.http.auth.digest.password";
19
    
20
    /**
21
     * Configure the authentication feature with the client
22
     * @param context feature context for configuration
23
     * @return true if feature was successfully configured
24
     */
25
    boolean configure(FeatureContext context);
26
}
27
```
28

29
### Basic Authentication
30

31
HTTP Basic authentication support with preemptive and non-preemptive modes for username/password authentication.
32

33
```java { .api }
34
public class HttpAuthenticationFeature implements Feature {
35
    /**
36
     * Create builder for Basic authentication configuration
37
     * @return Basic authentication builder
38
     */
39
    static BasicBuilder basicBuilder();
40
    
41
    /**
42
     * Create Basic authentication feature with credentials (preemptive by default)
43
     * @param username authentication username
44
     * @param password authentication password
45
     * @return configured Basic authentication feature
46
     */
47
    static HttpAuthenticationFeature basic(String username, String password);
48
    
49
    /**
50
     * Create Basic authentication feature with byte array password
51
     * @param username authentication username
52
     * @param password authentication password as byte array
53
     * @return configured Basic authentication feature
54
     */
55
    static HttpAuthenticationFeature basic(String username, byte[] password);
56
}
57

58
// Builder interface for Basic authentication
59
interface BasicBuilder extends Builder {
60
    /**
61
     * Configure non-preemptive Basic authentication (only send credentials after 401 challenge)
62
     * @return this builder instance
63
     */
64
    BasicBuilder nonPreemptive();
65
}
66

67
// Base builder interface
68
interface Builder {
69
    /**
70
     * Set authentication credentials
71
     * @param username authentication username
72
     * @param password authentication password
73
     * @return this builder instance
74
     */
75
    Builder credentials(String username, String password);
76
    
77
    /**
78
     * Set authentication credentials with byte array password
79
     * @param username authentication username
80
     * @param password authentication password as byte array
81
     * @return this builder instance
82
     */
83
    Builder credentials(String username, byte[] password);
84
    
85
    /**
86
     * Build the authentication feature
87
     * @return configured authentication feature
88
     */
89
    HttpAuthenticationFeature build();
90
}
91
```
92

93
**Usage Examples:**
94

95
```java
96
import org.glassfish.jersey.client.authentication.HttpAuthenticationFeature;
97

98
// Preemptive Basic authentication (default)
99
HttpAuthenticationFeature basicAuth = HttpAuthenticationFeature.basic("username", "password");
100
Client client = JerseyClientBuilder.createClient()
101
    .register(basicAuth);
102

103
// Non-preemptive Basic authentication (wait for 401 challenge)
104
HttpAuthenticationFeature nonPreemptiveBasic = HttpAuthenticationFeature.basicBuilder()
105
    .credentials("username", "password")
106
    .nonPreemptive()
107
    .build();
108

109
Client client2 = JerseyClientBuilder.createClient()
110
    .register(nonPreemptiveBasic);
111

112
// Using byte array for password (more secure)
113
byte[] passwordBytes = "password".getBytes(StandardCharsets.UTF_8);
114
HttpAuthenticationFeature secureBasic = HttpAuthenticationFeature.basic("username", passwordBytes);
115
```
116

117
### Digest Authentication
118

119
HTTP Digest authentication support for more secure authentication compared to Basic authentication, using challenge-response mechanism.
120

121
```java { .api }
122
public class HttpAuthenticationFeature implements Feature {
123
    /**
124
     * Create Digest authentication feature (no credentials, waits for challenge)
125
     * @return configured Digest authentication feature
126
     */
127
    static HttpAuthenticationFeature digest();
128
    
129
    /**
130
     * Create Digest authentication feature with credentials
131
     * @param username authentication username
132
     * @param password authentication password
133
     * @return configured Digest authentication feature
134
     */
135
    static HttpAuthenticationFeature digest(String username, String password);
136
    
137
    /**
138
     * Create Digest authentication feature with byte array password
139
     * @param username authentication username
140
     * @param password authentication password as byte array
141
     * @return configured Digest authentication feature
142
     */
143
    static HttpAuthenticationFeature digest(String username, byte[] password);
144
}
145
```
146

147
**Usage Examples:**
148

149
```java
150
// Digest authentication with credentials
151
HttpAuthenticationFeature digestAuth = HttpAuthenticationFeature.digest("username", "password");
152
Client client = JerseyClientBuilder.createClient()
153
    .register(digestAuth);
154

155
// Digest authentication waiting for challenge (credentials provided later)
156
HttpAuthenticationFeature digestChallenge = HttpAuthenticationFeature.digest();
157
Client client2 = JerseyClientBuilder.createClient()
158
    .register(digestChallenge);
159

160
// Using configuration properties for credentials
161
ClientConfig config = new ClientConfig();
162
config.property(HttpAuthenticationFeature.HTTP_AUTHENTICATION_DIGEST_USERNAME, "username");
163
config.property(HttpAuthenticationFeature.HTTP_AUTHENTICATION_DIGEST_PASSWORD, "password");
164
config.register(HttpAuthenticationFeature.digest());
165
Client client3 = JerseyClientBuilder.createClient(config);
166
```
167

168
### Universal Authentication
169

170
Universal authentication feature supporting both Basic and Digest authentication modes, automatically selecting the appropriate method based on server challenges.
171

172
```java { .api }
173
public class HttpAuthenticationFeature implements Feature {
174
    /**
175
     * Create builder for Universal authentication configuration
176
     * @return Universal authentication builder
177
     */
178
    static UniversalBuilder universalBuilder();
179
    
180
    /**
181
     * Create Universal authentication feature with credentials for both Basic and Digest
182
     * @param username authentication username
183
     * @param password authentication password
184
     * @return configured Universal authentication feature
185
     */
186
    static HttpAuthenticationFeature universal(String username, String password);
187
    
188
    /**
189
     * Create Universal authentication feature with byte array password
190
     * @param username authentication username
191
     * @param password authentication password as byte array
192
     * @return configured Universal authentication feature
193
     */
194
    static HttpAuthenticationFeature universal(String username, byte[] password);
195
}
196

197
// Builder interface for Universal authentication
198
interface UniversalBuilder extends Builder {
199
    /**
200
     * Set credentials specifically for Basic authentication
201
     * @param username Basic authentication username
202
     * @param password Basic authentication password
203
     * @return this builder instance
204
     */
205
    UniversalBuilder credentialsForBasic(String username, String password);
206
    
207
    /**
208
     * Set credentials specifically for Basic authentication with byte array password
209
     * @param username Basic authentication username
210
     * @param password Basic authentication password as byte array
211
     * @return this builder instance
212
     */
213
    UniversalBuilder credentialsForBasic(String username, byte[] password);
214
    
215
    /**
216
     * Set credentials specifically for Digest authentication
217
     * @param username Digest authentication username
218
     * @param password Digest authentication password
219
     * @return this builder instance
220
     */
221
    UniversalBuilder credentialsForDigest(String username, String password);
222
    
223
    /**
224
     * Set credentials specifically for Digest authentication with byte array password
225
     * @param username Digest authentication username
226
     * @param password Digest authentication password as byte array
227
     * @return this builder instance
228
     */
229
    UniversalBuilder credentialsForDigest(String username, byte[] password);
230
}
231
```
232

233
**Usage Examples:**
234

235
```java
236
// Universal authentication with same credentials for both Basic and Digest
237
HttpAuthenticationFeature universalAuth = HttpAuthenticationFeature.universal("username", "password");
238
Client client = JerseyClientBuilder.createClient()
239
    .register(universalAuth);
240

241
// Universal authentication with different credentials for Basic and Digest
242
HttpAuthenticationFeature customUniversal = HttpAuthenticationFeature.universalBuilder()
243
    .credentialsForBasic("basicUser", "basicPass")
244
    .credentialsForDigest("digestUser", "digestPass")
245
    .build();
246

247
Client client2 = JerseyClientBuilder.createClient()
248
    .register(customUniversal);
249

250
// Universal authentication with mixed credential types
251
HttpAuthenticationFeature mixedAuth = HttpAuthenticationFeature.universalBuilder()
252
    .credentialsForBasic("username", "password")
253
    .credentialsForDigest("username", "different-password".getBytes())
254
    .build();
255
```
256

257
### Authentication Exceptions
258

259
Exception classes for handling authentication-related errors during request processing and response handling.
260

261
```java { .api }
262
/**
263
 * Exception thrown during authentication request processing
264
 */
265
public class RequestAuthenticationException extends ProcessingException {
266
    /**
267
     * Create exception with cause
268
     * @param cause underlying cause of authentication failure
269
     */
270
    public RequestAuthenticationException(Throwable cause);
271
    
272
    /**
273
     * Create exception with message
274
     * @param message descriptive error message
275
     */
276
    public RequestAuthenticationException(String message);
277
    
278
    /**
279
     * Create exception with message and cause
280
     * @param message descriptive error message
281
     * @param cause underlying cause of authentication failure
282
     */
283
    public RequestAuthenticationException(String message, Throwable cause);
284
}
285

286
/**
287
 * Exception thrown during authentication response processing
288
 */
289
public class ResponseAuthenticationException extends ResponseProcessingException {
290
    /**
291
     * Create exception with response and cause
292
     * @param response HTTP response that caused the exception
293
     * @param cause underlying cause of authentication failure
294
     */
295
    public ResponseAuthenticationException(Response response, Throwable cause);
296
    
297
    /**
298
     * Create exception with response and message
299
     * @param response HTTP response that caused the exception
300
     * @param message descriptive error message
301
     */
302
    public ResponseAuthenticationException(Response response, String message);
303
    
304
    /**
305
     * Create exception with response, message, and cause
306
     * @param response HTTP response that caused the exception
307
     * @param message descriptive error message
308
     * @param cause underlying cause of authentication failure
309
     */
310
    public ResponseAuthenticationException(Response response, String message, Throwable cause);
311
}
312
```
313

314
**Usage Examples:**
315

316
```java
317
try {
318
    Response response = target.request().get();
319
} catch (RequestAuthenticationException e) {
320
    System.err.println("Authentication request failed: " + e.getMessage());
321
    // Handle request-side authentication error
322
} catch (ResponseAuthenticationException e) {
323
    System.err.println("Authentication response failed: " + e.getMessage());
324
    Response failedResponse = e.getResponse();
325
    int status = failedResponse.getStatus(); // Likely 401 or 403
326
    // Handle response-side authentication error
327
}
328
```
329

330
### Configuration Properties
331

332
Authentication configuration properties for setting credentials and authentication options through client configuration.
333

334
```java { .api }
335
// Example of using configuration properties for authentication
336
ClientConfig config = new ClientConfig();
337

338
// Global authentication credentials
339
config.property(HttpAuthenticationFeature.HTTP_AUTHENTICATION_USERNAME, "globalUser");
340
config.property(HttpAuthenticationFeature.HTTP_AUTHENTICATION_PASSWORD, "globalPass");
341

342
// Basic authentication specific credentials
343
config.property(HttpAuthenticationFeature.HTTP_AUTHENTICATION_BASIC_USERNAME, "basicUser");
344
config.property(HttpAuthenticationFeature.HTTP_AUTHENTICATION_BASIC_PASSWORD, "basicPass");
345

346
// Digest authentication specific credentials
347
config.property(HttpAuthenticationFeature.HTTP_AUTHENTICATION_DIGEST_USERNAME, "digestUser");
348
config.property(HttpAuthenticationFeature.HTTP_AUTHENTICATION_DIGEST_PASSWORD, "digestPass");
349

350
// Register authentication feature to use configured properties
351
config.register(HttpAuthenticationFeature.universal());
352

353
Client client = JerseyClientBuilder.createClient(config);
354
```
355

356
### Advanced Authentication Scenarios
357

358
Complex authentication scenarios combining multiple authentication types and configuration options.
359

360
**Usage Examples:**
361

362
```java
363
// Per-request authentication override
364
Client client = JerseyClientBuilder.createClient();
365

366
// Different authentication for different endpoints
367
HttpAuthenticationFeature adminAuth = HttpAuthenticationFeature.basic("admin", "admin-password");
368
HttpAuthenticationFeature userAuth = HttpAuthenticationFeature.digest("user", "user-password");
369

370
// Register different auth for different targets
371
WebTarget adminTarget = client.target("https://api.example.com/admin")
372
    .register(adminAuth);
373

374
WebTarget userTarget = client.target("https://api.example.com/user")
375
    .register(userAuth);
376

377
// Mix authentication with other features
378
Client fullClient = JerseyClientBuilder.createClient()
379
    .register(HttpAuthenticationFeature.basic("username", "password"))
380
    .register(new LoggingFeature())
381
    .property(ClientProperties.FOLLOW_REDIRECTS, true);
382

383
// Programmatic credential management
384
String username = getUsernameFromSecureStorage();
385
byte[] password = getPasswordFromSecureStorage();
386
HttpAuthenticationFeature secureAuth = HttpAuthenticationFeature.basic(username, password);
387

388
// Clear sensitive data
389
Arrays.fill(password, (byte) 0);
390

391
Client secureClient = JerseyClientBuilder.createClient()
392
    .register(secureAuth);
393
```