From 3f1b09c2482f0b279d9bf490977160ca1bcd769d Mon Sep 17 00:00:00 2001 From: Joe Grandja Date: Mon, 27 Nov 2017 13:16:20 -0500 Subject: [PATCH] Update javadoc for HttpSecurity.oauth2Login() Fixes gh-4875 --- .../annotation/web/builders/HttpSecurity.java | 164 ++++++------------ 1 file changed, 53 insertions(+), 111 deletions(-) diff --git a/config/src/main/java/org/springframework/security/config/annotation/web/builders/HttpSecurity.java b/config/src/main/java/org/springframework/security/config/annotation/web/builders/HttpSecurity.java index 6de48cbba3..4e4b9c0cb9 100644 --- a/config/src/main/java/org/springframework/security/config/annotation/web/builders/HttpSecurity.java +++ b/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 OAuth 2.0 or OpenID Connect 1.0 Provider. + * Configures authentication support using an OAuth 2.0 and/or OpenID Connect 1.0 Provider. *
*
* - * The "authentication flow" is realized using the Authorization Code Grant, - * as specified in the OAuth 2.0 Authorization Framework. + * The "authentication flow" is implemented using the Authorization Code Grant, as specified in the + * OAuth 2.0 Authorization Framework + * and OpenID Connect Core 1.0 + * specification. *
*
* - * As a prerequisite to using this feature, the developer must register a Client with an Authorization Server. - * The output of the Client Registration 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 Client include: client_id, client_secret, scope, redirect_uri, etc. - * There are also properties specific to the Provider, for example, - * Authorization Endpoint URI, Token Endpoint URI, UserInfo Endpoint URI, etc. - *
- *
- * - * Multiple client support is provided for use cases where the application provides the user the option - * for "Logging in" against one or more Providers, for example, Google, GitHub, Facebook, 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}. *
*
* * {@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 required - * 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 required and must be registered with the {@link ApplicationContext} or + * configured via oauth2Login().clientRegistrationRepository(..). *
*
* * The default configuration provides an auto-generated login page at "/login" and * redirects to "/login?error" 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 "/oauth2/authorization/code/{clientAlias}". - * Clicking through the link will initiate the "Authorization Request" flow - * redirecting the end-user's user-agent to the Authorization Endpoint of the Provider. - * Assuming the Resource Owner (end-user) grants the Client access, the Authorization Server - * will redirect the end-user's user-agent to the Redirection Endpoint containing the Authorization Code - * - the Redirection Endpoint is automatically configured for the application and - * defaults to "/oauth2/authorize/code/{clientAlias}". + * The login page will display each of the clients with a link + * that is capable of initiating the "authentication flow". + *
+ *
* *

- * At this point in the "authentication flow", the configured - * {@link OAuth2AccessTokenResponseClient} - * will getTokenResponse the Authorization Code for an Access Token and then use it to access the protected resource - * at the UserInfo Endpoint in order to retrieve the details of the Resource Owner (end-user) and establish the - * "authenticated" session. + *

Example Configuration

* - *

Example Configurations

- * - * The minimal configuration defaults to automatically generating a login page at "/login" - * and redirecting to "/login?error" when an authentication error occurs or redirecting to - * "/" when an authenticated session is established. + * The following example shows the minimal configuration required, using Google as the Authentication Provider. * * 
-	 * @EnableWebSecurity
-	 * public class OAuth2LoginSecurityConfig extends WebSecurityConfigurerAdapter {
+	 * @Configuration
+	 * public class OAuth2LoginConfig {
 	 *
-	 * 	@Override
-	 * 	protected void configure(HttpSecurity http) throws Exception {
-	 *		http
-	 * 			.authorizeRequests()
-	 * 				.anyRequest().authenticated()
-	 * 				.and()
-	 * 			.oauth2Login();
-	 * 	}
+	 * 	@EnableWebSecurity
+	 * 	public static class OAuth2LoginSecurityConfig extends WebSecurityConfigurerAdapter {
+	 * 		@Override
+	 * 		protected void configure(HttpSecurity http) throws Exception {
+	 * 			http
+	 * 				.authorizeRequests()
+	 * 					.anyRequest().authenticated()
+	 * 					.and()
+	 * 				  .oauth2Login();
+	 *		}
+	 *	}
 	 *
 	 *	@Bean
 	 *	public ClientRegistrationRepository clientRegistrationRepository() {
-	 *		// ClientRegistrationRepositoryImpl must be composed of at least one ClientRegistration instance
-	 *		return new ClientRegistrationRepositoryImpl();
+	 *		return new InMemoryClientRegistrationRepository(this.googleClientRegistration());
+	 *	}
+	 *
+	 * 	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();
 	 *	}
 	 * }
 	 *
* - * The following shows the configuration options available for customizing the defaults. - * - * 
-	 * @EnableWebSecurity
-	 * public class OAuth2LoginSecurityConfig extends WebSecurityConfigurerAdapter {
-	 *
-	 * 	@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"));
-	 * 	}
-	 *
-	 *	@Bean
-	 *	public ClientRegistrationRepository clientRegistrationRepository() {
-	 *		// ClientRegistrationRepositoryImpl must be composed of at least one ClientRegistration instance
-	 *		return new ClientRegistrationRepositoryImpl();
-	 *	}
-	 *
-	 * 	@Bean
-	 * 	public AuthorizationRequestUriBuilder authorizationRequestUriBuilder() {
-	 * 		// Custom URI builder for the "Authorization Request"
-	 * 		return new AuthorizationRequestUriBuilderImpl();
-	 * 	}
-	 *
-	 * 	@Bean
-	 * 	public OAuth2AccessTokenResponseClient<OAuth2LoginAuthenticationToken> accessTokenResponseClient() {
-	 * 		// Custom implementation that exchanges an "Authorization Code Grant" for an "Access Token"
-	 * 		return new AuthorizationCodeTokenExchangerImpl();
-	 * 	}
-	 *
-	 * 	@Bean
-	 * 	public OAuth2UserService userInfoService() {
-	 * 		// Custom implementation that retrieves the details of the authenticated user at the "UserInfo Endpoint"
-	 * 		return new OAuth2UserServiceImpl();
-	 * 	}
-	 *
-	 * 	@Bean
-	 * 	public Converter<ClientHttpResponse, UserInfo> userInfoConverter() {
-	 * 		// Default converter implementation for UserInfo
-	 * 		return new org.springframework.security.oauth2.client.user.converter.UserInfoConverter();
-	 * 	}
-	 * }
-	 *
+ *

+ * For more advanced configuration, see {@link OAuth2LoginConfigurer} for available options to customize the defaults. * * @author Joe Grandja * @since 5.0 - * @see Section 4.1 Authorization Code Grant Flow - * @see Section 4.1.1 Authorization Request - * @see Section 4.1.2 Authorization Response + * @see Section 4.1 Authorization Code Grant + * @see Section 3.1 Authorization Code Flow * @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 */