Document the end-to-end Servlet OAuth2 Login authentication flow

Summary

This is a documentation enhancement proposal. No behavioral or API change is requested.

The Servlet OAuth2 Login documentation currently explains the individual components involved in authentication, but it is difficult to follow how those components interact across the complete login lifecycle.

I would like to contribute documentation that connects the OAuth2 Login components in execution order and identifies the extension points available to applications.

Proposed Documentation

The proposed section would explain the following flow:

1. A client initiates login through /oauth2/authorization/{registrationId}.
2. OAuth2AuthorizationRequestRedirectFilter creates the authorization request.
3. OAuth2AuthorizationRequestRepository temporarily stores the request, including values used for request correlation and PKCE.
4. The authorization server redirects the user agent to /login/oauth2/code/{registrationId} with an authorization code.
5. OAuth2LoginAuthenticationFilter processes the authorization response.
6. The filter delegates authentication to AuthenticationManager.
7. OAuth2LoginAuthenticationProvider exchanges the authorization code for an access token.
8. OAuth2UserService retrieves the user information and returns an OAuth2User.
9. Spring Security creates an authenticated OAuth2AuthenticationToken.
10. The resulting authentication is stored through SecurityContextRepository.
11. The configured AuthenticationSuccessHandler is invoked.

A compact sequence diagram could illustrate the relationship between the browser, client application, authorization server, filters, authentication provider, user service, and security context.

Extension Points

The documentation could also identify the primary extension points available at each stage:

• OAuth2AuthorizationRequestResolver
• AuthorizationRequestRepository
• OAuth2UserService
• GrantedAuthoritiesMapper
• AuthenticationSuccessHandler
• AuthenticationFailureHandler
• SecurityContextRepository

Motivation

The individual classes are documented in the reference and API documentation, but their relationship is distributed across multiple sections.

In particular, it is not immediately clear:

• Which filter processes each of the default OAuth2 endpoint patterns
• Where the authorization request, state, and PKCE data are stored
• Which component performs the authorization-code exchange
• When OAuth2UserService is invoked
• How a custom OAuth2User becomes the authenticated principal
• When the resulting Authentication is stored in the SecurityContext
• When the success handler is invoked

An end-to-end lifecycle section would make it easier for users to understand where custom OAuth2 login logic belongs without requiring them to trace the filter and provider implementations.

Contribution

I would be happy to contribute this documentation.

Would this addition be welcome? If so, which existing Servlet OAuth2 Login documentation section would be the preferred location?

Start by reading the existing Servlet OAuth2 Login documentation and tracing the named filters, providers, services, and security-context components in the proposed execution order. Add an end-to-end lifecycle section, a compact sequence diagram, and the listed extension points; done means the endpoint flow and customization locations are understandable without tracing implementations.