Support Updating Authorities

There are a number of scenarios where it's desireable to update the
authorities in an authentication after identity has already been established.

For example, if a second factor is required or if temporary
authorization is needed for a given page, these likely won't
update the principal; they simply need to add more authorities
to the existing authentication.

Author: jzheaux

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

@@ -22,6 +22,7 @@
 import org.apereo.cas.client.validation.Assertion;
 
 import org.springframework.security.authentication.AbstractAuthenticationToken;
+import org.springframework.security.core.AuthenticationResult;
 import org.springframework.security.core.GrantedAuthority;
 import org.springframework.security.core.userdetails.UserDetails;
 import org.springframework.util.Assert;
@@ -33,7 +34,7 @@
  * @author Ben Alex
  * @author Scott Battaglia
  */
-public class CasAuthenticationToken extends AbstractAuthenticationToken implements Serializable {
+public class CasAuthenticationToken extends AbstractAuthenticationToken implements Serializable, AuthenticationResult {
 
 	private static final long serialVersionUID = 620L;
 
@@ -104,6 +105,12 @@ private CasAuthenticationToken(final Integer keyHash, final Object principal, fi
 		setAuthenticated(true);
 	}
 
+	@Override
+	public CasAuthenticationToken withGrantedAuthorities(Collection<GrantedAuthority> authorities) {
+		return new CasAuthenticationToken(this.keyHash, getPrincipal(), getCredentials(), authorities, this.userDetails,
+				this.assertion);
+	}
+
 	private static Integer extractKeyHash(String key) {
 		Assert.hasLength(key, "key cannot be null or empty");
 		return key.hashCode();

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

@@ -18,7 +18,9 @@
 
 import java.util.Collection;
 
+import org.springframework.security.core.AuthenticationResult;
 import org.springframework.security.core.GrantedAuthority;
+import org.springframework.util.Assert;
 
 /**
  * Represents a remembered <code>Authentication</code>.
@@ -29,7 +31,7 @@
  * @author Ben Alex
  * @author Luke Taylor
  */
-public class RememberMeAuthenticationToken extends AbstractAuthenticationToken {
+public class RememberMeAuthenticationToken extends AbstractAuthenticationToken implements AuthenticationResult {
 
 	private static final long serialVersionUID = 620L;
 
@@ -70,6 +72,12 @@ private RememberMeAuthenticationToken(Integer keyHash, Object principal,
 		setAuthenticated(true);
 	}
 
+	@Override
+	public RememberMeAuthenticationToken withGrantedAuthorities(Collection<GrantedAuthority> authorities) {
+		Assert.isTrue(isAuthenticated(), "cannot grant authorities to unauthenticated tokens");
+		return new RememberMeAuthenticationToken(this.keyHash, getPrincipal(), authorities);
+	}
+
 	/**
 	 * Always returns an empty <code>String</code>
 	 * @return an empty String

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

@@ -19,8 +19,10 @@
 import java.util.Collection;
 import java.util.List;
 
+import org.springframework.security.core.AuthenticationResult;
 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
@@ -30,7 +32,7 @@
  *
  * @author Ben Alex
  */
-public class TestingAuthenticationToken extends AbstractAuthenticationToken {
+public class TestingAuthenticationToken extends AbstractAuthenticationToken implements AuthenticationResult {
 
 	private static final long serialVersionUID = 1L;
 
@@ -61,6 +63,12 @@ public TestingAuthenticationToken(Object principal, Object credentials,
 		setAuthenticated(true);
 	}
 
+	@Override
+	public TestingAuthenticationToken withGrantedAuthorities(Collection<GrantedAuthority> authorities) {
+		Assert.isTrue(isAuthenticated(), "cannot grant authorities to unauthenticated tokens");
+		return new TestingAuthenticationToken(getPrincipal(), this.credentials, authorities);
+	}
+
 	@Override
 	public Object getCredentials() {
 		return this.credentials;

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

@@ -20,6 +20,7 @@
 
 import org.jspecify.annotations.Nullable;
 
+import org.springframework.security.core.AuthenticationResult;
 import org.springframework.security.core.GrantedAuthority;
 import org.springframework.util.Assert;
 
@@ -35,7 +36,7 @@
  * @author Ben Alex
  * @author Norbert Nowak
  */
-public class UsernamePasswordAuthenticationToken extends AbstractAuthenticationToken {
+public class UsernamePasswordAuthenticationToken extends AbstractAuthenticationToken implements AuthenticationResult {
 
 	private static final long serialVersionUID = 620L;
 
@@ -100,6 +101,12 @@ public static UsernamePasswordAuthenticationToken authenticated(Object principal
 		return new UsernamePasswordAuthenticationToken(principal, credentials, authorities);
 	}
 
+	@Override
+	public UsernamePasswordAuthenticationToken withGrantedAuthorities(Collection<GrantedAuthority> authorities) {
+		Assert.isTrue(isAuthenticated(), "cannot grant authorities to unauthenticated tokens");
+		return new UsernamePasswordAuthenticationToken(getPrincipal(), getCredentials(), authorities);
+	}
+
 	@Override
 	public @Nullable Object getCredentials() {
 		return this.credentials;

core/src/main/java/org/springframework/security/authentication/jaas/JaasAuthenticationToken.java

@@ -16,6 +16,8 @@
 
 package org.springframework.security.authentication.jaas;
 
+import java.util.ArrayList;
+import java.util.Collection;
 import java.util.List;
 
 import javax.security.auth.login.LoginContext;
@@ -24,6 +26,7 @@
 
 import org.springframework.security.authentication.UsernamePasswordAuthenticationToken;
 import org.springframework.security.core.GrantedAuthority;
+import org.springframework.util.Assert;
 
 /**
  * UsernamePasswordAuthenticationToken extension to carry the Jaas LoginContext that the
@@ -52,4 +55,11 @@ public LoginContext getLoginContext() {
 		return this.loginContext;
 	}
 
+	@Override
+	public JaasAuthenticationToken withGrantedAuthorities(Collection<GrantedAuthority> authorities) {
+		Assert.isTrue(isAuthenticated(), "cannot grant authorities to unauthenticated tokens");
+		return new JaasAuthenticationToken(getPrincipal(), getCredentials(), new ArrayList<>(authorities),
+				this.loginContext);
+	}
+
 }

core/src/main/java/org/springframework/security/authentication/ott/OneTimeTokenAuthenticationToken.java

@@ -19,19 +19,22 @@
 import java.io.Serial;
 import java.util.Collection;
 import java.util.Collections;
+import java.util.Objects;
 
 import org.jspecify.annotations.Nullable;
 
 import org.springframework.security.authentication.AbstractAuthenticationToken;
+import org.springframework.security.core.AuthenticationResult;
 import org.springframework.security.core.GrantedAuthority;
+import org.springframework.util.Assert;
 
 /**
  * Represents a One-Time Token authentication that can be authenticated or not.
  *
  * @author Marcus da Coregio
  * @since 6.4
  */
-public class OneTimeTokenAuthenticationToken extends AbstractAuthenticationToken {
+public class OneTimeTokenAuthenticationToken extends AbstractAuthenticationToken implements AuthenticationResult {
 
 	@Serial
 	private static final long serialVersionUID = -8691636031126328365L;
@@ -56,6 +59,13 @@ public OneTimeTokenAuthenticationToken(Object principal, Collection<? extends Gr
 		setAuthenticated(true);
 	}
 
+	@Override
+	public OneTimeTokenAuthenticationToken withGrantedAuthorities(Collection<GrantedAuthority> authorities) {
+		Assert.isTrue(isAuthenticated(), "cannot grant authorities to unauthenticated tokens");
+		Object principal = Objects.requireNonNull(this.principal);
+		return OneTimeTokenAuthenticationToken.authenticated(principal, authorities);
+	}
+
 	/**
 	 * Creates an unauthenticated token
 	 * @param tokenValue the one-time token value

core/src/main/java/org/springframework/security/core/AuthenticationResult.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.core;
+
+import java.io.Serial;
+import java.util.Collection;
+import java.util.HashSet;
+import java.util.function.Consumer;
+
+import org.jspecify.annotations.NullMarked;
+
+@NullMarked
+public interface AuthenticationResult extends Authentication {
+
+	@Serial
+	long serialVersionUID = -525010730472051621L;
+
+	default AuthenticationResult withGrantedAuthorities(Consumer<Collection<GrantedAuthority>> consumer) {
+		Collection<GrantedAuthority> existing = new HashSet<>(getAuthorities());
+		consumer.accept(existing);
+		return withGrantedAuthorities(existing);
+	}
+
+	AuthenticationResult withGrantedAuthorities(Collection<GrantedAuthority> authorities);
+
+	default boolean isAuthenticated() {
+		return true;
+	}
+
+}

oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/authentication/OAuth2AuthenticationToken.java

@@ -20,6 +20,7 @@
 
 import org.springframework.security.authentication.AbstractAuthenticationToken;
 import org.springframework.security.core.Authentication;
+import org.springframework.security.core.AuthenticationResult;
 import org.springframework.security.core.GrantedAuthority;
 import org.springframework.security.oauth2.client.OAuth2AuthorizedClient;
 import org.springframework.security.oauth2.core.user.OAuth2User;
@@ -40,7 +41,7 @@
  * @see OAuth2User
  * @see OAuth2AuthorizedClient
  */
-public class OAuth2AuthenticationToken extends AbstractAuthenticationToken {
+public class OAuth2AuthenticationToken extends AbstractAuthenticationToken implements AuthenticationResult {
 
 	private static final long serialVersionUID = 620L;
 
@@ -65,6 +66,11 @@ public OAuth2AuthenticationToken(OAuth2User principal, Collection<? extends Gran
 		this.setAuthenticated(true);
 	}
 
+	@Override
+	public OAuth2AuthenticationToken withGrantedAuthorities(Collection<GrantedAuthority> authorities) {
+		return new OAuth2AuthenticationToken(getPrincipal(), authorities, this.authorizedClientRegistrationId);
+	}
+
 	@Override
 	public OAuth2User getPrincipal() {
 		return this.principal;

oauth2/oauth2-resource-server/src/main/java/org/springframework/security/oauth2/server/resource/authentication/BearerTokenAuthentication.java

@@ -21,6 +21,7 @@
 import java.util.LinkedHashMap;
 import java.util.Map;
 
+import org.springframework.security.core.AuthenticationResult;
 import org.springframework.security.core.GrantedAuthority;
 import org.springframework.security.core.Transient;
 import org.springframework.security.oauth2.core.OAuth2AccessToken;
@@ -35,7 +36,8 @@
  * @since 5.2
  */
 @Transient
-public class BearerTokenAuthentication extends AbstractOAuth2TokenAuthenticationToken<OAuth2AccessToken> {
+public class BearerTokenAuthentication extends AbstractOAuth2TokenAuthenticationToken<OAuth2AccessToken>
+		implements AuthenticationResult {
 
 	private static final long serialVersionUID = 620L;
 
@@ -56,6 +58,11 @@ public BearerTokenAuthentication(OAuth2AuthenticatedPrincipal principal, OAuth2A
 		setAuthenticated(true);
 	}
 
+	@Override
+	public BearerTokenAuthentication withGrantedAuthorities(Collection<GrantedAuthority> authorities) {
+		return new BearerTokenAuthentication((OAuth2AuthenticatedPrincipal) getPrincipal(), getToken(), authorities);
+	}
+
 	@Override
 	public Map<String, Object> getTokenAttributes() {
 		return this.attributes;

oauth2/oauth2-resource-server/src/main/java/org/springframework/security/oauth2/server/resource/authentication/JwtAuthenticationToken.java

@@ -19,6 +19,7 @@
 import java.util.Collection;
 import java.util.Map;
 
+import org.springframework.security.core.AuthenticationResult;
 import org.springframework.security.core.GrantedAuthority;
 import org.springframework.security.core.Transient;
 import org.springframework.security.oauth2.jwt.Jwt;
@@ -33,7 +34,8 @@
  * @see Jwt
  */
 @Transient
-public class JwtAuthenticationToken extends AbstractOAuth2TokenAuthenticationToken<Jwt> {
+public class JwtAuthenticationToken extends AbstractOAuth2TokenAuthenticationToken<Jwt>
+		implements AuthenticationResult {
 
 	private static final long serialVersionUID = 620L;
 
@@ -71,6 +73,11 @@ public JwtAuthenticationToken(Jwt jwt, Collection<? extends GrantedAuthority> au
 		this.name = name;
 	}
 
+	@Override
+	public JwtAuthenticationToken withGrantedAuthorities(Collection<GrantedAuthority> authorities) {
+		return new JwtAuthenticationToken(getToken(), authorities, this.name);
+	}
+
 	@Override
 	public Map<String, Object> getTokenAttributes() {
 		return this.getToken().getClaims();