Polish OAuth 2.0 Authentication Builders

Issue gh-17861

Author: jzheaux

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

@@ -101,7 +101,7 @@ public Builder<?> toBuilder() {
 	}
 
 	/**
-	 * A builder preserving the concrete {@link Authentication} type
+	 * A builder of {@link OAuth2AuthenticationToken} instances
 	 *
 	 * @since 7.0
 	 */
@@ -124,6 +124,14 @@ public B principal(@Nullable Object principal) {
 			return (B) this;
 		}
 
+		/**
+		 * Use this
+		 * {@link org.springframework.security.oauth2.client.registration.ClientRegistration}
+		 * {@code registrationId}.
+		 * @param authorizedClientRegistrationId the registration id to use
+		 * @return the {@link Builder} for further configurations
+		 * @see OAuth2AuthenticationToken#getAuthorizedClientRegistrationId
+		 */
 		public B authorizedClientRegistrationId(String authorizedClientRegistrationId) {
 			this.authorizedClientRegistrationId = authorizedClientRegistrationId;
 			return (B) this;

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

@@ -118,8 +118,9 @@ public final T getToken() {
 	public abstract Map<String, Object> getTokenAttributes();
 
 	/**
-	 * A builder preserving the concrete {@link Authentication} type
+	 * A builder for {@link AbstractOAuth2TokenAuthenticationToken} implementations
 	 *
+	 * @param <B>
 	 * @since 7.0
 	 */
 	public abstract static class AbstractOAuth2TokenAuthenticationBuilder<T extends OAuth2Token, B extends AbstractOAuth2TokenAuthenticationBuilder<T, B>>
@@ -152,8 +153,13 @@ public B credentials(@Nullable Object credentials) {
 			return (B) this;
 		}
 
+		/**
+		 * The OAuth 2.0 Token to use
+		 * @param token the token to use
+		 * @return the {@link Builder} for further configurations
+		 */
 		public B token(T token) {
-			Assert.notNull(token, "credentials cannot be null");
+			Assert.notNull(token, "token cannot be null");
 			this.token = token;
 			return (B) this;
 		}

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

@@ -89,6 +89,11 @@ protected Builder(BearerTokenAuthentication token) {
 			this.attributes = token.getTokenAttributes();
 		}
 
+		/**
+		 * Use this principal. Must be of type {@link OAuth2AuthenticatedPrincipal}
+		 * @param principal the principal to use
+		 * @return the {@link Builder} for further configurations
+		 */
 		@Override
 		public B principal(@Nullable Object principal) {
 			Assert.isInstanceOf(OAuth2AuthenticatedPrincipal.class, principal,
@@ -97,13 +102,33 @@ public B principal(@Nullable Object principal) {
 			return super.principal(principal);
 		}
 
+		/**
+		 * A synonym for {@link #token(OAuth2AccessToken)}
+		 * @param token the token to use
+		 * @return the {@link Builder} for further configurations
+		 */
+		@Override
+		public B credentials(@Nullable Object token) {
+			Assert.isInstanceOf(OAuth2AccessToken.class, token, "token must be of type OAuth2AccessToken");
+			return token((OAuth2AccessToken) token);
+		}
+
+		/**
+		 * Use this token. Must have a {@link OAuth2AccessToken#getTokenType()} as
+		 * {@link OAuth2AccessToken.TokenType#BEARER}.
+		 * @param token the token to use
+		 * @return the {@link Builder} for further configurations
+		 */
 		@Override
 		public B token(OAuth2AccessToken token) {
-			Assert.isTrue(token.getTokenType() == OAuth2AccessToken.TokenType.BEARER,
-					"credentials must be a bearer token");
+			Assert.isTrue(token.getTokenType() == OAuth2AccessToken.TokenType.BEARER, "token must be a bearer token");
+			super.credentials(token);
 			return super.token(token);
 		}
 
+		/**
+		 * {@inheritDoc}
+		 */
 		@Override
 		public BearerTokenAuthentication build() {
 			return new BearerTokenAuthentication(this);

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

@@ -19,10 +19,13 @@
 import java.util.Collection;
 import java.util.Map;
 
+import org.jspecify.annotations.Nullable;
+
 import org.springframework.security.core.Authentication;
 import org.springframework.security.core.GrantedAuthority;
 import org.springframework.security.core.Transient;
 import org.springframework.security.oauth2.jwt.Jwt;
+import org.springframework.util.Assert;
 
 /**
  * An implementation of an {@link AbstractOAuth2TokenAuthenticationToken} representing a
@@ -96,9 +99,10 @@ public Builder<?> toBuilder() {
 	}
 
 	/**
-	 * A builder preserving the concrete {@link Authentication} type
+	 * A builder for {@link JwtAuthenticationToken} instances
 	 *
 	 * @since 7.0
+	 * @see Authentication.Builder
 	 */
 	public static class Builder<B extends Builder<B>> extends AbstractOAuth2TokenAuthenticationBuilder<Jwt, B> {
 
@@ -109,6 +113,44 @@ protected Builder(JwtAuthenticationToken token) {
 			this.name = token.getName();
 		}
 
+		/**
+		 * A synonym for {@link #token(Jwt)}
+		 * @return the {@link Builder} for further configurations
+		 */
+		@Override
+		public B principal(@Nullable Object principal) {
+			Assert.isInstanceOf(Jwt.class, principal, "principal must be of type Jwt");
+			return token((Jwt) principal);
+		}
+
+		/**
+		 * A synonym for {@link #token(Jwt)}
+		 * @return the {@link Builder} for further configurations
+		 */
+		@Override
+		public B credentials(@Nullable Object credentials) {
+			Assert.isInstanceOf(Jwt.class, credentials, "credentials must be of type Jwt");
+			return token((Jwt) credentials);
+		}
+
+		/**
+		 * Use this {@code token} as the token, principal, and credentials. Also sets the
+		 * {@code name} to {@link Jwt#getSubject}.
+		 * @param token the token to use
+		 * @return the {@link Builder} for further configurations
+		 */
+		@Override
+		public B token(Jwt token) {
+			super.principal(token);
+			super.credentials(token);
+			return super.token(token).name(token.getSubject());
+		}
+
+		/**
+		 * The name to use.
+		 * @param name the name to use
+		 * @return the {@link Builder} for further configurations
+		 */
 		public B name(String name) {
 			this.name = name;
 			return (B) this;