Document Authentication.Builder

The commit documents the new Authentication Builder interface
and its usage in the security filter chain.

Closes gh-17861
Closes gh-17862

docs/src/test/java/org/springframework/security/docs/servlet/authentication/servletauthenticationauthentication/CopyAuthoritiesTests.java

@@ -0,0 +1,41 @@
+package org.springframework.security.docs.servlet.authentication.servletauthenticationauthentication;
+
+import org.junit.jupiter.api.Test;
+
+import org.springframework.security.authentication.AuthenticationManager;
+import org.springframework.security.authentication.SecurityAssertions;
+import org.springframework.security.authentication.TestingAuthenticationToken;
+import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
+import org.springframework.security.authentication.ott.OneTimeTokenAuthentication;
+import org.springframework.security.core.Authentication;
+import org.springframework.security.core.authority.AuthorityUtils;
+import org.springframework.security.core.context.SecurityContextHolder;
+
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.BDDMockito.given;
+import static org.mockito.Mockito.mock;
+
+public class CopyAuthoritiesTests {
+	@Test
+	void toBuilderWhenApplyThenCopies() {
+		UsernamePasswordAuthenticationToken previous = new UsernamePasswordAuthenticationToken("alice", "pass",
+				AuthorityUtils.createAuthorityList("FACTOR_PASSWORD"));
+		SecurityContextHolder.getContext().setAuthentication(previous);
+		Authentication latest = new OneTimeTokenAuthentication("bob",
+				AuthorityUtils.createAuthorityList("FACTOR_OTT"));
+		AuthenticationManager authenticationManager = mock(AuthenticationManager.class);
+		given(authenticationManager.authenticate(any())).willReturn(latest);
+		Authentication authenticationRequest = new TestingAuthenticationToken("user", "pass");
+		// tag::springSecurity[]
+		Authentication lastestResult = authenticationManager.authenticate(authenticationRequest);
+		Authentication previousResult = SecurityContextHolder.getContext().getAuthentication();
+		if (previousResult != null && previousResult.isAuthenticated()) {
+			lastestResult = lastestResult.toBuilder()
+					.authorities((a) -> a.addAll(previous.getAuthorities()))
+					.build();
+		}
+		// end::springSecurity[]
+		SecurityAssertions.assertThat(lastestResult).hasAuthorities("FACTOR_PASSWORD", "FACTOR_OTT");
+		SecurityContextHolder.clearContext();
+	}
+}

docs/src/test/kotlin/org/springframework/security/kt/docs/servlet/authentication/servletauthenticationauthentication/CopyAuthoritiesTests.kt

@@ -0,0 +1,39 @@
+package org.springframework.security.kt.docs.servlet.authentication.servletauthenticationauthentication
+
+import org.junit.jupiter.api.Test
+import org.mockito.ArgumentMatchers
+import org.mockito.BDDMockito
+import org.mockito.Mockito
+import org.springframework.security.authentication.AuthenticationManager
+import org.springframework.security.authentication.SecurityAssertions
+import org.springframework.security.authentication.TestingAuthenticationToken
+import org.springframework.security.authentication.UsernamePasswordAuthenticationToken
+import org.springframework.security.authentication.ott.OneTimeTokenAuthentication
+import org.springframework.security.core.Authentication
+import org.springframework.security.core.authority.AuthorityUtils
+import org.springframework.security.core.context.SecurityContextHolder
+
+class CopyAuthoritiesTests {
+    @Test
+    fun toBuilderWhenApplyThenCopies() {
+        val previous: Authentication = UsernamePasswordAuthenticationToken("alice", "pass",
+            AuthorityUtils.createAuthorityList("FACTOR_PASSWORD"))
+        SecurityContextHolder.getContext().authentication = previous
+        var latest: Authentication = OneTimeTokenAuthentication("bob",
+            AuthorityUtils.createAuthorityList("FACTOR_OTT"))
+        val authenticationManager: AuthenticationManager = Mockito.mock(AuthenticationManager::class.java)
+        BDDMockito.given(authenticationManager.authenticate(ArgumentMatchers.any())).willReturn(latest)
+        val authenticationRequest: Authentication = TestingAuthenticationToken("user", "pass")
+        // tag::springSecurity[]
+        var latestResult: Authentication = authenticationManager.authenticate(authenticationRequest)
+        val previousResult = SecurityContextHolder.getContext().authentication;
+        if (previousResult?.isAuthenticated == true) {
+            latestResult = latestResult.toBuilder().authorities { a ->
+                a.addAll(previousResult.authorities)
+            }.build()
+        }
+        // end::springSecurity[]
+        SecurityAssertions.assertThat(latestResult).hasAuthorities("FACTOR_PASSWORD", "FACTOR_OTT")
+        SecurityContextHolder.clearContext()
+    }
+}