Add Authentication.Builder

This commit adds a new default method to Authentication
for the purposes of creating a Builder based on the current
authentication, allowing other authentications to be
applied to it as a composite.

It also adds Builders for each one of the authentication
result classes.

Issue gh-17861

saml2/saml2-service-provider/src/main/java/org/springframework/security/saml2/provider/service/authentication/Saml2AssertionAuthentication.java

@@ -19,6 +19,9 @@ package org.springframework.security.saml2.provider.service.authentication;
 import java.io.Serial;
 import java.util.Collection;
 
+import org.jspecify.annotations.NonNull;
+
+import org.springframework.security.core.Authentication;
 import org.springframework.security.core.GrantedAuthority;
 
 /**
@@ -62,4 +65,56 @@ public class Saml2AssertionAuthentication extends Saml2Authentication {
 		return this.relyingPartyRegistrationId;
 	}
 
+	@Override
+	public Builder toBuilder() {
+		return new Builder().apply(this);
+	}
+
+	/**
+	 * A builder preserving the concrete {@link Authentication} type
+	 *
+	 * @since 7.0
+	 */
+	public static final class Builder
+			extends AbstractAuthenticationBuilder<@NonNull Saml2AssertionAuthentication, @NonNull Builder> {
+
+		private Object principal;
+
+		private Saml2ResponseAssertionAccessor assertion;
+
+		private String relyingPartyRegistrationId;
+
+		private Builder() {
+
+		}
+
+		public Builder apply(Saml2AssertionAuthentication authentication) {
+			return super.apply(authentication).principal(authentication.getPrincipal())
+				.assertion(authentication.assertion)
+				.relyingPartyRegistrationId(authentication.relyingPartyRegistrationId);
+		}
+
+		public Builder principal(Object principal) {
+			this.principal = principal;
+			return this;
+		}
+
+		public Builder assertion(Saml2ResponseAssertionAccessor assertion) {
+			this.assertion = assertion;
+			return this;
+		}
+
+		public Builder relyingPartyRegistrationId(String relyingPartyRegistrationId) {
+			this.relyingPartyRegistrationId = relyingPartyRegistrationId;
+			return this;
+		}
+
+		@Override
+		protected Saml2AssertionAuthentication build(Collection<GrantedAuthority> authorities) {
+			return new Saml2AssertionAuthentication(this.principal, this.assertion, authorities,
+					this.relyingPartyRegistrationId);
+		}
+
+	}
+
 }

saml2/saml2-service-provider/src/test/java/org/springframework/security/saml2/provider/service/authentication/Saml2AssertionAuthenticationTests.java

@@ -0,0 +1,44 @@
+/*
+ * 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.saml2.provider.service.authentication;
+
+import java.util.Set;
+
+import org.junit.jupiter.api.Test;
+
+import org.springframework.security.core.authority.AuthorityUtils;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+class Saml2AssertionAuthenticationTests {
+
+	@Test
+	void toBuilderWhenApplyThenCopies() {
+		Saml2ResponseAssertion.Builder prototype = Saml2ResponseAssertion.withResponseValue("response");
+		Saml2AssertionAuthentication factorOne = new Saml2AssertionAuthentication("alice",
+				prototype.nameId("alice").build(), AuthorityUtils.createAuthorityList("FACTOR_ONE"), "alice");
+		Saml2AssertionAuthentication factorTwo = new Saml2AssertionAuthentication("bob",
+				prototype.nameId("alice").build(), AuthorityUtils.createAuthorityList("FACTOR_TWO"), "bob");
+		Saml2AssertionAuthentication result = factorOne.toBuilder().apply(factorTwo).build();
+		Set<String> authorities = AuthorityUtils.authorityListToSet(result.getAuthorities());
+		assertThat(result.getPrincipal()).isSameAs(factorTwo.getPrincipal());
+		assertThat(result.getCredentials()).isSameAs(factorTwo.getCredentials());
+		assertThat(result.getRelyingPartyRegistrationId()).isSameAs(factorTwo.getRelyingPartyRegistrationId());
+		assertThat(authorities).containsExactlyInAnyOrder("FACTOR_ONE", "FACTOR_TWO");
+	}
+
+}