How does REST Assured let you authenticate requests, and what is the difference between its basic() and preemptive().basic() authentication options?

## Where auth lives in the DSL Authentication is part of the **request specification**, so it is configured in the `given()` stage via `auth()`. Everything it does ultimately amounts to adding headers (or configuring TLS material) — REST Assured has no privileged access to your server; it is an HTTP client. ## Challenged vs preemptive Basic authentication HTTP Basic authentication, as specified for HTTP, is a **challenge-response** scheme: the client requests a protected resource without credentials, the server replies `401 Unauthorized` with a `WWW-Authenticate: Basic realm="..."` header, and the client retries with `Authorization: Basic base64(user:password)`. `given().auth().basic(user, pass)` implements exactly that: the first request carries **no** credentials. REST Assured only attaches them after seeing a proper 401 challenge. `given().auth().preemptive().basic(user, pass)` skips the negotiation and sends `Authorization: Basic ...` on the first request. Why the distinction matters in practice: 1. **Round trips.** Challenged basic doubles the request count on every protected call — noticeable in a suite of hundreds of tests, and it pollutes server logs and metrics with 401s. 2. **Servers that do not challenge.** Many APIs return `401` or `403` with no `WWW-Authenticate` header, or redirect to an HTML login page, because they are designed for token auth or for clients that always send credentials. Against those, challenged basic never sends the credentials at all, and the test fails with a 401/403 that looks like a credential problem when it is really a negotiation problem. "My username and password are definitely right but I get 401" is the classic symptom, and switching to `preemptive()` is the classic fix. 3. **Non-idempotent requests.** With a POST, the challenged flow may send the body twice (once rejected, once accepted), which is wasteful and occasionally surprising if a proxy or filter counts requests. The rule of thumb: **use `preemptive().basic(...)` unless you are specifically testing the challenge behaviour itself.** ## Token-based auth Most modern APIs use bearer tokens. Two equivalent routes: ```java given().auth().oauth2(accessToken) // sets Authorization: Bearer <token> given().header("Authorization", "Bearer " + accessToken) ``` `auth().oauth2(...)` is a convenience over the header; there is no OAuth flow being executed. Acquiring the token is your job — typically one REST Assured call to the token endpoint whose result you extract and cache: ```java String token = given() .contentType(ContentType.URLENC) .formParam("grant_type", "client_credentials") .formParam("client_id", id).formParam("client_secret", secret) .when().post("/oauth/token") .then().statusCode(200) .extract().path("access_token"); ``` Cache it for the suite rather than re-fetching per test, but respect expiry — a suite that runs longer than the token lifetime will start failing halfway through with 401s, which looks like flakiness. A `Filter` that refreshes the token when a response is 401 is a clean way to handle it. ## Other supported schemes - **Digest**: `auth().digest(user, pass)` — challenge-based by design. - **Form**: `auth().form(user, pass, new FormAuthConfig("/login", "username", "password"))`, which posts the login form, keeps the session cookie and reuses it. `FormAuthConfig.springSecurity()` is a preset for the conventional Spring Security login endpoint. `auth().form(...)` without a config attempts to autodetect the form fields by parsing the login page, which is brittle. - **Cookie/session**: after any login call, `extract().sessionId()` or `extract().cookies()` and then `given().sessionId(id)` / `given().cookies(map)`. - **Certificate / mTLS**: `auth().certificate(keystorePath, password, certAuthSettings)`, plus `RestAssured.config().sslConfig(...)` for trust stores. `relaxedHTTPSValidation()` disables certificate checks — acceptable against a throwaway test environment with self-signed certs, never something to leave in a suite that points at a real one. ## Applying it across a suite Repeating credentials in every test is noise. Options, in increasing order of discipline: - `RestAssured.authentication = preemptive().basic(user, pass);` in suite setup — a static global, so reset it afterwards. - A shared `RequestSpecification` built once with `RequestSpecBuilder().setAuth(...)` and passed to `given().spec(authedSpec)`. - A `Filter` that injects the current token, so refresh logic lives in one place. And a single test that needs to check the unauthenticated path uses `given().auth().none()` to opt out of whatever global default is in force. Testing the negative cases — no credentials, wrong credentials, valid credentials but insufficient role — is exactly the kind of coverage an API-level suite is good at, and it depends on being able to turn the default off. ## Secrets hygiene Credentials belong in environment variables or a secret store read at runtime, not hardcoded in test sources that live in version control. And remember that `log().all()` prints the `Authorization` header: use `log().ifValidationFails()` plus `config().logConfig(logConfig().blacklistHeader("Authorization"))` so a CI log does not leak a token.