Update javadoc for HttpSecurity.oauth2Login()

Fixes gh-4875

config/src/main/java/org/springframework/security/config/annotation/web/builders/HttpSecurity.java

@@ -62,7 +62,6 @@ import org.springframework.security.core.context.SecurityContext;
 import org.springframework.security.core.context.SecurityContextHolder;
 import org.springframework.security.core.userdetails.UserDetailsService;
 import org.springframework.security.config.annotation.web.configurers.oauth2.client.OAuth2LoginConfigurer;
-import org.springframework.security.oauth2.client.endpoint.OAuth2AccessTokenResponseClient;
 import org.springframework.security.web.DefaultSecurityFilterChain;
 import org.springframework.security.web.PortMapper;
 import org.springframework.security.web.PortMapperImpl;
@@ -899,149 +898,92 @@ public final class HttpSecurity extends
 	}
 
 	/**
-	 * Configures authentication against an external <i>OAuth 2.0</i> or <i>OpenID Connect 1.0</i> Provider.
+	 * Configures authentication support using an OAuth 2.0 and/or OpenID Connect 1.0 Provider.
 	 * <br>
 	 * <br>
 	 *
-	 * The <i>&quot;authentication flow&quot;</i> is realized using the <b>Authorization Code Grant</b>,
-	 * as specified in the <a target="_blank" href="https://tools.ietf.org/html/rfc6749#section-4.1">OAuth 2.0 Authorization Framework</a>.
+	 * The &quot;authentication flow&quot; is implemented using the <b>Authorization Code Grant</b>, as specified in the
+	 * <a target="_blank" href="https://tools.ietf.org/html/rfc6749#section-4.1">OAuth 2.0 Authorization Framework</a>
+	 * and <a target="_blank" href="http://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth">OpenID Connect Core 1.0</a>
+	 * specification.
 	 * <br>
 	 * <br>
 	 *
-	 * As a prerequisite to using this feature, the developer must register a <i>Client</i> with an <i>Authorization Server</i>.
-	 * The output of the <i>Client Registration</i> process results in a number of properties that are then used for configuring
-	 * an instance of a {@link org.springframework.security.oauth2.client.registration.ClientRegistration}.
-	 * Properties specific to a <i>Client</i> include: <i>client_id</i>, <i>client_secret</i>, <i>scope</i>, <i>redirect_uri</i>, etc.
-	 * There are also properties specific to the <i>Provider</i>, for example,
-	 * <i>Authorization Endpoint URI</i>, <i>Token Endpoint URI</i>, <i>UserInfo Endpoint URI</i>, etc.
-	 * <br>
-	 * <br>
-	 *
-	 * Multiple client support is provided for use cases where the application provides the user the option
-	 * for <i>&quot;Logging in&quot;</i> against one or more Providers, for example, <i>Google</i>, <i>GitHub</i>, <i>Facebook</i>, etc.
+	 * As a prerequisite to using this feature, you must register a client with a provider.
+	 * The client registration information may than be used for configuring
+	 * a {@link org.springframework.security.oauth2.client.registration.ClientRegistration} using a
+	 * {@link org.springframework.security.oauth2.client.registration.ClientRegistration.Builder}.
 	 * <br>
 	 * <br>
 	 *
 	 * {@link org.springframework.security.oauth2.client.registration.ClientRegistration}(s) are composed within a
-	 * {@link org.springframework.security.oauth2.client.registration.ClientRegistrationRepository}.
-	 * An instance of {@link org.springframework.security.oauth2.client.registration.ClientRegistrationRepository} is <b>required</b>
-	 * and may be supplied via the {@link ApplicationContext} or configured using
-	 * {@link OAuth2LoginConfigurer#clientRegistrationRepository(org.springframework.security.oauth2.client.registration.ClientRegistrationRepository)}.
+	 * {@link org.springframework.security.oauth2.client.registration.ClientRegistrationRepository},
+	 * which is <b>required</b> and must be registered with the {@link ApplicationContext} or
+	 * configured via <code>oauth2Login().clientRegistrationRepository(..)</code>.
 	 * <br>
 	 * <br>
 	 *
 	 * The default configuration provides an auto-generated login page at <code>&quot;/login&quot;</code> and
 	 * redirects to <code>&quot;/login?error&quot;</code> when an authentication error occurs.
-	 * The login page will display each of the clients (composed within the
-	 * {@link org.springframework.security.oauth2.client.registration.ClientRegistrationRepository})
-	 * with an anchor link to <code>&quot;/oauth2/authorization/code/{clientAlias}&quot;</code>.
-	 * Clicking through the link will initiate the <i>&quot;Authorization Request&quot;</i> flow
-	 * redirecting the end-user's user-agent to the <i>Authorization Endpoint</i> of the <i>Provider</i>.
-	 * Assuming the <i>Resource Owner</i> (end-user) grants the <i>Client</i> access, the <i>Authorization Server</i>
-	 * will redirect the end-user's user-agent to the <i>Redirection Endpoint</i> containing the <i>Authorization Code</i>
-	 * - the <i>Redirection Endpoint</i> is automatically configured for the application and
-	 * defaults to <code>&quot;/oauth2/authorize/code/{clientAlias}&quot;</code>.
+	 * The login page will display each of the clients with a link
+	 * that is capable of initiating the &quot;authentication flow&quot;.
+	 * <br>
+	 * <br>
 	 *
 	 * <p>
-	 * At this point in the <i>&quot;authentication flow&quot;</i>, the configured
-	 * {@link OAuth2AccessTokenResponseClient}
-	 * will getTokenResponse the <i>Authorization Code</i> for an <i>Access Token</i> and then use it to access the protected resource
-	 * at the <i>UserInfo Endpoint</i> in order to retrieve the details of the <i>Resource Owner</i> (end-user) and establish the
-	 * <i>&quot;authenticated&quot;</i> session.
-	 *
-	 * <h2>Example Configurations</h2>
+	 * <h2>Example Configuration</h2>
 	 *
-	 * The minimal configuration defaults to automatically generating a login page at <code>&quot;/login&quot;</code>
-	 * and redirecting to <code>&quot;/login?error&quot;</code> when an authentication error occurs or redirecting to
-	 * <code>&quot;/&quot;</code> when an authenticated session is established.
+	 * The following example shows the minimal configuration required, using Google as the Authentication Provider.
 	 *
 	 * <pre>
-	 * &#064;EnableWebSecurity
-	 * public class OAuth2LoginSecurityConfig extends WebSecurityConfigurerAdapter {
-	 *
-	 * 	&#064;Override
-	 * 	protected void configure(HttpSecurity http) throws Exception {
-	 *		http
-	 * 			.authorizeRequests()
-	 * 				.anyRequest().authenticated()
-	 * 				.and()
-	 * 			.oauth2Login();
-	 * 	}
-	 *
-	 *	&#064;Bean
-	 *	public ClientRegistrationRepository clientRegistrationRepository() {
-	 *		// ClientRegistrationRepositoryImpl must be composed of at least one ClientRegistration instance
-	 *		return new ClientRegistrationRepositoryImpl();
+	 * &#064;Configuration
+	 * public class OAuth2LoginConfig {
+	 *
+	 * 	&#064;EnableWebSecurity
+	 * 	public static class OAuth2LoginSecurityConfig extends WebSecurityConfigurerAdapter {
+	 * 		&#064;Override
+	 * 		protected void configure(HttpSecurity http) throws Exception {
+	 * 			http
+	 * 				.authorizeRequests()
+	 * 					.anyRequest().authenticated()
+	 * 					.and()
+	 * 				  .oauth2Login();
+	 *		}
 	 *	}
-	 * }
-	 * </pre>
-	 *
-	 * The following shows the configuration options available for customizing the defaults.
-	 *
-	 * <pre>
-	 * &#064;EnableWebSecurity
-	 * public class OAuth2LoginSecurityConfig extends WebSecurityConfigurerAdapter {
-	 *
-	 * 	&#064;Override
-	 * 	protected void configure(HttpSecurity http) throws Exception {
-	 *		http
-	 * 			.authorizeRequests()
-	 * 				.anyRequest().authenticated()
-	 * 				.and()
-	 * 			.oauth2Login()
-	 * 				.clientRegistrationRepository(this.clientRegistrationRepository())
-	 * 				.authorizationRequestUriBuilder(this.authorizationRequestUriBuilder())
-	 * 				.accessTokenResponseClient(this.accessTokenResponseClient())
-	 * 				.userInfoEndpoint()
-	 * 					.userInfoService(this.userInfoService())
-	 * 				.userInfoEndpoint()
-	 * 					// Provide a mapping between a Converter implementation and a UserInfo Endpoint URI
-	 * 					.userInfoTypeConverter(this.userInfoConverter(),
-	 * 									new URI("https://www.googleapis.com/oauth2/v3/userinfo"));
-	 * 	}
 	 *
 	 *	&#064;Bean
 	 *	public ClientRegistrationRepository clientRegistrationRepository() {
-	 *		// ClientRegistrationRepositoryImpl must be composed of at least one ClientRegistration instance
-	 *		return new ClientRegistrationRepositoryImpl();
+	 *		return new InMemoryClientRegistrationRepository(this.googleClientRegistration());
 	 *	}
 	 *
-	 * 	&#064;Bean
-	 * 	public AuthorizationRequestUriBuilder authorizationRequestUriBuilder() {
-	 * 		// Custom URI builder for the &quot;Authorization Request&quot;
-	 * 		return new AuthorizationRequestUriBuilderImpl();
-	 * 	}
-	 *
-	 * 	&#064;Bean
-	 * 	public OAuth2AccessTokenResponseClient&lt;OAuth2LoginAuthenticationToken&gt; accessTokenResponseClient() {
-	 * 		// Custom implementation that exchanges an &quot;Authorization Code Grant&quot; for an &quot;Access Token&quot;
-	 * 		return new AuthorizationCodeTokenExchangerImpl();
-	 * 	}
-	 *
-	 * 	&#064;Bean
-	 * 	public OAuth2UserService userInfoService() {
-	 * 		// Custom implementation that retrieves the details of the authenticated user at the &quot;UserInfo Endpoint&quot;
-	 * 		return new OAuth2UserServiceImpl();
-	 * 	}
-	 *
-	 * 	&#064;Bean
-	 * 	public Converter&lt;ClientHttpResponse, UserInfo&gt; userInfoConverter() {
-	 * 		// Default converter implementation for UserInfo
-	 * 		return new org.springframework.security.oauth2.client.user.converter.UserInfoConverter();
-	 * 	}
+	 * 	private ClientRegistration googleClientRegistration() {
+	 * 		return ClientRegistration.withRegistrationId("google")
+	 * 			.clientId("google-client-id")
+	 * 			.clientSecret("google-client-secret")
+	 * 			.clientAuthenticationMethod(ClientAuthenticationMethod.BASIC)
+	 * 			.authorizationGrantType(AuthorizationGrantType.AUTHORIZATION_CODE)
+	 * 			.redirectUriTemplate("{baseUrl}/login/oauth2/code/{registrationId}")
+	 * 			.scope("openid", "profile", "email", "address", "phone")
+	 * 			.authorizationUri("https://accounts.google.com/o/oauth2/v2/auth")
+	 * 			.tokenUri("https://www.googleapis.com/oauth2/v4/token")
+	 * 			.userInfoUri("https://www.googleapis.com/oauth2/v3/userinfo")
+	 * 			.userNameAttributeName(IdTokenClaimNames.SUB)
+	 * 			.jwkSetUri("https://www.googleapis.com/oauth2/v3/certs")
+	 * 			.clientName("Google")
+	 * 			.build();
+	 *	}
 	 * }
 	 * </pre>
 	 *
+	 * <p>
+	 * For more advanced configuration, see {@link OAuth2LoginConfigurer} for available options to customize the defaults.
+	 *
 	 * @author Joe Grandja
 	 * @since 5.0
-	 * @see <a target="_blank" href="https://tools.ietf.org/html/rfc6749#section-4.1">Section 4.1 Authorization Code Grant Flow</a>
-	 * @see <a target="_blank" href="https://tools.ietf.org/html/rfc6749#section-4.1.1">Section 4.1.1 Authorization Request</a>
-	 * @see <a target="_blank" href="https://tools.ietf.org/html/rfc6749#section-4.1.2">Section 4.1.2 Authorization Response</a>
+	 * @see <a target="_blank" href="https://tools.ietf.org/html/rfc6749#section-4.1">Section 4.1 Authorization Code Grant</a>
+	 * @see <a target="_blank" href="http://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth">Section 3.1 Authorization Code Flow</a>
 	 * @see org.springframework.security.oauth2.client.registration.ClientRegistration
 	 * @see org.springframework.security.oauth2.client.registration.ClientRegistrationRepository
-	 * @see OAuth2AccessTokenResponseClient
-	 * @see org.springframework.security.oauth2.client.user.OAuth2UserService
-	 *
 	 * @return the {@link OAuth2LoginConfigurer} for further customizations
 	 * @throws Exception
 	 */