0
# Authentication
1

2
Comprehensive authentication support including basic, digest, OAuth 1.0/2.0, certificate-based, form authentication, and preemptive authentication schemes for REST API testing.
3

4
## Capabilities
5

6
### Basic Authentication
7

8
HTTP Basic authentication using username and password credentials.
9

10
```java { .api }
11
/**
12
 * Create HTTP basic authentication scheme
13
 * @param userName The username
14
 * @param password The password
15
 * @return Authentication scheme for basic auth
16
 */
17
static AuthenticationScheme basic(String userName, String password);
18

19
// Via authentication specification
20
interface AuthenticationSpecification {
21
    /**
22
     * Use HTTP basic authentication for this request
23
     * @param userName The username
24
     * @param password The password
25
     * @return Updated request specification
26
     */
27
    RequestSpecification basic(String userName, String password);
28
}
29
```
30

31
**Usage Examples:**
32

33
```java
34
// Global basic authentication
35
RestAssured.authentication = basic("admin", "password123");
36

37
// Per-request basic authentication
38
given()
39
    .auth().basic("user", "pass")
40
.when()
41
    .get("/protected")
42
.then()
43
    .statusCode(200);
44

45
// Preemptive basic authentication (sends credentials without challenge)
46
given()
47
    .auth().preemptive().basic("user", "pass")
48
.when()
49
    .get("/protected");
50
```
51

52
### Digest Authentication
53

54
HTTP Digest authentication for enhanced security over basic authentication.
55

56
```java { .api }
57
/**
58
 * Create HTTP digest authentication scheme
59
 * @param userName The username
60
 * @param password The password (should be properly encoded)
61
 * @return Authentication scheme for digest auth
62
 */
63
static AuthenticationScheme digest(String userName, String password);
64

65
interface AuthenticationSpecification {
66
    /**
67
     * Use HTTP digest authentication for this request
68
     * @param userName The username
69
     * @param password The password
70
     * @return Updated request specification
71
     */
72
    RequestSpecification digest(String userName, String password);
73
}
74
```
75

76
**Usage Examples:**
77

78
```java
79
// Digest authentication
80
given()
81
    .auth().digest("user", "password")
82
.when()
83
    .get("/protected")
84
.then()
85
    .statusCode(200);
86
```
87

88
### OAuth 1.0 Authentication
89

90
OAuth 1.0 authentication with consumer key, consumer secret, access token, and secret token.
91

92
```java { .api }
93
/**
94
 * Create OAuth 1.0 authentication scheme
95
 * @param consumerKey OAuth consumer key
96
 * @param consumerSecret OAuth consumer secret
97
 * @param accessToken OAuth access token
98
 * @param secretToken OAuth secret token
99
 * @return Authentication scheme for OAuth 1.0
100
 */
101
static AuthenticationScheme oauth(String consumerKey, String consumerSecret, String accessToken, String secretToken);
102

103
/**
104
 * Create OAuth 1.0 authentication scheme with custom signature
105
 * @param consumerKey OAuth consumer key
106
 * @param consumerSecret OAuth consumer secret
107
 * @param accessToken OAuth access token
108
 * @param secretToken OAuth secret token
109
 * @param signature OAuth signature method
110
 * @return Authentication scheme for OAuth 1.0
111
 */
112
static AuthenticationScheme oauth(String consumerKey, String consumerSecret, String accessToken, String secretToken, OAuthSignature signature);
113

114
interface AuthenticationSpecification {
115
    /**
116
     * Use OAuth 1.0 authentication for this request
117
     * @param consumerKey OAuth consumer key
118
     * @param consumerSecret OAuth consumer secret
119
     * @param accessToken OAuth access token
120
     * @param secretToken OAuth secret token
121
     * @return Updated request specification
122
     */
123
    RequestSpecification oauth(String consumerKey, String consumerSecret, String accessToken, String secretToken);
124
    
125
    /**
126
     * Use OAuth 1.0 authentication with custom signature for this request
127
     * @param consumerKey OAuth consumer key
128
     * @param consumerSecret OAuth consumer secret
129
     * @param accessToken OAuth access token
130
     * @param secretToken OAuth secret token
131
     * @param signature OAuth signature method
132
     * @return Updated request specification
133
     */
134
    RequestSpecification oauth(String consumerKey, String consumerSecret, String accessToken, String secretToken, OAuthSignature signature);
135
}
136
```
137

138
**Usage Examples:**
139

140
```java
141
// OAuth 1.0 authentication
142
given()
143
    .auth().oauth("consumerKey", "consumerSecret", "accessToken", "tokenSecret")
144
.when()
145
    .get("/api/protected")
146
.then()
147
    .statusCode(200);
148

149
// OAuth 1.0 with custom signature method
150
given()
151
    .auth().oauth("consumerKey", "consumerSecret", "accessToken", "tokenSecret", OAuthSignature.HMAC_SHA256)
152
.when()
153
    .post("/api/data");
154
```
155

156
### OAuth 2.0 Authentication
157

158
OAuth 2.0 authentication using Bearer tokens.
159

160
```java { .api }
161
/**
162
 * Create OAuth 2.0 authentication scheme
163
 * @param accessToken OAuth 2.0 access token
164
 * @return Authentication scheme for OAuth 2.0
165
 */
166
static AuthenticationScheme oauth2(String accessToken);
167

168
/**
169
 * Create OAuth 2.0 authentication scheme with custom signature
170
 * @param accessToken OAuth 2.0 access token
171
 * @param signature OAuth signature method
172
 * @return Authentication scheme for OAuth 2.0
173
 */
174
static AuthenticationScheme oauth2(String accessToken, OAuthSignature signature);
175

176
interface AuthenticationSpecification {
177
    /**
178
     * Use OAuth 2.0 authentication for this request
179
     * @param accessToken OAuth 2.0 access token
180
     * @return Updated request specification
181
     */
182
    RequestSpecification oauth2(String accessToken);
183
    
184
    /**
185
     * Use OAuth 2.0 authentication with custom signature for this request
186
     * @param accessToken OAuth 2.0 access token
187
     * @param signature OAuth signature method
188
     * @return Updated request specification
189
     */
190
    RequestSpecification oauth2(String accessToken, OAuthSignature signature);
191
}
192
```
193

194
**Usage Examples:**
195

196
```java
197
// OAuth 2.0 Bearer token authentication
198
given()
199
    .auth().oauth2("eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...")
200
.when()
201
    .get("/api/user")
202
.then()
203
    .statusCode(200);
204

205
// OAuth 2.0 with custom signature
206
given()
207
    .auth().oauth2("accessToken", OAuthSignature.HMAC_SHA1)
208
.when()
209
    .get("/api/protected");
210
```
211

212
### Certificate Authentication
213

214
Certificate-based authentication using SSL/TLS client certificates.
215

216
```java { .api }
217
/**
218
 * Create certificate authentication scheme with default SSL settings
219
 * @param certURL Path to JKS keystore containing the certificate
220
 * @param password Password for the keystore
221
 * @return Authentication scheme for certificate auth
222
 */
223
static AuthenticationScheme certificate(String certURL, String password);
224

225
/**
226
 * Create certificate authentication scheme with custom settings
227
 * @param certURL Path to JKS keystore containing the certificate
228
 * @param password Password for the keystore
229
 * @param certificateAuthSettings Advanced certificate authentication settings
230
 * @return Authentication scheme for certificate auth
231
 */
232
static AuthenticationScheme certificate(String certURL, String password, CertificateAuthSettings certificateAuthSettings);
233

234
/**
235
 * Create certificate authentication scheme with separate trust and key stores
236
 * @param trustStorePath Path to JKS trust store
237
 * @param trustStorePassword Password for the trust store
238
 * @param keyStorePath Path to JKS keystore
239
 * @param keyStorePassword Password for the keystore
240
 * @param certificateAuthSettings Advanced certificate authentication settings
241
 * @return Authentication scheme for certificate auth
242
 */
243
static AuthenticationScheme certificate(String trustStorePath, String trustStorePassword, String keyStorePath, String keyStorePassword, CertificateAuthSettings certificateAuthSettings);
244

245
interface AuthenticationSpecification {
246
    /**
247
     * Use certificate authentication for this request
248
     * @param certURL Path to certificate
249
     * @param password Certificate password
250
     * @return Updated request specification
251
     */
252
    RequestSpecification certificate(String certURL, String password);
253
    
254
    /**
255
     * Use certificate authentication with custom settings for this request
256
     * @param certURL Path to certificate
257
     * @param password Certificate password
258
     * @param certificateAuthSettings Advanced certificate settings
259
     * @return Updated request specification
260
     */
261
    RequestSpecification certificate(String certURL, String password, CertificateAuthSettings certificateAuthSettings);
262
}
263
```
264

265
**Usage Examples:**
266

267
```java
268
// Basic certificate authentication
269
given()
270
    .auth().certificate("/path/to/client-cert.jks", "keystorePassword")
271
.when()
272
    .get("/secure-api")
273
.then()
274
    .statusCode(200);
275

276
// Certificate authentication with custom settings
277
CertificateAuthSettings settings = CertificateAuthSettings.certAuthSettings()
278
    .trustStore("/path/to/truststore.jks")
279
    .keyStoreType("PKCS12")
280
    .port(8443);
281

282
given()
283
    .auth().certificate("/path/to/client.p12", "password", settings)
284
.when()
285
    .get("/mutual-tls-endpoint");
286
```
287

288
### Form Authentication
289

290
Form-based authentication that automatically handles login forms.
291

292
```java { .api }
293
/**
294
 * Create form authentication scheme with auto-detection
295
 * @param userName The username
296
 * @param password The password
297
 * @return Authentication scheme for form auth
298
 */
299
static AuthenticationScheme form(String userName, String password);
300

301
/**
302
 * Create form authentication scheme with custom configuration
303
 * @param userName The username
304
 * @param password The password
305
 * @param config Form authentication configuration
306
 * @return Authentication scheme for form auth
307
 */
308
static AuthenticationScheme form(String userName, String password, FormAuthConfig config);
309

310
interface AuthenticationSpecification {
311
    /**
312
     * Use form authentication for this request
313
     * @param userName The username
314
     * @param password The password
315
     * @return Updated request specification
316
     */
317
    RequestSpecification form(String userName, String password);
318
    
319
    /**
320
     * Use form authentication with custom configuration for this request
321
     * @param userName The username
322
     * @param password The password
323
     * @param config Form authentication configuration
324
     * @return Updated request specification
325
     */
326
    RequestSpecification form(String userName, String password, FormAuthConfig config);
327
}
328
```
329

330
**Usage Examples:**
331

332
```java
333
// Basic form authentication (auto-detects form fields)
334
given()
335
    .auth().form("user", "password")
336
.when()
337
    .get("/dashboard")
338
.then()
339
    .statusCode(200);
340

341
// Form authentication with custom configuration
342
FormAuthConfig config = FormAuthConfig.formAuthConfig()
343
    .withFormAction("/custom-login")
344
    .withUsernameField("email")
345
    .withPasswordField("pwd")
346
    .withAutoDetection(false);
347

348
given()
349
    .auth().form("user@example.com", "password", config)
350
.when()
351
    .get("/protected-page");
352
```
353

354
### NTLM Authentication
355

356
Windows NTLM authentication for corporate environments.
357

358
```java { .api }
359
/**
360
 * Create NTLM authentication scheme
361
 * @param userName The username
362
 * @param password The password
363
 * @param workstation The NTLM workstation
364
 * @param domain The NTLM domain
365
 * @return Authentication scheme for NTLM auth
366
 */
367
static AuthenticationScheme ntlm(String userName, String password, String workstation, String domain);
368

369
interface AuthenticationSpecification {
370
    /**
371
     * Use NTLM authentication for this request
372
     * @param userName The username
373
     * @param password The password
374
     * @param workstation The workstation name
375
     * @param domain The domain name
376
     * @return Updated request specification
377
     */
378
    RequestSpecification ntlm(String userName, String password, String workstation, String domain);
379
}
380
```
381

382
**Usage Examples:**
383

384
```java
385
// NTLM authentication
386
given()
387
    .auth().ntlm("domain\\user", "password", "WORKSTATION", "DOMAIN")
388
.when()
389
    .get("/corporate-api")
390
.then()
391
    .statusCode(200);
392
```
393

394
### Preemptive Authentication
395

396
Preemptive authentication that sends credentials without waiting for authentication challenge.
397

398
```java { .api }
399
/**
400
 * Create preemptive authentication provider
401
 * @return Preemptive authentication provider
402
 */
403
static PreemptiveAuthProvider preemptive();
404

405
interface AuthenticationSpecification {
406
    /**
407
     * Enable preemptive authentication
408
     * @return Preemptive authentication specification
409
     */
410
    PreemptiveAuthSpec preemptive();
411
}
412

413
interface PreemptiveAuthSpec {
414
    /**
415
     * Use preemptive basic authentication
416
     * @param userName The username
417
     * @param password The password
418
     * @return Updated request specification
419
     */
420
    RequestSpecification basic(String userName, String password);
421
}
422
```
423

424
**Usage Examples:**
425

426
```java
427
// Preemptive basic authentication (sends credentials immediately)
428
given()
429
    .auth().preemptive().basic("user", "password")
430
.when()
431
    .get("/api")
432
.then()
433
    .statusCode(200);
434
```
435

436
### No Authentication
437

438
Disable authentication for specific requests when global authentication is configured.
439

440
```java { .api }
441
interface AuthenticationSpecification {
442
    /**
443
     * Disable authentication for this request
444
     * @return Updated request specification
445
     */
446
    RequestSpecification none();
447
}
448
```
449

450
**Usage Examples:**
451

452
```java
453
// Disable global authentication for this request
454
RestAssured.authentication = basic("user", "password");
455

456
given()
457
    .auth().none() // This request won't use the global auth
458
.when()
459
    .get("/public-endpoint")
460
.then()
461
    .statusCode(200);
462
```
463

464
## Types
465

466
```java { .api }
467
// Base authentication scheme interface
468
interface AuthenticationScheme {
469
    // Implementation details handled internally
470
}
471

472
// Authentication specification interface
473
interface AuthenticationSpecification {
474
    RequestSpecification basic(String userName, String password);
475
    RequestSpecification digest(String userName, String password);
476
    RequestSpecification oauth(String consumerKey, String consumerSecret, String accessToken, String secretToken);
477
    RequestSpecification oauth(String consumerKey, String consumerSecret, String accessToken, String secretToken, OAuthSignature signature);
478
    RequestSpecification oauth2(String accessToken);
479
    RequestSpecification oauth2(String accessToken, OAuthSignature signature);
480
    RequestSpecification certificate(String certURL, String password);
481
    RequestSpecification certificate(String certURL, String password, CertificateAuthSettings certificateAuthSettings);
482
    RequestSpecification form(String userName, String password);
483
    RequestSpecification form(String userName, String password, FormAuthConfig config);
484
    RequestSpecification ntlm(String userName, String password, String workstation, String domain);
485
    PreemptiveAuthSpec preemptive();
486
    RequestSpecification none();
487
}
488

489
// Preemptive authentication specification
490
interface PreemptiveAuthSpec {
491
    RequestSpecification basic(String userName, String password);
492
}
493

494
// Preemptive authentication provider
495
class PreemptiveAuthProvider {
496
    PreemptiveAuthSpec basic(String userName, String password);
497
}
498

499
// OAuth signature methods
500
enum OAuthSignature {
501
    HMAC_SHA1, HMAC_SHA256, RSA_SHA1, PLAINTEXT;
502
}
503

504
// Form authentication configuration
505
class FormAuthConfig {
506
    static FormAuthConfig formAuthConfig();
507
    FormAuthConfig withFormAction(String formAction);
508
    FormAuthConfig withUsernameField(String usernameFieldName);
509
    FormAuthConfig withPasswordField(String passwordFieldName);
510
    FormAuthConfig withAutoDetection(boolean shouldAutoDetect);
511
    FormAuthConfig withAdditionalFields(Map<String, String> additionalFields);
512
    FormAuthConfig withCsrfFieldName(String csrfFieldName);
513
    FormAuthConfig withCsrfTokenPath(String csrfTokenPath);
514
    FormAuthConfig withLoggingEnabled(boolean isLoggingEnabled);
515
}
516

517
// Certificate authentication settings
518
class CertificateAuthSettings {
519
    static CertificateAuthSettings certAuthSettings();
520
    CertificateAuthSettings keyStore(String pathToKeyStore);
521
    CertificateAuthSettings keyStore(KeyStore keyStore);
522
    CertificateAuthSettings keyStoreType(String keyStoreType);
523
    CertificateAuthSettings keyStorePassword(String password);
524
    CertificateAuthSettings trustStore(String pathToTrustStore);
525
    CertificateAuthSettings trustStore(KeyStore trustStore);
526
    CertificateAuthSettings trustStoreType(String trustStoreType);
527
    CertificateAuthSettings trustStorePassword(String password);
528
    CertificateAuthSettings x509HostnameVerifier(X509HostnameVerifier hostnameVerifier);
529
    CertificateAuthSettings sslSocketFactory(SSLSocketFactory sslSocketFactory);
530
    CertificateAuthSettings port(int port);
531
}
532
```