Deprecate CustomUserTypesOAuth2UserService

Closes gh-8908

Author: jgrandja

config/src/main/java/org/springframework/security/config/annotation/web/configurers/oauth2/client/OAuth2LoginConfigurer.java

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2019 the original author or authors.
+ * Copyright 2002-2020 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.
@@ -439,10 +439,13 @@ public UserInfoEndpointConfig oidcUserService(OAuth2UserService<OidcUserRequest,
 		 * Sets a custom {@link OAuth2User} type and associates it to the provided
 		 * client {@link ClientRegistration#getRegistrationId() registration identifier}.
 		 *
+		 * @deprecated See {@link CustomUserTypesOAuth2UserService} for alternative usage.
+		 *
 		 * @param customUserType a custom {@link OAuth2User} type
 		 * @param clientRegistrationId the client registration identifier
 		 * @return the {@link UserInfoEndpointConfig} for further configuration
 		 */
+		@Deprecated
 		public UserInfoEndpointConfig customUserType(Class<? extends OAuth2User> customUserType, String clientRegistrationId) {
 			Assert.notNull(customUserType, "customUserType cannot be null");
 			Assert.hasText(clientRegistrationId, "clientRegistrationId cannot be empty");

docs/manual/src/docs/asciidoc/_includes/servlet/oauth2/oauth2-login.adoc

@@ -616,7 +616,6 @@ public class OAuth2LoginSecurityConfig extends WebSecurityConfigurerAdapter {
 			        .userAuthoritiesMapper(this.userAuthoritiesMapper())
 			        .userService(this.oauth2UserService())
 			        .oidcUserService(this.oidcUserService())
-			        .customUserType(GitHubOAuth2User.class, "github")
 			    )
 			);
 	}
@@ -651,7 +650,6 @@ class OAuth2LoginSecurityConfig : WebSecurityConfigurerAdapter() {
                     userAuthoritiesMapper = userAuthoritiesMapper()
                     userService = oauth2UserService()
                     oidcUserService = oidcUserService()
-                    customUserType(GitHubOAuth2User::class.java, "github")
                 }
             }
         }
@@ -875,7 +873,6 @@ return CommonOAuth2Provider.GOOGLE.getBuilder("google")
 The UserInfo Endpoint includes a number of configuration options, as described in the following sub-sections:
 
 * <<oauth2login-advanced-map-authorities, Mapping User Authorities>>
-* <<oauth2login-advanced-custom-user, Configuring a Custom OAuth2User>>
 * <<oauth2login-advanced-oauth2-user-service, OAuth 2.0 UserService>>
 * <<oauth2login-advanced-oidc-user-service, OpenID Connect 1.0 UserService>>
 
@@ -1142,104 +1139,6 @@ class OAuth2LoginSecurityConfig : WebSecurityConfigurerAdapter() {
 ====
 
 
-[[oauth2login-advanced-custom-user]]
-===== Configuring a Custom OAuth2User
-
-`CustomUserTypesOAuth2UserService` is an implementation of an `OAuth2UserService` that provides support for custom `OAuth2User` types.
-
-If the default implementation (`DefaultOAuth2User`) does not suit your needs, you can define your own implementation of `OAuth2User`.
-
-The following code demonstrates how you would register a custom `OAuth2User` type for GitHub:
-
-[source,java]
-----
-@EnableWebSecurity
-public class OAuth2LoginSecurityConfig extends WebSecurityConfigurerAdapter {
-
-	@Override
-	protected void configure(HttpSecurity http) throws Exception {
-		http
-			.oauth2Login(oauth2 -> oauth2
-			    .userInfoEndpoint(userInfo -> userInfo
-			        .customUserType(GitHubOAuth2User.class, "github")
-			        ...
-			    )
-			);
-	}
-}
-----
-
-The following code shows an example of a custom `OAuth2User` type for GitHub:
-
-[source,java]
-----
-public class GitHubOAuth2User implements OAuth2User {
-	private List<GrantedAuthority> authorities =
-		AuthorityUtils.createAuthorityList("ROLE_USER");
-	private Map<String, Object> attributes;
-	private String id;
-	private String name;
-	private String login;
-	private String email;
-
-	@Override
-	public Collection<? extends GrantedAuthority> getAuthorities() {
-		return this.authorities;
-	}
-
-	@Override
-	public Map<String, Object> getAttributes() {
-		if (this.attributes == null) {
-			this.attributes = new HashMap<>();
-			this.attributes.put("id", this.getId());
-			this.attributes.put("name", this.getName());
-			this.attributes.put("login", this.getLogin());
-			this.attributes.put("email", this.getEmail());
-		}
-		return attributes;
-	}
-
-	public String getId() {
-		return this.id;
-	}
-
-	public void setId(String id) {
-		this.id = id;
-	}
-
-	@Override
-	public String getName() {
-		return this.name;
-	}
-
-	public void setName(String name) {
-		this.name = name;
-	}
-
-	public String getLogin() {
-		return this.login;
-	}
-
-	public void setLogin(String login) {
-		this.login = login;
-	}
-
-	public String getEmail() {
-		return this.email;
-	}
-
-	public void setEmail(String email) {
-		this.email = email;
-	}
-}
-----
-
-[TIP]
-`id`, `name`, `login`, and `email` are attributes returned in GitHub's UserInfo Response.
-For detailed information returned from the UserInfo Endpoint, see the API documentation
-for https://developer.github.com/v3/users/#get-the-authenticated-user["Get the authenticated user"].
-
-
 [[oauth2login-advanced-oauth2-user-service]]
 ===== OAuth 2.0 UserService
 

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

@@ -1,5 +1,5 @@
 /*
- * Copyright 2002-2018 the original author or authors.
+ * Copyright 2002-2020 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.
@@ -40,13 +40,18 @@
  * using a {@code Map} of {@link OAuth2User} type(s) keyed by {@code String},
  * which represents the {@link ClientRegistration#getRegistrationId() Registration Id} of the Client.
  *
+ * @deprecated It is recommended to use a delegation-based strategy of an {@link OAuth2UserService} to support custom {@link OAuth2User} types,
+ * as it provides much greater flexibility compared to this implementation.
+ * See the <a target="_blank" href="https://docs.spring.io/spring-security/site/docs/current/reference/html5/#oauth2login-advanced-map-authorities-oauth2userservice">reference manual</a> for details on how to implement.
+ *
  * @author Joe Grandja
  * @since 5.0
  * @see OAuth2UserService
  * @see OAuth2UserRequest
  * @see OAuth2User
  * @see ClientRegistration
  */
+@Deprecated
 public class CustomUserTypesOAuth2UserService implements OAuth2UserService<OAuth2UserRequest, OAuth2User> {
 	private static final String INVALID_USER_INFO_RESPONSE_ERROR_CODE = "invalid_user_info_response";