From 57d6ab7134a77cf28bb37f56672080ef8fa96f6b Mon Sep 17 00:00:00 2001
From: Marcus Da Coregio <marcusdacoregio@gmail.com>
Date: Wed, 13 Jul 2022 09:04:21 -0300
Subject: [PATCH] Improve docs on dispatcherTypeMatcher

Closes gh-11467
---
 .../authorize-http-requests.adoc              | 75 +++++++++++++++++++
 .../authorization/authorize-requests.adoc     | 68 +++++++++++++++++
 2 files changed, 143 insertions(+)

diff --git a/docs/modules/ROOT/pages/servlet/authorization/authorize-http-requests.adoc b/docs/modules/ROOT/pages/servlet/authorization/authorize-http-requests.adoc
index 8b994db9a6..e3005ed304 100644
--- a/docs/modules/ROOT/pages/servlet/authorization/authorize-http-requests.adoc
+++ b/docs/modules/ROOT/pages/servlet/authorization/authorize-http-requests.adoc
@@ -205,3 +205,78 @@ open fun web(http: HttpSecurity): SecurityFilterChain {
 }
 ----
 ====
+
+Now with the authorization rules applying to all dispatcher types, you have more control of the authorization on them.
+For example, you may want to configure `shouldFilterAllDispatcherTypes` to `true` but not apply authorization on requests with dispatcher type `ASYNC` or `FORWARD`.
+
+.Permit ASYNC and FORWARD dispatcher type
+====
+.Java
+[source,java,role="primary"]
+----
+@Bean
+SecurityFilterChain web(HttpSecurity http) throws Exception {
+    http
+        .authorizeHttpRequests((authorize) -> authorize
+            .shouldFilterAllDispatcherTypes(true)
+            .dispatcherTypeMatchers(DispatcherType.ASYNC, DispatcherType.FORWARD).permitAll()
+            .anyRequest().authenticated()
+        )
+        // ...
+
+    return http.build();
+}
+----
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+@Bean
+open fun web(http: HttpSecurity): SecurityFilterChain {
+    http {
+        authorizeHttpRequests {
+            shouldFilterAllDispatcherTypes = true
+            authorize(DispatcherTypeRequestMatcher(DispatcherType.ASYNC, DispatcherType.FORWARD), permitAll)
+            authorize(anyRequest, authenticated)
+        }
+    }
+    return http.build()
+}
+----
+====
+
+You can also customize it to require a specific role for a dispatcher type:
+
+.Require ADMIN for Dispatcher Type ERROR
+====
+.Java
+[source,java,role="primary"]
+----
+@Bean
+SecurityFilterChain web(HttpSecurity http) throws Exception {
+    http
+        .authorizeHttpRequests((authorize) -> authorize
+            .shouldFilterAllDispatcherTypes(true)
+            .dispatcherTypeMatchers(DispatcherType.ERROR).hasRole("ADMIN")
+            .anyRequest().authenticated()
+        )
+        // ...
+
+    return http.build();
+}
+----
+.Kotlin
+[source,kotlin,role="secondary"]
+----
+@Bean
+open fun web(http: HttpSecurity): SecurityFilterChain {
+    http {
+        authorizeHttpRequests {
+            shouldFilterAllDispatcherTypes = true
+            authorize(DispatcherTypeRequestMatcher(DispatcherType.ERROR), hasRole("ADMIN"))
+            authorize(anyRequest, authenticated)
+        }
+    }
+    return http.build()
+}
+----
+====
diff --git a/docs/modules/ROOT/pages/servlet/authorization/authorize-requests.adoc b/docs/modules/ROOT/pages/servlet/authorization/authorize-requests.adoc
index 3009ba4f36..505773efca 100644
--- a/docs/modules/ROOT/pages/servlet/authorization/authorize-requests.adoc
+++ b/docs/modules/ROOT/pages/servlet/authorization/authorize-requests.adoc
@@ -137,3 +137,71 @@ You will notice that since we are invoking the `hasRole` method we do not need t
 You will notice that since we are using the `hasRole` expression we do not need to specify the "ROLE_" prefix.
 <5> Any URL that has not already been matched on is denied access.
 This is a good strategy if you do not want to accidentally forget to update your authorization rules.
+
+[[filtersecurityinterceptor-every-request]]
+== Apply FilterSecurityInterceptor to every request
+
+By default, the `FilterSecurityInterceptor` only applies once to a request.
+This means that if a request is dispatched from a request that was already filtered, the `FilterSecurityInterceptor` will back-off and not perform any authorization checks.
+In some scenarios, you may want to apply the filter to every request.
+You can configure Spring Security to apply the authorization rules to every request by using the `filterSecurityInterceptorOncePerRequest` method:
+
+.Set filterSecurityInterceptorOncePerRequest to false
+====
+.Java
+[source,java,role="primary"]
+----
+@Bean
+SecurityFilterChain web(HttpSecurity http) throws Exception {
+    http
+        .authorizeRequests((authorize) -> authorize
+            .filterSecurityInterceptorOncePerRequest(false)
+            .anyRequest.authenticated()
+        )
+        // ...
+
+    return http.build();
+}
+----
+.XML
+[source,xml]
+----
+<http once-per-request="false">
+    <intercept-url pattern="/**" access="authenticated"/>
+</http>
+----
+====
+
+You can also configure authorization based on the request dispatcher type:
+
+.Permit ASYNC dispatcher type
+====
+.Java
+[source,java,role="primary"]
+----
+@Bean
+SecurityFilterChain web(HttpSecurity http) throws Exception {
+    http
+        .authorizeRequests((authorize) -> authorize
+            .filterSecurityInterceptorOncePerRequest(false)
+            .dispatcherTypeMatchers(DispatcherType.ASYNC).permitAll()
+            .anyRequest.authenticated()
+        )
+        // ...
+
+    return http.build();
+}
+----
+.XML
+[source,xml]
+----
+<http auto-config="true" once-per-request="false">
+    <intercept-url request-matcher-ref="dispatcherTypeMatcher" access="permitAll" />
+    <intercept-url pattern="/**" access="authenticated"/>
+</http>
+
+<b:bean id="dispatcherTypeMatcher" class="org.springframework.security.web.util.matcher.DispatcherTypeRequestMatcher">
+    <b:constructor-arg value="ASYNC"/>
+</b:bean>
+----
+====