Chapter 9: Configuring CSRF protection
Introduces the risk of CSRF attacks and explains why Spring Security’s default CSRF protection affected earlier HTTP POST examples.
After this chapter you will be able to
- CSRF attack risk. Explain that a CSRF-vulnerable application can be used to make an authenticated user perform unwanted actions.
- Default CSRF protection. Explain why earlier examples could not call HTTP POST endpoints directly without disabling CSRF protection.
- Logged-in user impersonation. Explain how an attacker-controlled page can cause unwanted actions in an application where the user is already logged in.
- Token requirement for mutations. Explain how a CSRF token distinguishes permitted mutating requests from requests made by a foreign page.
- CsrfFilter request checks. Describe which requests CsrfFilter allows without a token, what it requires of other requests, and how tokens are managed by default.
- CSRF protection use cases. Explain why browser-based web apps with mutating actions need CSRF protection, and distinguish the same-server frontend and backend scenario from clients developed independently of the backend.
- Custom form token submission. Trace why the example’s custom POST form initially receives HTTP 403 Forbidden and how adding the CSRF token makes the request succeed. Describe where the view obtains that token.
- Selective CSRF path exclusions. Explain how to exclude selected paths from CSRF protection while leaving protection in place for other applicable requests.
- Custom token repository responsibilities. Describe the token information and repository operations needed for the database-backed CSRF example.
- Request handler and token flow. Trace how the configured handler and repository support obtaining a token with GET and using it for a protected POST request.
What it builds on
- Adding a filter after an existing one in the chain (chapter 5) · Placing a custom filter after an existing filter in the chain.
- Implementing authentication with form-based login (chapter 6) · Assumes familiarity with Spring Security’s form-based login.
Section by section
Introduction
Introduces the risk of CSRF attacks and explains why Spring Security’s default CSRF protection affected earlier HTTP POST examples.
- CSRF attack risk: Explain that a CSRF-vulnerable application can be used to make an authenticated user perform unwanted actions.
Why it matters: This is the risk that CSRF protection is meant to address. - Default CSRF protection: Explain why earlier examples could not call HTTP POST endpoints directly without disabling CSRF protection.
Why it matters: It explains the HTTP POST behavior encountered in the earlier examples without treating disabling protection as the general solution.
Key terms: CSRF, cross-site request forgery, HTTP POST, CSRF protection
9.1 How CSRF protection works in Spring Security
The section explains how CSRF attacks exploit a logged-in user, how Spring Security checks CSRF tokens, and how a small example makes that behavior visible.
- Logged-in user impersonation: Explain how an attacker-controlled page can cause unwanted actions in an application where the user is already logged in.
Why it matters: This is the threat the token check is meant to prevent. - Token requirement for mutations: Explain how a CSRF token distinguishes permitted mutating requests from requests made by a foreign page.
Why it matters: The token requirement explains why a foreign page cannot simply submit changes on the user's behalf. - CsrfFilter request checks: Describe which requests CsrfFilter allows without a token, what it requires of other requests, and how tokens are managed by default.
Why it matters: These rules explain both the default 403 response and why the session matters when reusing a token. - Token retrieval demonstration: Trace how the example obtains a token from a GET request and uses it, with the same session, to make a successful POST request.
Why it matters: The example connects the filter's token check to a GET-then-POST test without disabling CSRF protection.
Key terms: CSRF attacks, forgery code, CSRF token, mutating operations, CsrfFilter, CsrfTokenRepository, HTTP session, HTTP 403 Forbidden, _csrf, CsrfToken
9.2 Using CSRF protection in practical scenarios
This section shows when CSRF protection fits a web application and how a browser form must send a token for a mutating request to succeed.
- CSRF protection use cases: Explain why browser-based web apps with mutating actions need CSRF protection, and distinguish the same-server frontend and backend scenario from clients developed independently of the backend.
Why it matters: It helps you recognize where the token-based approach shown here is a good fit. - Default login token handling: Explain why Spring Security’s default form login succeeds with CSRF protection enabled even though login submits an HTTP POST request.
Why it matters: It explains why a working default login does not mean your own POST forms can omit the token. - Custom form token submission: Trace why the example’s custom POST form initially receives HTTP 403 Forbidden and how adding the CSRF token makes the request succeed. Describe where the view obtains that token.
Why it matters: It connects a rejected mutating request to the concrete token your own page must send. - GET request mutation warning: Explain why the section warns against implementing data-changing behavior through an HTTP GET endpoint.
Why it matters: Using GET for a data-changing action would bypass the token requirement described in this section.
Key terms: CSRF protection, CSRF tokens, mutating operations, default form login, CSRF token, hidden input, HTTP POST, HTTP 403 Forbidden, CsrfFilter, _csrf
9.3 Customizing CSRF protection
This section shows how to exempt selected requests from CSRF protection and replace session-based token storage with a database-backed implementation.
- Selective CSRF path exclusions: Explain how to exclude selected paths from CSRF protection while leaving protection in place for other applicable requests.
Why it matters: You can exempt an endpoint without disabling CSRF protection across the application. - Database token storage rationale: Justify why the example replaces HTTP-session CSRF token storage with database storage, and describe how it associates a token with a client.
Why it matters: The storage choice explains why the example needs both a database and a way to identify the client. - Custom token repository responsibilities: Describe the token information and repository operations needed for the database-backed CSRF example.
Why it matters: These contracts define what must change when token management moves from the session to the database. - Request handler and token flow: Trace how the configured handler and repository support obtaining a token with GET and using it for a protected POST request.
Why it matters: The flow connects the custom configuration to what a client must send when calling a protected endpoint.
Key terms: csrf(), Customizer, ignoringRequestMatchers(), RequestMatcher, MvcRequestMatcher, HTTP session, horizontal scaling, client ID, session ID, CsrfToken
9.4 Summary
Where this is used later
- The sins of OAuth 2 (chapter 13) · Introduces CSRF protection.
- Testing CSRF configurations (chapter 18) · Spring Security’s use of CSRF tokens to protect mutating requests
Concepts explained in this chapter
- csrf protectionCSRF protection is a web-security mechanism that prevents forged state-changing requests from an authenticated user's browser.
- CsrfTokenRepositoryCsrfTokenRepository is a Spring Security interface for generating, storing, retrieving, and invalidating CSRF tokens.
- mutationA mutating operation is an application operation that changes stored data or other server-side state.
- CsrfTokenRequestHandlerCsrfTokenRequestHandler is a Spring Security interface for managing how a generated CSRF token is associated with an HTTP request.
- CsrfTokenRequestAttributeHandlerCsrfTokenRequestAttributeHandler is a Spring Security implementation that exposes a generated CSRF token as an HTTP request attribute.
- request matcherRequestMatcher is an API contract for determining whether an HTTP request matches specified request attributes.
- cross-site request forgeryCross-site request forgery is an attack that causes a user's authenticated browser to send an unintended state-changing request to a web application.
- CsrfFilterCsrfFilter is a Spring Security filter that processes protection against cross-site request forgery.
- servlet request attributeA request attribute is a named value attached to an HTTP request for access by components processing that request.
- hidden fieldA hidden input is an HTML form control whose value is submitted with the form but is not displayed to the user.
- CustomizerCustomizer is a Spring configuration functional interface whose callback applies customization to a framework configuration object.
- HttpSecurityHttpSecurity is a Spring Security configuration API for defining servlet-based web authentication, authorization, and protection settings.
- MVC matcherMvcRequestMatcher is a Spring Security request matcher that evaluates paths using Spring MVC request-mapping conventions.
← Chapter 8: Configuring endpoint-level authorization: Applying restrictions
Chapter 10: Configuring CORS →
These guides are generated from the text of Manning books by Manning's knowledge graph and link to the sections they draw on. The full books are available on liveBook and at manning.com.