Browse Source

Add sections for migrating exploit protection in 6.0

Issue gh-12462
Steve Riesenberg 2 years ago
parent
commit
bf2951b5af

+ 1 - 1
docs/modules/ROOT/pages/migration/index.adoc

@@ -4,7 +4,7 @@
 The Spring Security team has prepared the 5.8 release to simplify upgrading to Spring Security 6.0.
 Use 5.8 and
 ifdef::spring-security-version[]
-xref:5.8.0@migration/index.adoc[its preparation steps]
+xref:5.8.2@migration/index.adoc[its preparation steps]
 endif::[]
 ifndef::spring-security-version[]
 its preparation steps

+ 32 - 0
docs/modules/ROOT/pages/migration/servlet/exploits.adoc

@@ -1,7 +1,39 @@
 = Exploit Protection Migrations
 
+The 5.8 migration guide contains several steps for
+ifdef::spring-security-version[]
+xref:5.8.2@migration/servlet/exploits.adoc[exploit protection migrations] when updating to 6.0.
+endif::[]
+ifndef::spring-security-version[]
+exploit protection migrations when updating to 6.0.
+endif::[]
+You are encouraged to follow those steps first.
+
 The following steps relate to how to finish migrating exploit protection support.
 
+== Defer Loading CsrfToken
+
+In Spring Security 5.8, the default `CsrfTokenRequestHandler` for making the `CsrfToken` available to the application is `CsrfTokenRequestAttributeHandler`.
+The default for the field `csrfRequestAttributeName` is `null`, which causes the CSRF token to be loaded on every request.
+
+In Spring Security 6, `csrfRequestAttributeName` defaults to `_csrf`.
+If you configured the following only for the purpose of updating to 6.0, you can now remove it:
+
+    requestHandler.setCsrfRequestAttributeName("_csrf");
+
+== Protect against CSRF BREACH
+
+In Spring Security 5.8, the default `CsrfTokenRequestHandler` for making the `CsrfToken` available to the application is `CsrfTokenRequestAttributeHandler`.
+`XorCsrfTokenRequestAttributeHandler` was added to allow opting into CSRF BREACH support.
+
+In Spring Security 6, `XorCsrfTokenRequestAttributeHandler` is the default `CsrfTokenRequestHandler` for making the `CsrfToken` available.
+If you configured the `XorCsrfTokenRequestAttributeHandler` only for the purpose of updating to 6.0, you can remove it completely.
+
+[NOTE]
+====
+If you have set the `csrfRequestAttributeName` to `null` in order to opt out of deferred tokens, or if you have configured a `CsrfTokenRequestHandler` for any other reason, you can leave the configuration in place.
+====
+
 == CSRF BREACH with WebSocket support
 
 In Spring Security 5.8, the default `ChannelInterceptor` for making the `CsrfToken` available with xref:servlet/integrations/websocket.adoc[WebSocket Security] is `CsrfChannelInterceptor`.