skip to content

How do you test a secured endpoint with TestRestTemplate — for example sending HTTP Basic credentials?

level: middleimportance: should knowfreq 50%

answer

  1. withBasicAuth returns a NEW instance — use it
  2. real filter chain runs: 200 / 401 / 403
  3. 401 = auth fails, 403 = authorized fails
  4. bearer/custom → set HttpHeaders + exchange
  5. ENABLE_COOKIES for session flows

basics

~20 s

Call rest.withBasicAuth("user", "password") — it returns a new TestRestTemplate that adds an HTTP Basic Authorization header to every request. Use the returned instance. Because it makes a real request, the whole Spring Security filter chain runs and you assert 200 vs 401/403.

solid answer

~40 s

TestRestTemplate has withBasicAuth(username, password), which returns a NEW TestRestTemplate that attaches a Basic Authorization header to each call — you must use the returned instance, since the original is unchanged. Because the request is real HTTP through the running server, the full Spring Security filter chain executes: authentication, authorization, method security. So you can assert 200 for valid credentials, 401 for missing/bad credentials, and 403 for authenticated-but-unauthorized. For token/cookie schemes instead of Basic, set the Authorization or Cookie header yourself via HttpHeaders and exchange with an HttpEntity. For session-based flows you may also need HttpClientOption.ENABLE_COOKIES so the session cookie is carried across calls. This end-to-end execution of security is a major reason to use TestRestTemplate over slice tests.

code

java · 26 lines
java
@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
class SecuredEndpointTest {

    @Autowired TestRestTemplate rest;

    @Test
    void validCredentials_200() {
        // MUST use the returned instance; withBasicAuth does not mutate 'rest'.
        ResponseEntity<String> r = rest.withBasicAuth("admin", "secret")
                .getForEntity("/api/admin/stats", String.class);
        assertThat(r.getStatusCode()).isEqualTo(HttpStatus.OK);
    }

    @Test
    void noCredentials_401() {
        assertThat(rest.getForEntity("/api/admin/stats", String.class)
                .getStatusCode()).isEqualTo(HttpStatus.UNAUTHORIZED);
    }

    @Test
    void wrongRole_403() {
        assertThat(rest.withBasicAuth("viewer", "pw")
                .getForEntity("/api/admin/stats", String.class)
                .getStatusCode()).isEqualTo(HttpStatus.FORBIDDEN);
    }
}

go deeper

for a junior

Know withBasicAuth adds Basic credentials and you assert 200 vs 401.

for a middle

Explain the new-instance semantics, 401 vs 403, and bearer-token via HttpHeaders+exchange.

for a senior

Cover ENABLE_COOKIES for session flows and why real-filter execution beats @WithMockUser slice tests.

for a principal

Weigh full end-to-end security tests vs faster slice tests in the overall test pyramid and CI cost.

### The problem A secured endpoint requires credentials. With a real HTTP call, you must present them exactly as a client would — and the running server's **entire Spring Security filter chain** will evaluate them. ### withBasicAuth — the idiomatic helper `TestRestTemplate.withBasicAuth(String username, String password)` returns a **new** `TestRestTemplate` configured to add an `Authorization: Basic <base64(user:pass)>` header to every request. Two important properties: 1. It is **non-mutating** — it returns a new instance and leaves the original untouched. A classic bug is calling `rest.withBasicAuth(...)` and then using `rest` (unauthenticated). Always use the returned value. 2. It works with the auto-configured, port-aware instance, so you keep using relative URLs. ```java ResponseEntity<String> ok = rest .withBasicAuth("admin", "secret") .getForEntity("/api/admin/stats", String.class); assertThat(ok.getStatusCode()).isEqualTo(HttpStatus.OK); ``` ### The three status codes you typically assert - **200/2xx** — valid credentials, authorized. - **401 Unauthorized** — no credentials or bad credentials (authentication failed). Test by calling with no auth or wrong password. - **403 Forbidden** — authenticated but lacking the required role/authority (authorization failed). Test with a valid but under-privileged user. Because the real filter chain runs (including `@PreAuthorize` method security if enabled), these outcomes reflect production behavior. ### Non-Basic schemes (bearer tokens, custom headers) `withBasicAuth` only covers Basic. For a JWT/bearer token or custom header, build the header yourself and use `exchange`: ```java HttpHeaders headers = new HttpHeaders(); headers.setBearerAuth(jwt); // Authorization: Bearer <jwt> HttpEntity<Void> req = new HttpEntity<>(headers); ResponseEntity<String> r = rest.exchange( "/api/me", HttpMethod.GET, req, String.class); ``` ### Cookie/session flows By default TestRestTemplate does **not** persist cookies between calls. For a login-then-call session flow, construct it with `TestRestTemplate.HttpClientOption.ENABLE_COOKIES` so the `JSESSIONID`/session cookie set by the first response is sent on subsequent calls. Alternatively capture `Set-Cookie` from the first response and replay it manually via headers. ### Constructor-based Basic auth You can also bake credentials in at construction: `new TestRestTemplate("user", "pass")`. `withBasicAuth` is usually cleaner because it reuses the auto-configured, port-aware bean. ### Why this beats slice tests for security `@WebMvcTest` with `@WithMockUser` short-circuits real authentication (it injects a fake principal). A `TestRestTemplate` call exercises the **actual** authentication mechanism — real password/token verification, real filters — so it catches misconfigured security that a mocked principal would hide.

  • What's the difference between a 401 and a 403 in these tests?
    401 Unauthorized means authentication failed — no or invalid credentials. 403 Forbidden means the caller authenticated successfully but lacks the required role/authority for that resource.
  • How would you send a JWT bearer token instead of Basic auth?
    withBasicAuth only does Basic. Build HttpHeaders with headers.setBearerAuth(token), wrap in an HttpEntity, and call rest.exchange(url, method, entity, Type.class).

  • Calling rest.withBasicAuth(...) but then using the original rest (it returns a new instance).
  • Confusing 401 (authentication) with 403 (authorization).
  • Assuming cookies/session persist across calls without ENABLE_COOKIES.

context