Document OAuth2UserService delegation-based strategy for authorities mapping

Fixes gh-4909

docs/manual/src/docs/asciidoc/index.adoc

@@ -6851,13 +6851,21 @@ The UserInfo Endpoint includes a number of configuration options, as described i
 ==== Mapping User Authorities
 
 After the user successfully authenticates with the OAuth 2.0 Provider,
-the `OAuth2User.getAuthorities()` may be mapped to a new set of `GrantedAuthority` instances, which are then supplied to `OAuth2AuthenticationToken`.
+the `OAuth2User.getAuthorities()` (or `OidcUser.getAuthorities()`) may be mapped to a new set of `GrantedAuthority` instances,
+which will be supplied to `OAuth2AuthenticationToken` when completing the authentication.
 
 [TIP]
 `OAuth2AuthenticationToken.getAuthorities()` is used for authorizing requests, such as in `hasRole('USER')` or `hasRole('ADMIN')`.
 
-In order to map user authorities, you need to provide an implementation of `GrantedAuthoritiesMapper`
+There are a couple of options to choose from when mapping user authorities:
-and configure it as shown in the following example:
+
+* <<oauth2login-advanced-map-authorities-grantedauthoritiesmapper,Using a `GrantedAuthoritiesMapper`>>
+* <<oauth2login-advanced-map-authorities-oauth2userservice,Delegation-based strategy with `OAuth2UserService`>>
+
+[[oauth2login-advanced-map-authorities-grantedauthoritiesmapper]]
+===== Using a `GrantedAuthoritiesMapper`
+
+Provide an implementation of `GrantedAuthoritiesMapper` and configure it as shown in the following example:
 
 [source,java]
 ----
@@ -6904,6 +6912,56 @@ public class OAuth2LoginSecurityConfig extends WebSecurityConfigurerAdapter {
 }
 ----
 
+[[oauth2login-advanced-map-authorities-oauth2userservice]]
+===== Delegation-based strategy with `OAuth2UserService`
+
+This strategy is advanced compared to using a `GrantedAuthoritiesMapper`, however, it's also more flexible
+as it gives you access to the `OAuth2UserRequest` and `OAuth2User` (when using an OAuth 2.0 UserService)
+or `OidcUserRequest` and `OidcUser` (when using an OpenID Connect 1.0 UserService).
+
+The `OAuth2UserRequest` (and `OidcUserRequest`) provides you access to the associated `OAuth2AccessToken`,
+which is very useful in the cases where the _delegator_ needs to fetch authority information
+from a protected resource before it can map the custom authorities for the user.
+
+The following example shows how to implement and configure a delegation-based strategy using an OpenID Connect 1.0 UserService:
+
+[source,java]
+----
+@EnableWebSecurity
+public class OAuth2LoginSecurityConfig extends WebSecurityConfigurerAdapter {
+
+	@Override
+	protected void configure(HttpSecurity http) throws Exception {
+		http
+			.oauth2Login()
+				.userInfoEndpoint()
+					.oidcUserService(this.oidcUserService())
+					...
+	}
+
+	private OAuth2UserService<OidcUserRequest, OidcUser> oidcUserService() {
+		final OidcUserService delegate = new OidcUserService();
+
+		return (userRequest) -> {
+			// Delegate to the default implementation for loading a user
+			OidcUser oidcUser = delegate.loadUser(userRequest);
+
+			OAuth2AccessToken accessToken = userRequest.getAccessToken();
+			Set<GrantedAuthority> mappedAuthorities = new HashSet<>();
+
+			// TODO
+			// 1) Fetch the authority information from the protected resource using accessToken
+			// 2) Map the authority information to one or more GrantedAuthority's and add it to mappedAuthorities
+
+			// 3) Create a copy of oidcUser but use the mappedAuthorities instead
+			oidcUser = new DefaultOidcUser(mappedAuthorities, oidcUser.getIdToken(), oidcUser.getUserInfo());
+
+			return oidcUser;
+		};
+	}
+}
+----
+
 [[oauth2login-advanced-custom-user]]
 ==== Configuring a Custom OAuth2User