diff --git a/docs/manual/src/docs/asciidoc/_includes/reactive/index.adoc b/docs/manual/src/docs/asciidoc/_includes/reactive/index.adoc index 0c6425a254..1044149999 100644 --- a/docs/manual/src/docs/asciidoc/_includes/reactive/index.adoc +++ b/docs/manual/src/docs/asciidoc/_includes/reactive/index.adoc @@ -2,6 +2,8 @@ include::webflux.adoc[leveloffset=+1] +include::oauth2/index.adoc[leveloffset=+1] + include::webclient.adoc[leveloffset=+1] include::method.adoc[leveloffset=+1] diff --git a/docs/manual/src/docs/asciidoc/_includes/reactive/oauth2/index.adoc b/docs/manual/src/docs/asciidoc/_includes/reactive/oauth2/index.adoc new file mode 100644 index 0000000000..cd10b1223c --- /dev/null +++ b/docs/manual/src/docs/asciidoc/_includes/reactive/oauth2/index.adoc @@ -0,0 +1,5 @@ += OAuth2 WebFlux + +Spring Security provides OAuth2 and WebFlux integration for reactive applications. + +include::login.adoc[leveloffset+=1] diff --git a/docs/manual/src/docs/asciidoc/_includes/reactive/oauth2/login.adoc b/docs/manual/src/docs/asciidoc/_includes/reactive/oauth2/login.adoc new file mode 100644 index 0000000000..65434a5bc1 --- /dev/null +++ b/docs/manual/src/docs/asciidoc/_includes/reactive/oauth2/login.adoc @@ -0,0 +1,154 @@ +[[webflux-oauth2-login]] += OAuth 2.0 Login + +The OAuth 2.0 Login feature provides an application with the capability to have users log in to the application by using their existing account at an OAuth 2.0 Provider (e.g. +GitHub) or OpenID Connect 1.0 Provider (such as Google). +OAuth 2.0 Login implements the use cases: "Login with Google" or "Login with GitHub". + +NOTE: OAuth 2.0 Login is implemented by using the *Authorization Code Grant*, as specified in the https://tools.ietf.org/html/rfc6749#section-4.1[OAuth 2.0 Authorization Framework] and http://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth[OpenID Connect Core 1.0]. + +[[webflux-oauth2-login-sample]] +== Spring Boot 2.0 Sample + +Spring Boot 2.0 brings full auto-configuration capabilities for OAuth 2.0 Login. + +This section shows how to configure the {gh-samples-url}/boot/oauth2login-webflux[*OAuth 2.0 Login WebFlux sample*] using _Google_ as the _Authentication Provider_ and covers the following topics: + +* <> +* <> +* <> +* <> + + +[[webflux-oauth2-login-sample-setup]] +=== Initial setup + +To use Google's OAuth 2.0 authentication system for login, you must set up a project in the Google API Console to obtain OAuth 2.0 credentials. + +NOTE: https://developers.google.com/identity/protocols/OpenIDConnect[Google's OAuth 2.0 implementation] for authentication conforms to the http://openid.net/connect/[OpenID Connect 1.0] specification and is http://openid.net/certification/[OpenID Certified]. + +Follow the instructions on the https://developers.google.com/identity/protocols/OpenIDConnect[OpenID Connect] page, starting in the section, "Setting up OAuth 2.0". + +After completing the "Obtain OAuth 2.0 credentials" instructions, you should have a new OAuth Client with credentials consisting of a Client ID and a Client Secret. + +[[webflux-oauth2-login-sample-redirect]] +=== Setting the redirect URI + +The redirect URI is the path in the application that the end-user's user-agent is redirected back to after they have authenticated with Google and have granted access to the OAuth Client _(<>)_ on the Consent page. + +In the "Set a redirect URI" sub-section, ensure that the *Authorized redirect URIs* field is set to `http://localhost:8080/login/oauth2/code/google`. + +TIP: The default redirect URI template is `{baseUrl}/login/oauth2/code/{registrationId}`. +The *_registrationId_* is a unique identifier for the <>. +For our example, the `registrationId` is `google`. + +[[webflux-oauth2-login-sample-config]] +=== Configure `application.yml` + +Now that you have a new OAuth Client with Google, you need to configure the application to use the OAuth Client for the _authentication flow_. +To do so: + +. Go to `application.yml` and set the following configuration: ++ +[source,yaml] +---- +spring: + security: + oauth2: + client: + registration: <1> + google: <2> + client-id: google-client-id + client-secret: google-client-secret +---- ++ +.OAuth Client properties +==== +<1> `spring.security.oauth2.client.registration` is the base property prefix for OAuth Client properties. +<2> Following the base property prefix is the ID for the <>, such as google. +==== + +. Replace the values in the `client-id` and `client-secret` property with the OAuth 2.0 credentials you created earlier. + + +[[webflux-oauth2-login-sample-start]] +=== Boot up the application + +Launch the Spring Boot 2.0 sample and go to `http://localhost:8080`. +You are then redirected to the default _auto-generated_ login page, which displays a link for Google. + +Click on the Google link, and you are then redirected to Google for authentication. + +After authenticating with your Google account credentials, the next page presented to you is the Consent screen. +The Consent screen asks you to either allow or deny access to the OAuth Client you created earlier. +Click *Allow* to authorize the OAuth Client to access your email address and basic profile information. + +At this point, the OAuth Client retrieves your email address and basic profile information from the http://openid.net/specs/openid-connect-core-1_0.html#UserInfo[UserInfo Endpoint] and establishes an authenticated session. + +[[webflux-oauth2-login-openid-provider-configuration]] +== Using OpenID Provider Configuration + +For well known providers, Spring Security provides the necessary defaults for the OAuth Authorization Provider's configuration. +If you are working with your own Authorization Provider that supports https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfig[OpenID Provider Configuration], you may use the https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationResponse[OpenID Provider Configuration Response] the issuer-uri can be used to configure the application. + +[source,yml] +---- +spring: + security: + oauth2: + client: + provider: + keycloak: + issuer-uri: https://idp.example.com/auth/realms/demo + registration: + keycloak: + client-id: spring-security + client-secret: 6cea952f-10d0-4d00-ac79-cc865820dc2c +---- + +The `issuer-uri` instructs Spring Security to leverage the endpoint at `https://idp.example.com/auth/realms/demo/.well-known/openid-configuration` to discover the configuration. +The `client-id` and `client-secret` are linked to the provider because `keycloak` is used for both the provider and the registration. + + +[[webflux-oauth2-login-explicit]] +== Explicit OAuth2 Login Configuration + +A minimal OAuth2 Login configuration is shown below: + +[source,java] +---- +@Bean +ReactiveClientRegistrationRepository clientRegistrations() { + ClientRegistration clientRegistration = ClientRegistrations + .fromOidcIssuerLocation("https://idp.example.com/auth/realms/demo") + .clientId("spring-security") + .clientSecret("6cea952f-10d0-4d00-ac79-cc865820dc2c") + .build(); + return new InMemoryReactiveClientRegistrationRepository(clientRegistration); +} + +@Bean +SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) { + http + // ... + .oauth2Login(); + return http.build(); +} +---- + +Additional configuration options can be seen below: + +[source,java] +---- +@Bean +SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) { + http + // ... + .oauth2Login() + .authenticationConverter(converter) + .authenticationManager(manager) + .authorizedClientRepository(authorizedClients) + .clientRegistrationRepository(clientRegistrations); + return http.build(); +} +----