Add SpEL support for nested username extraction in OAuth2 user info

[yybmion]

This PR adds support for extracting usernames from nested properties in OAuth2 user info responses using SpEL expressions, addressing the limitation where providers wrap user data in nested objects.

Fixes #16390

Problem

OAuth2 providers (like X/Twitter) wrap user data in nested objects, requiring complex workarounds to extract usernames.

Solution

Commit 1: Allow injecting principal name into DefaultOAuth2User

• Add username field to DefaultOAuth2User
• Add static factory method withUsername() for direct username injection
• Deprecate constructor that uses nameAttributeKey lookup
• Maintain backward compatibility and serialization format

Commit 2: Add SpEL support for nested username extraction

• Add usernameExpression property to ClientRegistration
• Add username field to OAuth2UserAuthority
• Support SpEL expressions for nested property access (e.g., "data.username")
• Use SimpleEvaluationContext for secure expression evaluation
• Update both DefaultOAuth2UserService and DefaultReactiveOAuth2UserService
• Pass evaluated username directly to OAuth2UserAuthority for Expose user name attribute name in OAuth2UserAuthority #15012 compatibility

Backward Compatibility

• No breaking changes - all existing APIs continue to work
• Deprecated APIs remain functional with clear migration path

[rwinch]

Thanks for the PR @yybmion! I wonder if this might be better implemented using SpEL to provide more powerful options for resolving the username. What are your thoughts?

[yybmion]

Hi @rwinch , Thank you for your guidance on this.

I initially chose the dot notation approach because it offers a simple and intuitive solution specifically for the nested user-name-attribute issue.

However, I can see the value in using SpEL as you suggested. While I think it may be slightly more complex, SpEL provides much greater extensibility for future use cases beyond simple nested structures. The consistency with other parts of the Spring Security framework is also a advantage.

If you confirm that SpEL is the preferred direction, I'd be happy to update the PR accordingly.

[rwinch]

Yes. Please provide an implementation that uses SpEL.

[yybmion]

Hello @rwinch, I'd like to clarify your feedback on my PR about supporting nested properties in the user-name-attribute.

Did you mean that I should implement support for expressions like #{data.username} in the properties and yml configuration files to handle nested structures? (Instead using data.username)

Thank you for your guidance!

[rwinch]

I think an outline would be:

Allow Injecting the Principal Name into DefaultOAuth2User

Right now OAuth2UserService requires defining the name property as an attribute name. This limits the flexibility of resolving the name.

Update DefaultOAuth2User to allow injecting the name (rather than a property for obtaining the name). You would add a new member variable of username. This would likely require using a static factory method to distinguish from the existing constructor since the types of the nameAttributeKey and username are the same.

You can remove the nameAttributeKey member variable and instead populate the username using the attributes[nameAttributeKey] in the constructor if nameAttributeKey was specified.

Deprecate the old DefaultOAuth2User constructor in favor of injecting the name directly and update the usage of DefaultOAuth2User within Spring Security to no longer use the deprecated constructor.

Add SpEL Support

Update ClientRegistration to have a property named usernameExpression and remove the userNameAttributeName property but preserving and deprecating the methods which instead populate the usernameExpression member variable. This should be passive since the usernameAttributeName is a valid SpEL expression.

Update OAuth2UserService to extract the username using the usernameExpression property from the ClientRegistration as a SpEL expression with the attributes as the root object. Create the DefaultOAuth2User with the username injected into it rather than using the nameAttributeKey.

I think creating these as two separate commits is valuable since they are useful on their own. Let me know your thoughts.

[yybmion]

Hi @rwinch. I've addressed all the review feedback and updated the documentation as requested.
Please let me know if there are any areas in the documentation that need further improvement or clarification.

[rwinch]

Thank you for the changes.

I've included some comments inline around Spring Boot not supporting the new property yet. We will need to create a ticket with them once we merge here. Once they add the support we can add the documentation back.

Please go through and find/remove any usage (within main) for any of the constructors/methods that you deprecated. For example, I see that OidcUserRequestUtils still references UserInfoEndpoint.getUserNameAttributeName() We should update it to use non-deprecated methods.

[rwinch]

Can you please fix this to use tabs?

[rwinch]

This won't work yet because Spring Boot has not added support. Please remove it for now. If you like, you can save it in another branch in its own commit and we can use it when Spring Boot adds the support.

[rwinch]

This won't work yet because Spring Boot has not added support. Please remove it for now. If you like, you can save it in another branch in its own commit and we can use it when Spring Boot adds the support.

[rwinch]

The yaml won't work yet because Spring Boot has not added support. Please remove it for now. If you like, you can save it in another branch in its own commit and we can use it when Spring Boot adds the support.

[yybmion]

Thank you for the review @rwinch !
I'm planning to create a separate commit to address the deprecated constructor/method usage you mentioned. However, I have a few questions that came up during the modifications.

I'm wondering about your thoughts on :

1. Deprecating the nameAttributeKey field in DefaultOAuth2User constructors for consistency with the new usernameExpression approach
2. Adding builder pattern to DefaultOidcUser since it extends DefaultOAuth2User and currently calls the deprecated parent constructor via super()

Should I include these changes in this PR?

[rwinch]

Thanks for reaching out and your patience as we put the final touches on this @yybmion

Deprecating the nameAttributeKey field in DefaultOAuth2User constructors for consistency with the new usernameExpression approach

Yes. I think that this is good. Generally, we want people to move to the builder instead.

Adding builder pattern to DefaultOidcUser since it extends DefaultOAuth2User and currently calls the deprecated parent constructor via super().

Yes I think that is good too. You will likely need to ensure the non-deprecated constructor in DefaultOAuth2User is protected so that it can be used by DefaultOidcUser.

Should I include these changes in this PR?

Yes please. It is important that we push people towards the new, more powerful, approach.

[yybmion]

Thank you for the guidance, @rwinch !
I've updated the deprecated constructor/method usage in main based on your review feedback. After searching through the codebase, I found that most of the deprecated usage was in OidcUserRequestUtils using deprecated constructors/methods. The remaining usage was in test code and documentation, which I left unchanged as requested.

Additionally, since the username SpEL evaluation logic was being used in multiple places, I created a utility class OAuth2UsernameExpressionUtils to centralize this functionality and eliminate code duplication.

[yybmion]

Hi @rwinch,
I noticed that the "What's New" documentation for Spring Security 7 has recently been updated, which caused a conflict with the changes I previously added. I've resolved the conflict accordingly.

[rwinch]

Thanks again for all of your work on this PR!

I'd like to encapsulate the logic (keep private) in OAuth2UsernameExpressionUtils so that we can refactor without breaking anything later. One example of such a refactoring is that at some point the ExpressionParser might need to be injected to allow resolving Bean references in the expressions. Even if we allow injecting the ExpressionParser, I'd still like to keep this logic encapsulated in case of other refactorings.

To work toward that end I created and resolved gh-17626. In the case where we invoke the OAuth2UserService (or the reactive equivalent), we could use the result to obtain the username. The problem is that OidcUserService (and the reactive equivalent) leverage userNameAttributeName even when the OAuth2Service is not invoked and it does not use the result from the delegate service even when it does invoke the user info endpoint.

To address those concerns I created gh-17627 gh-17628

I believe we could extract the logic for injecting the username rather than the attribute into a separate PR and merge that without being blocked since that behavior would be passive and not be impacted by the decisions of the issues above. Feel free to do this if you like. However, as of now we are blocked on merging resolving the username using an expression until those two issues are resolved.

cc @jgrandja