Add ConditionalAuthorizationManager

Closes gh-18919

docs/modules/ROOT/pages/servlet/authorization/architecture.adoc

@@ -144,6 +144,16 @@ Another manager is the `AuthenticatedAuthorizationManager`.
 It can be used to differentiate between anonymous, fully-authenticated and remember-me authenticated users.
 Many sites allow certain limited access under remember-me authentication, but require a user to confirm their identity by logging in for full access.
 
+[[authz-conditional-authorization-manager]]
+==== ConditionalAuthorizationManager
+javadoc:org.springframework.security.authorization.ConditionalAuthorizationManager[] delegates to one of two ``AuthorizationManager``s based on a condition evaluated against the current ``Authentication``.
+When the condition returns true (and the authentication is non-null), the ``whenTrue`` manager is used; otherwise the ``whenFalse`` manager is used.
+Create an instance using the builder returned by `ConditionalAuthorizationManager.when(Predicate<Authentication>)`: set `whenTrue` (required) and optionally `whenFalse` (defaults to permit-all).
+This is useful for scenarios such as requiring multi-factor authentication only when the user has registered a second factor.
+
+.ConditionalAuthorizationManager example
+include-code::./ConditionalAuthorizationManagerExample[tag=conditionalAuthorizationManager,indent=0]
+
 [[authz-authorization-manager-factory]]
 === Creating AuthorizationManager instances
 

docs/modules/ROOT/pages/whats-new.adoc

@@ -5,6 +5,7 @@
 
 * https://github.com/spring-projects/spring-security/pull/18634[gh-18634] - Added javadoc:org.springframework.security.web.util.matcher.InetAddressMatcher[]
 * https://github.com/spring-projects/spring-security/issues/18755[gh-18755] - Include `charset` in `WWW-Authenticate` header
+* Added xref:servlet/authorization/architecture.adoc#authz-conditional-authorization-manager[ConditionalAuthorizationManager]
 
 == OAuth 2.0
 

docs/src/test/java/org/springframework/security/docs/servlet/authorization/authzconditionalauthorizationmanager/ConditionalAuthorizationManagerExample.java

@@ -0,0 +1,33 @@
+package org.springframework.security.docs.servlet.authorization.authzconditionalauthorizationmanager;
+
+import java.util.function.Predicate;
+
+import org.springframework.security.authorization.AllRequiredFactorsAuthorizationManager;
+import org.springframework.security.authorization.AuthorizationManager;
+import org.springframework.security.authorization.ConditionalAuthorizationManager;
+import org.springframework.security.core.Authentication;
+import org.springframework.security.web.access.intercept.RequestAuthorizationContext;
+
+public class ConditionalAuthorizationManagerExample {
+
+	public void configure(MfaRepository mfaRepository) {
+		// tag::conditionalAuthorizationManager[]
+		Predicate<Authentication> whenUserHasMfa = (auth) -> mfaRepository.hasRegisteredMfa(auth.getName());
+		AuthorizationManager<RequestAuthorizationContext> mfaRequired = AllRequiredFactorsAuthorizationManager
+			.<RequestAuthorizationContext>builder()
+			.requireFactor((f) -> f.passwordAuthority())
+			.requireFactor((f) -> f.webauthnAuthority())
+			.build();
+		AuthorizationManager<RequestAuthorizationContext> manager = ConditionalAuthorizationManager.<RequestAuthorizationContext>when(whenUserHasMfa)
+			.whenTrue(mfaRequired)
+			.build();
+		// end::conditionalAuthorizationManager[]
+	}
+
+	interface MfaRepository {
+
+		boolean hasRegisteredMfa(String username);
+
+	}
+
+}

docs/src/test/kotlin/org/springframework/security/kt/docs/servlet/authorization/authzconditionalauthorizationmanager/ConditionalAuthorizationManagerExample.kt

@@ -0,0 +1,26 @@
+package org.springframework.security.kt.docs.servlet.authorization.authzconditionalauthorizationmanager;
+
+import org.springframework.security.authorization.AllRequiredFactorsAuthorizationManager
+import org.springframework.security.authorization.ConditionalAuthorizationManager
+import org.springframework.security.core.Authentication
+import org.springframework.security.web.access.intercept.RequestAuthorizationContext
+import java.util.function.Predicate
+
+class ConditionalAuthorizationManagerExample {
+    fun configure(mfaRepository: MfaRepository) {
+        // tag::conditionalAuthorizationManager[]
+        val whenUserHasMfa = Predicate { auth: Authentication -> mfaRepository.hasRegisteredMfa(auth.name) }
+        val mfaRequired = AllRequiredFactorsAuthorizationManager.builder<RequestAuthorizationContext>()
+            .requireFactor { f -> f.passwordAuthority() }
+            .requireFactor { f -> f.webauthnAuthority() }
+            .build()
+        val manager = ConditionalAuthorizationManager.`when`<RequestAuthorizationContext>(whenUserHasMfa)
+            .whenTrue(mfaRequired)
+            .build()
+        // end::conditionalAuthorizationManager[]
+    }
+
+    interface MfaRepository {
+        fun hasRegisteredMfa(username: String?): Boolean
+    }
+}