Cwikius-Spring/spring-security
1
0
Fork 0
mirror of https://github.com/spring-projects/spring-security.git synced 2025-05-30 00:32:14 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update javadoc for HttpSecurity.oauth2Login()

Browse Source 
Fixes gh-4875
This commit is contained in:
Joe Grandja 2017-11-27 13:16:20 -05:00
parent ae664c33b1
commit 3f1b09c248
1 changed files with 53 additions and 111 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -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 Configuration</h2>
*
* <h2>Example Configurations</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;Configuration
* public class OAuth2LoginConfig {
*
* &#064;Override
* protected void configure(HttpSecurity http) throws Exception {
* http
* .authorizeRequests()
* .anyRequest().authenticated()
* .and()
* .oauth2Login();
* }
* &#064;EnableWebSecurity
* public static 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();
* 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();
* }
* }
* </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();
* }
*
* &#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();
* }
* }
* </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
*/