Add Initial Documentation

Issue spring-projectsgh-17934

Author: jzheaux

docs/modules/ROOT/nav.adoc

@@ -49,6 +49,7 @@
 ***** xref:servlet/authentication/passwords/password-encoder.adoc[PasswordEncoder]
 ***** xref:servlet/authentication/passwords/dao-authentication-provider.adoc[DaoAuthenticationProvider]
 ***** xref:servlet/authentication/passwords/ldap.adoc[LDAP]
+*** xref:servlet/authentication/adaptive.adoc[Multifactor Authentication]
 *** xref:servlet/authentication/persistence.adoc[Persistence]
 *** xref:servlet/authentication/passkeys.adoc[Passkeys]
 *** xref:servlet/authentication/onetimetoken.adoc[One-Time Token]

docs/modules/ROOT/pages/servlet/authentication/adaptive.adoc

@@ -0,0 +1,101 @@
+= Adaptive Authentication
+
+Since authentication needs can vary from person-to-person and even from one login attempt to the next, Spring Security supports adapting authentication requirements to each situation.
+
+Some of the most common applications of this principal are:
+
+1. *Re-authentication* - Users need to provide authentication again in order to enter an area of elevated security
+2. *Multi-factor Authentication* - Users need more than one authentication mechanism to pass in order to access secured resources
+3. *Authorizing More Scopes* - Users are allowed to consent to a subset of scopes from an OAuth 2.0 Authorization Server.
+Then, if later on a scope that they did not grant is needed, consent can be re-requested for just that scope.
+4. *Opting-in to Stronger Authentication Mechanisms* - Users may not be ready yet to start using MFA, but the application wants to allow the subset of security-minded users to opt-in.
+5. *Requiring Additional Steps for Suspicious Logins* - The application may notice that the user's IP address has changed, that they are behind a VPN, or some other consideration that requires additional verification
+
+[[re-authentication]]
+== Re-authentication
+
+The most common of these is re-authentication.
+Imagine an application configured in the following way:
+
+include-code::./SimpleConfiguration[tag=httpSecurity,indent=0]
+
+By default, this application has two authentication mechanisms that it allows, meaning that the user could use either one and be fully-authenticated.
+
+If there is a set of endpoints that require a specific factor, we can specify that in `authorizeHttpRequests` as follows:
+
+include-code::./RequireOttConfiguration[tag=httpSecurity,indent=0]
+<1> - States that all `/profile/**` endpoints require one-time-token login to be authorized
+
+Given the above configuration, users can log in with any mechanism that you support.
+And, if they want to visit the profile page, then Spring Security will redirect them to the One-Time-Token Login page to obtain it.
+
+In this way, the authority given to a user is directly proportional to the amount of proof given.
+This adaptive approach allows users to give only the proof needed to perform their intended operations.
+
+[[multi-factor-authentication]]
+== Multi-Factor Authentication
+
+You may require that all users require both One-Time-Token login and Username/Password login to access any part of your site.
+
+To require both, you can state an authorization rule with `anyRequest` like so:
+
+include-code::./ListAuthoritiesConfiguration[tag=httpSecurity,indent=0]
+<1> - This states that both `FACTOR_PASSWORD` and `FACTOR_OTT` are needed to use any part of the application
+
+Spring Security behind the scenes knows which endpoint to go to depending on which authority is missing.
+If the user logged in initially with their username and password, then Spring Security redirects to the One-Time-Token Login page.
+If the user logged in initially with a token, then Spring Security redirects to the Username/Password Login page.
+
+[[authorization-manager-factory]]
+=== Requiring MFA For All Endpoints
+
+Specifying all authorities for each request pattern could be unwanted boilerplate:
+
+include-code::./ListAuthoritiesEverywhereConfiguration[tag=httpSecurity,indent=0]
+<1> - Since all authorities need to be specified for each endpoint, deploying MFA in this way can create unwanted boilerplate
+
+This can be remedied by publishing an `AuthorizationManagerFactory` bean like so:
+
+include-code::./UseAuthorizationManagerFactoryConfiguration[tag=authorizationManagerFactoryBean,indent=0]
+
+This yields a more familiar configuration:
+
+include-code::./UseAuthorizationManagerFactoryConfiguration[tag=httpSecurity,indent=0]
+
+[[obtaining-more-authorization]]
+== Authorizing More Scopes
+
+You can also configure exception handling to direct Spring Security on how to obtain a missing scope.
+
+Consider an application that requires a specific OAuth 2.0 scope for a given endpoint:
+
+include-code::./ScopeConfiguration[tag=httpSecurity,indent=0]
+
+If this is also configured with an `AuthorizationManagerFactory` bean like this one:
+
+include-code::./MissingAuthorityConfiguration[tag=authorizationManagerFactoryBean,indent=0]
+
+Then the application will require an X.509 certificate as well as authorization from an OAuth 2.0 authorization server.
+
+In the event that the user does not consent to `profile:read`, this application as it stands will issue a 403.
+However, if you have a way for the application to re-ask for consent, then you can implement this in an `AuthenticationEntryPoint` like the following:
+
+include-code::./MissingAuthorityConfiguration[tag=authenticationEntryPoint,indent=0]
+
+Then, your filter chain declaration can bind this entry point to the given authority like so:
+
+include-code::./MissingAuthorityConfiguration[tag=httpSecurity,indent=0]
+
+[[custom-authorization-manager-factory]]
+== Programmatically Decide Which Authorities Are Required
+
+`AuthorizationManager` is the core interface for making authorization decisions.
+Consider an authorization manager that looks at the logged in user to decide which factors are necessary:
+
+include-code::./CustomAuthorizationManagerFactory[tag=authorizationManager,indent=0]
+
+In this case, using One-Time-Token is only required for those who have opted in.
+
+This can then be enforced by a custom `AuthorizationManagerFactory` implementation:
+
+include-code::./CustomAuthorizationManagerFactory[tag=authorizationManagerFactory,indent=0]

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

@@ -15,6 +15,7 @@ Each section that follows will indicate the more notable removals as well as the
 
 == Core
 
+* Added Support for xref:servlet/authentication/adaptive.adoc[Multi-factor Authentication]
 * Removed `AuthorizationManager#check` in favor of `AuthorizationManager#authorize`
 * Added javadoc:org.springframework.security.authorization.AllAuthoritiesAuthorizationManager[] and javadoc:org.springframework.security.authorization.AllAuthoritiesReactiveAuthorizationManager[] along with corresponding methods for xref:servlet/authorization/authorize-http-requests.adoc#authorize-requests[Authorizing `HttpServletRequests`] and xref:servlet/authorization/method-security.adoc#using-authorization-expression-fields-and-methods[method security expressions].
 * Added xref:servlet/authorization/architecture.adoc#authz-authorization-manager-factory[`AuthorizationManagerFactory`] for creating `AuthorizationManager` instances in xref:servlet/authorization/authorize-http-requests.adoc#customizing-authorization-managers[request-based] and xref:servlet/authorization/method-security.adoc#customizing-authorization-managers[method-based] authorization components

docs/src/test/java/org/springframework/security/docs/servlet/authentication/authorizationmanagerfactory/AuthorizationManagerFactoryTests.java

@@ -0,0 +1,114 @@
+/*
+ * Copyright 2004-present the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *      https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.springframework.security.docs.servlet.authentication.authorizationmanagerfactory;
+
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+
+import org.springframework.beans.factory.annotation.Autowired;
+import org.springframework.security.config.test.SpringTestContext;
+import org.springframework.security.config.test.SpringTestContextExtension;
+import org.springframework.security.docs.servlet.authentication.servletx509config.CustomX509Configuration;
+import org.springframework.security.test.context.support.WithMockUser;
+import org.springframework.security.test.context.support.WithSecurityContextTestExecutionListener;
+import org.springframework.test.context.TestExecutionListeners;
+import org.springframework.test.context.junit.jupiter.SpringExtension;
+import org.springframework.test.web.servlet.MockMvc;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+import static org.springframework.security.test.web.servlet.response.SecurityMockMvcResultMatchers.authenticated;
+import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.get;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.redirectedUrl;
+import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.status;
+
+/**
+ * Tests {@link CustomX509Configuration}.
+ *
+ * @author Rob Winch
+ */
+@ExtendWith({ SpringExtension.class, SpringTestContextExtension.class })
+@TestExecutionListeners(WithSecurityContextTestExecutionListener.class)
+public class AuthorizationManagerFactoryTests {
+
+	public final SpringTestContext spring = new SpringTestContext(this);
+
+	@Autowired
+	MockMvc mockMvc;
+
+	@Test
+	@WithMockUser(authorities = { "FACTOR_PASSWORD", "FACTOR_OTT" })
+	void getWhenAuthenticatedWithPasswordAndOttThenPermits() throws Exception {
+		this.spring.register(UseAuthorizationManagerFactoryConfiguration.class, Http200Controller.class).autowire();
+		// @formatter:off
+		this.mockMvc.perform(get("/"))
+			.andExpect(status().isOk())
+			.andExpect(authenticated().withUsername("user"));
+		// @formatter:on
+	}
+
+	@Test
+	@WithMockUser(authorities = "FACTOR_PASSWORD")
+	void getWhenAuthenticatedWithPasswordThenRedirectsToOtt() throws Exception {
+		this.spring.register(UseAuthorizationManagerFactoryConfiguration.class, Http200Controller.class).autowire();
+		// @formatter:off
+		this.mockMvc.perform(get("/"))
+			.andExpect(status().is3xxRedirection())
+			.andExpect(redirectedUrl("http://localhost/login?factor=ott"));
+		// @formatter:on
+	}
+
+	@Test
+	@WithMockUser(authorities = "FACTOR_OTT")
+	void getWhenAuthenticatedWithOttThenRedirectsToPassword() throws Exception {
+		this.spring.register(UseAuthorizationManagerFactoryConfiguration.class, Http200Controller.class).autowire();
+		// @formatter:off
+		this.mockMvc.perform(get("/"))
+			.andExpect(status().is3xxRedirection())
+			.andExpect(redirectedUrl("http://localhost/login?factor=password"));
+		// @formatter:on
+	}
+
+	@Test
+	@WithMockUser
+	void getWhenAuthenticatedThenRedirectsToPassword() throws Exception {
+		this.spring.register(UseAuthorizationManagerFactoryConfiguration.class, Http200Controller.class).autowire();
+		// @formatter:off
+		this.mockMvc.perform(get("/"))
+			.andExpect(status().is3xxRedirection())
+			.andExpect(redirectedUrl("http://localhost/login?factor=password"));
+		// @formatter:on
+	}
+
+	@Test
+	void getWhenUnauthenticatedThenRedirectsToBoth() throws Exception {
+		this.spring.register(UseAuthorizationManagerFactoryConfiguration.class, Http200Controller.class).autowire();
+		// @formatter:off
+		this.mockMvc.perform(get("/"))
+			.andExpect(status().is3xxRedirection())
+			.andExpect(redirectedUrl("http://localhost/login"));
+		// @formatter:on
+	}
+
+	@RestController
+	static class Http200Controller {
+		@GetMapping("/**")
+		String ok() {
+			return "ok";
+		}
+	}
+}

docs/src/test/java/org/springframework/security/docs/servlet/authentication/authorizationmanagerfactory/ListAuthoritiesEverywhereConfiguration.java

@@ -0,0 +1,54 @@
+package org.springframework.security.docs.servlet.authentication.authorizationmanagerfactory;
+
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.security.config.Customizer;
+import org.springframework.security.config.annotation.web.builders.HttpSecurity;
+import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
+import org.springframework.security.core.userdetails.User;
+import org.springframework.security.core.userdetails.UserDetailsService;
+import org.springframework.security.provisioning.InMemoryUserDetailsManager;
+import org.springframework.security.web.SecurityFilterChain;
+import org.springframework.security.web.authentication.ott.OneTimeTokenGenerationSuccessHandler;
+import org.springframework.security.web.authentication.ott.RedirectOneTimeTokenGenerationSuccessHandler;
+
+import static org.springframework.security.authorization.AuthorityAuthorizationManager.hasAuthority;
+import static org.springframework.security.authorization.AuthorityAuthorizationManager.hasRole;
+import static org.springframework.security.authorization.AuthorizationManagers.allOf;
+
+@EnableWebSecurity
+@Configuration(proxyBeanMethods = false)
+public class ListAuthoritiesEverywhereConfiguration {
+
+	// tag::httpSecurity[]
+	@Bean
+	public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
+		// @formatter:off
+		http
+			.authorizeHttpRequests((authorize) -> authorize
+				.requestMatchers("/admin/**").access(allOf(hasAuthority("FACTOR_PASSWORD"), hasAuthority("FACTOR_OTT"), hasRole("ADMIN"))) // <1>
+				.anyRequest().access(allOf(hasAuthority("FACTOR_PASSWORD"), hasAuthority("FACTOR_OTT")))
+			)
+			.formLogin(Customizer.withDefaults())
+			.oneTimeTokenLogin(Customizer.withDefaults());
+		// @formatter:on
+		return http.build();
+	}
+	// end::httpSecurity[]
+
+	@Bean
+	UserDetailsService userDetailsService() {
+		return new InMemoryUserDetailsManager(
+				User.withDefaultPasswordEncoder()
+						.username("user")
+						.password("password")
+						.authorities("app")
+						.build()
+		);
+	}
+
+	@Bean
+	OneTimeTokenGenerationSuccessHandler tokenGenerationSuccessHandler() {
+		return new RedirectOneTimeTokenGenerationSuccessHandler("/ott/sent");
+	}
+}

docs/src/test/java/org/springframework/security/docs/servlet/authentication/authorizationmanagerfactory/UseAuthorizationManagerFactoryConfiguration.java

@@ -0,0 +1,60 @@
+package org.springframework.security.docs.servlet.authentication.authorizationmanagerfactory;
+
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.security.authorization.AuthorizationManagerFactory;
+import org.springframework.security.authorization.DefaultAuthorizationManagerFactory;
+import org.springframework.security.config.Customizer;
+import org.springframework.security.config.annotation.web.builders.HttpSecurity;
+import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
+import org.springframework.security.core.userdetails.User;
+import org.springframework.security.core.userdetails.UserDetailsService;
+import org.springframework.security.provisioning.InMemoryUserDetailsManager;
+import org.springframework.security.web.SecurityFilterChain;
+import org.springframework.security.web.authentication.ott.OneTimeTokenGenerationSuccessHandler;
+import org.springframework.security.web.authentication.ott.RedirectOneTimeTokenGenerationSuccessHandler;
+
+@EnableWebSecurity
+@Configuration(proxyBeanMethods = false)
+class UseAuthorizationManagerFactoryConfiguration {
+
+	// tag::httpSecurity[]
+	@Bean
+	SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
+		// @formatter:off
+		http
+			.authorizeHttpRequests((authorize) -> authorize
+				.requestMatchers("/admin/**").hasRole("ADMIN")
+				.anyRequest().authenticated()
+			)
+			.formLogin(Customizer.withDefaults())
+			.oneTimeTokenLogin(Customizer.withDefaults());
+		// @formatter:on
+		return http.build();
+	}
+	// end::httpSecurity[]
+
+	// tag::authorizationManagerFactoryBean[]
+	@Bean
+	AuthorizationManagerFactory<Object> authz() {
+		return DefaultAuthorizationManagerFactory.builder()
+				.requireAdditionalAuthorities("FACTOR_PASSWORD", "FACTOR_OTT").build();
+	}
+	// end::authorizationManagerFactoryBean[]
+
+	@Bean
+	UserDetailsService userDetailsService() {
+		return new InMemoryUserDetailsManager(
+				User.withDefaultPasswordEncoder()
+						.username("user")
+						.password("password")
+						.authorities("app")
+						.build()
+		);
+	}
+
+	@Bean
+	OneTimeTokenGenerationSuccessHandler tokenGenerationSuccessHandler() {
+		return new RedirectOneTimeTokenGenerationSuccessHandler("/ott/sent");
+	}
+}