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.

Author: jzheaux

cas/src/main/java/org/springframework/security/cas/authentication/CasAuthenticationToken.java

@@ -20,8 +20,10 @@
 import java.util.Collection;
 
 import org.apereo.cas.client.validation.Assertion;
+import org.jspecify.annotations.NonNull;
 
 import org.springframework.security.authentication.AbstractAuthenticationToken;
+import org.springframework.security.core.Authentication;
 import org.springframework.security.core.GrantedAuthority;
 import org.springframework.security.core.userdetails.UserDetails;
 import org.springframework.util.Assert;
@@ -153,6 +155,11 @@ public UserDetails getUserDetails() {
 		return this.userDetails;
 	}
 
+	@Override
+	public Builder toBuilder() {
+		return new Builder().apply(this);
+	}
+
 	@Override
 	public String toString() {
 		StringBuilder sb = new StringBuilder();
@@ -162,4 +169,66 @@ public String toString() {
 		return (sb.toString());
 	}
 
+	/**
+	 * A builder preserving the concrete {@link Authentication} type
+	 *
+	 * @since 7.0
+	 */
+	public static final class Builder extends AbstractAuthenticationBuilder<@NonNull CasAuthenticationToken, Builder> {
+
+		private Integer keyHash;
+
+		private Object principal;
+
+		private Object credentials;
+
+		private UserDetails userDetails;
+
+		private Assertion assertion;
+
+		private Builder() {
+
+		}
+
+		public Builder apply(CasAuthenticationToken authentication) {
+			return super.apply(authentication).keyHash(authentication.keyHash)
+				.principal(authentication.principal)
+				.credentials(authentication.credentials)
+				.userDetails(authentication.userDetails)
+				.assertion(authentication.assertion);
+		}
+
+		public Builder keyHash(Integer keyHash) {
+			this.keyHash = keyHash;
+			return this;
+		}
+
+		public Builder principal(Object principal) {
+			this.principal = principal;
+			return this;
+		}
+
+		public Builder credentials(Object credentials) {
+			this.credentials = credentials;
+			return this;
+		}
+
+		public Builder userDetails(UserDetails userDetails) {
+			this.userDetails = userDetails;
+			return this;
+		}
+
+		public Builder assertion(Assertion assertion) {
+			this.assertion = assertion;
+			return this;
+		}
+
+		@Override
+		protected @NonNull CasAuthenticationToken build(Collection<GrantedAuthority> authorities) {
+			return new CasAuthenticationToken(this.keyHash, this.principal, this.credentials, authorities,
+					this.userDetails, this.assertion);
+		}
+
+	}
+
 }

cas/src/test/java/org/springframework/security/cas/authentication/CasAuthenticationTokenTests.java

@@ -18,6 +18,7 @@
 
 import java.util.Collections;
 import java.util.List;
+import java.util.Set;
 
 import org.apereo.cas.client.validation.Assertion;
 import org.apereo.cas.client.validation.AssertionImpl;
@@ -26,6 +27,7 @@
 import org.springframework.security.core.GrantedAuthority;
 import org.springframework.security.core.authority.AuthorityUtils;
 import org.springframework.security.core.authority.SimpleGrantedAuthority;
+import org.springframework.security.core.userdetails.PasswordEncodedUser;
 import org.springframework.security.core.userdetails.User;
 import org.springframework.security.core.userdetails.UserDetails;
 
@@ -155,4 +157,22 @@ public void testToString() {
 		assertThat(result.lastIndexOf("Credentials (Service/Proxy Ticket):") != -1).isTrue();
 	}
 
+	@Test
+	public void toBuilderWhenApplyThenCopies() {
+		Assertion assertionOne = new AssertionImpl("test");
+		CasAuthenticationToken factorOne = new CasAuthenticationToken("key", "alice", "pass",
+				AuthorityUtils.createAuthorityList("FACTOR_ONE"), PasswordEncodedUser.user(), assertionOne);
+		Assertion assertionTwo = new AssertionImpl("test");
+		CasAuthenticationToken factorTwo = new CasAuthenticationToken("yek", "bob", "ssap",
+				AuthorityUtils.createAuthorityList("FACTOR_TWO"), PasswordEncodedUser.admin(), assertionTwo);
+		CasAuthenticationToken authentication = factorOne.toBuilder().apply(factorTwo).build();
+		Set<String> authorities = AuthorityUtils.authorityListToSet(authentication.getAuthorities());
+		assertThat(authentication.getKeyHash()).isEqualTo(factorTwo.getKeyHash());
+		assertThat(authentication.getPrincipal()).isEqualTo(factorTwo.getPrincipal());
+		assertThat(authentication.getCredentials()).isEqualTo(factorTwo.getCredentials());
+		assertThat(authentication.getUserDetails()).isEqualTo(factorTwo.getUserDetails());
+		assertThat(authentication.getAssertion()).isEqualTo(factorTwo.getAssertion());
+		assertThat(authorities).containsExactlyInAnyOrder("FACTOR_ONE", "FACTOR_TWO");
+	}
+
 }

core/src/main/java/org/springframework/security/authentication/AbstractAuthenticationToken.java

@@ -20,6 +20,8 @@
 import java.util.ArrayList;
 import java.util.Collection;
 import java.util.Collections;
+import java.util.HashSet;
+import java.util.function.Consumer;
 
 import org.jspecify.annotations.Nullable;
 
@@ -185,4 +187,36 @@ public String toString() {
 		return sb.toString();
 	}
 
+	protected abstract static class AbstractAuthenticationBuilder<A extends Authentication, B extends AbstractAuthenticationBuilder<A, B>>
+			implements Builder<A, B> {
+
+		private final Collection<GrantedAuthority> authorities = new HashSet<>();
+
+		protected AbstractAuthenticationBuilder() {
+
+		}
+
+		@Override
+		public B authorities(Consumer<Collection<GrantedAuthority>> authorities) {
+			authorities.accept(this.authorities);
+			return (B) this;
+		}
+
+		@Override
+		public A build() {
+			return build(this.authorities);
+		}
+
+		@Override
+		public B apply(Authentication token) {
+			Assert.isTrue(token.isAuthenticated(), "cannot mutate an unauthenticated token");
+			Assert.notNull(token.getPrincipal(), "principal cannot be null");
+			this.authorities.addAll(token.getAuthorities());
+			return (B) this;
+		}
+
+		protected abstract A build(Collection<GrantedAuthority> authorities);
+
+	}
+
 }

core/src/main/java/org/springframework/security/authentication/RememberMeAuthenticationToken.java

@@ -18,7 +18,11 @@
 
 import java.util.Collection;
 
+import org.jspecify.annotations.Nullable;
+
+import org.springframework.security.core.Authentication;
 import org.springframework.security.core.GrantedAuthority;
+import org.springframework.util.Assert;
 
 /**
  * Represents a remembered <code>Authentication</code>.
@@ -88,6 +92,11 @@ public Object getPrincipal() {
 		return this.principal;
 	}
 
+	@Override
+	public Builder toBuilder() {
+		return new Builder().apply(this);
+	}
+
 	@Override
 	public boolean equals(Object obj) {
 		if (!super.equals(obj)) {
@@ -106,4 +115,42 @@ public int hashCode() {
 		return result;
 	}
 
+	/**
+	 * A builder preserving the concrete {@link Authentication} type
+	 *
+	 * @since 7.0
+	 */
+	public static final class Builder extends AbstractAuthenticationBuilder<RememberMeAuthenticationToken, Builder> {
+
+		private @Nullable Integer keyHash;
+
+		private @Nullable Object principal;
+
+		private Builder() {
+
+		}
+
+		public Builder apply(RememberMeAuthenticationToken token) {
+			return super.apply(token).keyHash(token.getKeyHash()).principal(token.getPrincipal());
+		}
+
+		public Builder principal(Object principal) {
+			this.principal = principal;
+			return this;
+		}
+
+		public Builder keyHash(int keyHash) {
+			this.keyHash = keyHash;
+			return this;
+		}
+
+		@Override
+		protected RememberMeAuthenticationToken build(Collection<GrantedAuthority> authorities) {
+			Assert.notNull(this.keyHash, "keyHash cannot be null");
+			Assert.notNull(this.principal, "principal cannot be null");
+			return new RememberMeAuthenticationToken(this.keyHash, this.principal, authorities);
+		}
+
+	}
+
 }

core/src/main/java/org/springframework/security/authentication/TestingAuthenticationToken.java

@@ -19,8 +19,12 @@
 import java.util.Collection;
 import java.util.List;
 
+import org.jspecify.annotations.Nullable;
+
+import org.springframework.security.core.Authentication;
 import org.springframework.security.core.GrantedAuthority;
 import org.springframework.security.core.authority.AuthorityUtils;
+import org.springframework.util.Assert;
 
 /**
  * An {@link org.springframework.security.core.Authentication} implementation that is
@@ -71,4 +75,48 @@ public Object getPrincipal() {
 		return this.principal;
 	}
 
+	@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<TestingAuthenticationToken, Builder> {
+
+		private @Nullable Object principal;
+
+		private @Nullable Object credentials;
+
+		private Builder() {
+
+		}
+
+		public Builder apply(TestingAuthenticationToken authentication) {
+			return super.apply(authentication).principal(authentication.getPrincipal())
+				.credentials(authentication.getCredentials());
+		}
+
+		public Builder principal(Object principal) {
+			this.principal = principal;
+			return this;
+		}
+
+		public Builder credentials(Object credentials) {
+			this.credentials = credentials;
+			return this;
+		}
+
+		@Override
+		protected TestingAuthenticationToken build(Collection<GrantedAuthority> authorities) {
+			Assert.notNull(this.principal, "principal cannot be null");
+			Assert.notNull(this.credentials, "credentials cannot be null");
+			return new TestingAuthenticationToken(this.principal, this.credentials, authorities);
+		}
+
+	}
+
 }

core/src/main/java/org/springframework/security/authentication/UsernamePasswordAuthenticationToken.java

@@ -20,6 +20,7 @@
 
 import org.jspecify.annotations.Nullable;
 
+import org.springframework.security.core.Authentication;
 import org.springframework.security.core.GrantedAuthority;
 import org.springframework.util.Assert;
 
@@ -124,4 +125,47 @@ public void eraseCredentials() {
 		this.credentials = null;
 	}
 
+	@Override
+	public Builder<?, ?> toBuilder() {
+		return new Builder<>().apply(this);
+	}
+
+	/**
+	 * A builder preserving the concrete {@link Authentication} type
+	 *
+	 * @since 7.0
+	 */
+	public static class Builder<A extends UsernamePasswordAuthenticationToken, B extends Builder<A, B>>
+			extends AbstractAuthenticationBuilder<A, B> {
+
+		private @Nullable Object principal;
+
+		private @Nullable Object credentials;
+
+		protected Builder() {
+		}
+
+		public B apply(UsernamePasswordAuthenticationToken authentication) {
+			return super.apply(authentication).principal(authentication.getPrincipal())
+				.credentials(authentication.getCredentials());
+		}
+
+		public B principal(Object principal) {
+			this.principal = principal;
+			return (B) this;
+		}
+
+		public B credentials(@Nullable Object credentials) {
+			this.credentials = credentials;
+			return (B) this;
+		}
+
+		@Override
+		protected A build(Collection<GrantedAuthority> authorities) {
+			Assert.notNull(this.principal, "principal cannot be null");
+			return (A) new UsernamePasswordAuthenticationToken(this.principal, this.credentials, authorities);
+		}
+
+	}
+
 }