Add SpEL support for nested username extraction in OAuth2

- Add usernameExpression property with SpEL evaluation support
- Auto-convert userNameAttributeName to SpEL for backward compatibility
- Use SimpleEvaluationContext for secure expression evaluation
- Pass evaluated username to OAuth2UserAuthority for gh-15012 compatibility
- Add Builder pattern to DefaultOAuth2User
- Add Builder pattern to OAuth2UserAuthority
- Add Builder pattern to OidcUserAuthority with inherance support
- Add Builder pattern to DefaultOidcUser with inherance support
- Support nested property access (e.g., "data.username")
- Add usernameExpression property to ClientRegistration documentation
- Update What's New section

Fixes gh-16390

Signed-off-by: yybmion <[email protected]>

Author: yybmion

docs/modules/ROOT/pages/reactive/oauth2/client/core.adoc

@@ -36,12 +36,13 @@ public final class ClientRegistration {
 			private String uri;	<14>
 			private AuthenticationMethod authenticationMethod;  <15>
 			private String userNameAttributeName;	<16>
+			private String usernameExpression;	<17>
 
 		}
 	}
 
 	public static final class ClientSettings {
-		private boolean requireProofKey; // <17>
+		private boolean requireProofKey; // <18>
 	}
 }
 ----
@@ -67,8 +68,9 @@ The name may be used in certain scenarios, such as when displaying the name of t
 <14> `(userInfoEndpoint)uri`: The UserInfo Endpoint URI used to access the claims/attributes of the authenticated end-user.
 <15> `(userInfoEndpoint)authenticationMethod`: The authentication method used when sending the access token to the UserInfo Endpoint.
 The supported values are *header*, *form* and *query*.
-<16> `userNameAttributeName`: The name of the attribute returned in the UserInfo Response that references the Name or Identifier of the end-user.
-<17> [[oauth2Client-client-registration-requireProofKey]]`requireProofKey`: If `true` or if `authorizationGrantType` is `none`, then PKCE will be enabled by default.
+<16> `userNameAttributeName`: The name of the attribute returned in the UserInfo Response that references the Name or Identifier of the end-user. *Deprecated* - use `usernameExpression` instead.
+<17> `usernameExpression`: A SpEL expression used to extract the username from the UserInfo Response. Supports accessing nested attributes (e.g., `"data.username"`) and complex expressions (e.g., `"preferred_username ?: email"`).
+<18> [[oauth2Client-client-registration-requireProofKey]]`requireProofKey`: If `true` or if `authorizationGrantType` is `none`, then PKCE will be enabled by default.
 
 A `ClientRegistration` can be initially configured using discovery of an OpenID Connect Provider's https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig[Configuration endpoint] or an Authorization Server's https://tools.ietf.org/html/rfc8414#section-3[Metadata endpoint].
 

docs/modules/ROOT/pages/servlet/oauth2/client/core.adoc

@@ -31,18 +31,19 @@ public final class ClientRegistration {
 		private UserInfoEndpoint userInfoEndpoint;
 		private String jwkSetUri;	<11>
 		private String issuerUri;	<12>
-        private Map<String, Object> configurationMetadata;  <13>
+		private Map<String, Object> configurationMetadata;	<13>
 
 		public class UserInfoEndpoint {
 			private String uri;	<14>
-            private AuthenticationMethod authenticationMethod;  <15>
+			private AuthenticationMethod authenticationMethod;	<15>
 			private String userNameAttributeName;	<16>
+			private String usernameExpression;	<17>
 
 		}
 	}
 
 	public static final class ClientSettings {
-		private boolean requireProofKey; // <17>
+		private boolean requireProofKey; // <18>
 	}
 }
 ----
@@ -68,8 +69,9 @@ This information is available only if the Spring Boot property `spring.security.
 <14> `(userInfoEndpoint)uri`: The UserInfo Endpoint URI used to access the claims and attributes of the authenticated end-user.
 <15> `(userInfoEndpoint)authenticationMethod`: The authentication method used when sending the access token to the UserInfo Endpoint.
 The supported values are *header*, *form*, and *query*.
-<16> `userNameAttributeName`: The name of the attribute returned in the UserInfo Response that references the Name or Identifier of the end-user.
-<17> [[oauth2Client-client-registration-requireProofKey]]`requireProofKey`: If `true` or if `authorizationGrantType` is `none`, then PKCE will be enabled by default.
+<16> `userNameAttributeName`: The name of the attribute returned in the UserInfo Response that references the Name or Identifier of the end-user. Deprecated - use usernameExpression instead.
+<17> `usernameExpression`: A SpEL expression used to extract the username from the UserInfo Response. Supports accessing nested attributes (e.g., "data.username") and complex expressions (e.g., "preferred_username ?: email").
+<18> [[oauth2Client-client-registration-requireProofKey]]`requireProofKey`: If `true` or if `authorizationGrantType` is `none`, then PKCE will be enabled by default.
 
 You can initially configure a `ClientRegistration` by using discovery of an OpenID Connect Provider's https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig[Configuration endpoint] or an Authorization Server's https://tools.ietf.org/html/rfc8414#section-3[Metadata endpoint].
 

docs/modules/ROOT/pages/whats-new.adoc

@@ -36,7 +36,7 @@ http.csrf((csrf) -> csrf.spa());
 * Removed `ApacheDsContainer` and related Apache DS support in favor of UnboundID
 
 == OAuth 2.0
-
+* OAuth2 Client now supports SpEL expressions for extracting usernames from nested UserInfo responses, eliminating the need for custom `OAuth2UserService` implementations in many cases. This is particularly useful for APIs like Twitter API v2 that return nested user data.
 * Removed support for password grant
 * Added OAuth2 Support for xref:features/integrations/rest/http-interface.adoc[HTTP Interface Integration]
 * Added support for custom `JwkSource` in `NimbusJwtDecoder`, allowing usage of Nimbus's `JwkSourceBuilder` API

oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/jackson2/DefaultOidcUserMixin.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2020 the original author or authors.
+ * Copyright 2002-2025 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.

oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/registration/ClientRegistration.java

@@ -47,6 +47,7 @@
  *
  * @author Joe Grandja
  * @author Michael Sosa
+ * @author Yoobin Yoon
  * @since 5.0
  * @see <a target="_blank" href="https://tools.ietf.org/html/rfc6749#section-2">Section 2
  * Client Registration</a>
@@ -299,8 +300,11 @@ public class UserInfoEndpoint implements Serializable {
 
 			private AuthenticationMethod authenticationMethod = AuthenticationMethod.HEADER;
 
+			@Deprecated
 			private String userNameAttributeName;
 
+			private String usernameExpression;
+
 			UserInfoEndpoint() {
 			}
 
@@ -322,15 +326,23 @@ public AuthenticationMethod getAuthenticationMethod() {
 			}
 
 			/**
-			 * Returns the attribute name used to access the user's name from the user
-			 * info response.
-			 * @return the attribute name used to access the user's name from the user
-			 * info response
+			 * @deprecated Use {@link #getUsernameExpression()} instead
 			 */
+			@Deprecated
 			public String getUserNameAttributeName() {
 				return this.userNameAttributeName;
 			}
 
+			/**
+			 * Returns the SpEL expression used to extract the username from user info
+			 * response.
+			 * @return the SpEL expression for username extraction
+			 * @since 7.0
+			 */
+			public String getUsernameExpression() {
+				return this.usernameExpression;
+			}
+
 		}
 
 	}
@@ -370,8 +382,11 @@ public static final class Builder implements Serializable {
 
 		private AuthenticationMethod userInfoAuthenticationMethod = AuthenticationMethod.HEADER;
 
+		@Deprecated
 		private String userNameAttributeName;
 
+		private String usernameExpression;
+
 		private String jwkSetUri;
 
 		private String issuerUri;
@@ -399,6 +414,7 @@ private Builder(ClientRegistration clientRegistration) {
 			this.userInfoUri = clientRegistration.providerDetails.userInfoEndpoint.uri;
 			this.userInfoAuthenticationMethod = clientRegistration.providerDetails.userInfoEndpoint.authenticationMethod;
 			this.userNameAttributeName = clientRegistration.providerDetails.userInfoEndpoint.userNameAttributeName;
+			this.usernameExpression = clientRegistration.providerDetails.userInfoEndpoint.usernameExpression;
 			this.jwkSetUri = clientRegistration.providerDetails.jwkSetUri;
 			this.issuerUri = clientRegistration.providerDetails.issuerUri;
 			Map<String, Object> configurationMetadata = clientRegistration.providerDetails.configurationMetadata;
@@ -552,14 +568,43 @@ public Builder userInfoAuthenticationMethod(AuthenticationMethod userInfoAuthent
 		}
 
 		/**
-		 * Sets the attribute name used to access the user's name from the user info
-		 * response.
-		 * @param userNameAttributeName the attribute name used to access the user's name
-		 * from the user info response
+		 * Sets the username attribute name. This method automatically converts the
+		 * attribute name to a SpEL expression for backward compatibility.
+		 *
+		 * <p>
+		 * This is a convenience method that internally calls
+		 * {@link #usernameExpression(String)} with the attribute name wrapped in bracket
+		 * notation.
+		 * @param userNameAttributeName the username attribute name
 		 * @return the {@link Builder}
 		 */
 		public Builder userNameAttributeName(String userNameAttributeName) {
 			this.userNameAttributeName = userNameAttributeName;
+			if (userNameAttributeName != null) {
+				this.usernameExpression = "['" + userNameAttributeName + "']";
+			}
+			return this;
+		}
+
+		/**
+		 * Sets the SpEL expression used to extract the username from user info response.
+		 *
+		 * <p>
+		 * Examples:
+		 * <ul>
+		 * <li>Simple attribute: {@code "['username']"} or {@code "username"}</li>
+		 * <li>Nested attribute: {@code "data.username"}</li>
+		 * <li>Complex expression: {@code "user_info?.name ?: 'anonymous'"}</li>
+		 * <li>Array access: {@code "users[0].name"}</li>
+		 * <li>Conditional:
+		 * {@code "preferred_username != null ? preferred_username : email"}</li>
+		 * </ul>
+		 * @param usernameExpression the SpEL expression for username extraction
+		 * @return the {@link Builder}
+		 * @since 7.0
+		 */
+		public Builder usernameExpression(String usernameExpression) {
+			this.usernameExpression = usernameExpression;
 			return this;
 		}
 
@@ -669,7 +714,10 @@ private ProviderDetails createProviderDetails(ClientRegistration clientRegistrat
 			providerDetails.tokenUri = this.tokenUri;
 			providerDetails.userInfoEndpoint.uri = this.userInfoUri;
 			providerDetails.userInfoEndpoint.authenticationMethod = this.userInfoAuthenticationMethod;
+
+			providerDetails.userInfoEndpoint.usernameExpression = this.usernameExpression;
 			providerDetails.userInfoEndpoint.userNameAttributeName = this.userNameAttributeName;
+
 			providerDetails.jwkSetUri = this.jwkSetUri;
 			providerDetails.issuerUri = this.issuerUri;
 			providerDetails.configurationMetadata = Collections.unmodifiableMap(this.configurationMetadata);

oauth2/oauth2-client/src/main/java/org/springframework/security/oauth2/client/userinfo/DefaultOAuth2UserService.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2024 the original author or authors.
+ * Copyright 2002-2025 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.
@@ -20,8 +20,12 @@
 import java.util.LinkedHashSet;
 import java.util.Map;
 
+import org.springframework.context.expression.MapAccessor;
 import org.springframework.core.ParameterizedTypeReference;
 import org.springframework.core.convert.converter.Converter;
+import org.springframework.expression.ExpressionParser;
+import org.springframework.expression.spel.standard.SpelExpressionParser;
+import org.springframework.expression.spel.support.SimpleEvaluationContext;
 import org.springframework.http.RequestEntity;
 import org.springframework.http.ResponseEntity;
 import org.springframework.security.core.GrantedAuthority;
@@ -47,16 +51,17 @@
  * An implementation of an {@link OAuth2UserService} that supports standard OAuth 2.0
  * Provider's.
  * <p>
- * For standard OAuth 2.0 Provider's, the attribute name used to access the user's name
- * from the UserInfo response is required and therefore must be available via
- * {@link ClientRegistration.ProviderDetails.UserInfoEndpoint#getUserNameAttributeName()
- * UserInfoEndpoint.getUserNameAttributeName()}.
+ * For standard OAuth 2.0 Provider's, the username expression used to extract the user's
+ * name from the UserInfo response is required and therefore must be available via
+ * {@link ClientRegistration.ProviderDetails.UserInfoEndpoint#getUsernameExpression()
+ * UserInfoEndpoint.getUsernameExpression()}.
  * <p>
  * <b>NOTE:</b> Attribute names are <b>not</b> standardized between providers and
  * therefore will vary. Please consult the provider's API documentation for the set of
  * supported user attribute names.
  *
  * @author Joe Grandja
+ * @author Yoobin Yoon
  * @since 5.0
  * @see OAuth2UserService
  * @see OAuth2UserRequest
@@ -71,6 +76,10 @@ public class DefaultOAuth2UserService implements OAuth2UserService<OAuth2UserReq
 
 	private static final String INVALID_USER_INFO_RESPONSE_ERROR_CODE = "invalid_user_info_response";
 
+	private static final String INVALID_USERNAME_EXPRESSION_ERROR_CODE = "invalid_username_expression";
+
+	private static final ExpressionParser expressionParser = new SpelExpressionParser();
+
 	private static final ParameterizedTypeReference<Map<String, Object>> PARAMETERIZED_RESPONSE_TYPE = new ParameterizedTypeReference<>() {
 	};
 
@@ -90,13 +99,67 @@ public DefaultOAuth2UserService() {
 	@Override
 	public OAuth2User loadUser(OAuth2UserRequest userRequest) throws OAuth2AuthenticationException {
 		Assert.notNull(userRequest, "userRequest cannot be null");
-		String userNameAttributeName = getUserNameAttributeName(userRequest);
+		String usernameExpression = getUsernameExpression(userRequest);
 		RequestEntity<?> request = this.requestEntityConverter.convert(userRequest);
 		ResponseEntity<Map<String, Object>> response = getResponse(userRequest, request);
 		OAuth2AccessToken token = userRequest.getAccessToken();
 		Map<String, Object> attributes = this.attributesConverter.convert(userRequest).convert(response.getBody());
-		Collection<GrantedAuthority> authorities = getAuthorities(token, attributes, userNameAttributeName);
-		return new DefaultOAuth2User(authorities, attributes, userNameAttributeName);
+
+		String evaluatedUsername = evaluateUsername(attributes, usernameExpression);
+
+		Collection<GrantedAuthority> authorities = getAuthorities(token, attributes, evaluatedUsername);
+
+		return DefaultOAuth2User.withUsername(evaluatedUsername)
+			.authorities(authorities)
+			.attributes(attributes)
+			.build();
+	}
+
+	private String getUsernameExpression(OAuth2UserRequest userRequest) {
+		if (!StringUtils
+			.hasText(userRequest.getClientRegistration().getProviderDetails().getUserInfoEndpoint().getUri())) {
+			OAuth2Error oauth2Error = new OAuth2Error(MISSING_USER_INFO_URI_ERROR_CODE,
+					"Missing required UserInfo Uri in UserInfoEndpoint for Client Registration: "
+							+ userRequest.getClientRegistration().getRegistrationId(),
+					null);
+			throw new OAuth2AuthenticationException(oauth2Error, oauth2Error.toString());
+		}
+		String usernameExpression = userRequest.getClientRegistration()
+			.getProviderDetails()
+			.getUserInfoEndpoint()
+			.getUsernameExpression();
+		if (!StringUtils.hasText(usernameExpression)) {
+			OAuth2Error oauth2Error = new OAuth2Error(MISSING_USER_NAME_ATTRIBUTE_ERROR_CODE,
+					"Missing required \"user name\" attribute name in UserInfoEndpoint for Client Registration: "
+							+ userRequest.getClientRegistration().getRegistrationId(),
+					null);
+			throw new OAuth2AuthenticationException(oauth2Error, oauth2Error.toString());
+		}
+		return usernameExpression;
+	}
+
+	private String evaluateUsername(Map<String, Object> attributes, String usernameExpression) {
+		Object value = null;
+
+		try {
+			SimpleEvaluationContext context = SimpleEvaluationContext.forPropertyAccessors(new MapAccessor())
+				.withRootObject(attributes)
+				.build();
+			value = expressionParser.parseExpression(usernameExpression).getValue(context);
+		}
+		catch (Exception ex) {
+			OAuth2Error oauth2Error = new OAuth2Error(INVALID_USERNAME_EXPRESSION_ERROR_CODE,
+					"Invalid username expression or SPEL expression: " + usernameExpression, null);
+			throw new OAuth2AuthenticationException(oauth2Error, oauth2Error.toString(), ex);
+		}
+
+		if (value == null) {
+			OAuth2Error oauth2Error = new OAuth2Error(INVALID_USER_INFO_RESPONSE_ERROR_CODE,
+					"An error occurred while attempting to retrieve the UserInfo Resource: username cannot be null",
+					null);
+			throw new OAuth2AuthenticationException(oauth2Error, oauth2Error.toString());
+		}
+		return value.toString();
 	}
 
 	/**
@@ -164,33 +227,11 @@ private ResponseEntity<Map<String, Object>> getResponse(OAuth2UserRequest userRe
 		}
 	}
 
-	private String getUserNameAttributeName(OAuth2UserRequest userRequest) {
-		if (!StringUtils
-			.hasText(userRequest.getClientRegistration().getProviderDetails().getUserInfoEndpoint().getUri())) {
-			OAuth2Error oauth2Error = new OAuth2Error(MISSING_USER_INFO_URI_ERROR_CODE,
-					"Missing required UserInfo Uri in UserInfoEndpoint for Client Registration: "
-							+ userRequest.getClientRegistration().getRegistrationId(),
-					null);
-			throw new OAuth2AuthenticationException(oauth2Error, oauth2Error.toString());
-		}
-		String userNameAttributeName = userRequest.getClientRegistration()
-			.getProviderDetails()
-			.getUserInfoEndpoint()
-			.getUserNameAttributeName();
-		if (!StringUtils.hasText(userNameAttributeName)) {
-			OAuth2Error oauth2Error = new OAuth2Error(MISSING_USER_NAME_ATTRIBUTE_ERROR_CODE,
-					"Missing required \"user name\" attribute name in UserInfoEndpoint for Client Registration: "
-							+ userRequest.getClientRegistration().getRegistrationId(),
-					null);
-			throw new OAuth2AuthenticationException(oauth2Error, oauth2Error.toString());
-		}
-		return userNameAttributeName;
-	}
-
 	private Collection<GrantedAuthority> getAuthorities(OAuth2AccessToken token, Map<String, Object> attributes,
-			String userNameAttributeName) {
+			String username) {
 		Collection<GrantedAuthority> authorities = new LinkedHashSet<>();
-		authorities.add(new OAuth2UserAuthority(attributes, userNameAttributeName));
+		authorities.add(OAuth2UserAuthority.withUsername(username).attributes(attributes).build());
+
 		for (String authority : token.getScopes()) {
 			authorities.add(new SimpleGrantedAuthority("SCOPE_" + authority));
 		}