org.springframework.security.config.web.server

Class ServerHttpSecurity

java.lang.Object

org.springframework.security.config.web.server.ServerHttpSecurity

public class ServerHttpSecurity
extends java.lang.Object

A ServerHttpSecurity is similar to Spring Security's HttpSecurity but for WebFlux. It allows configuring web based security for specific http requests. By default it will be applied to all requests, but can be restricted using securityMatcher(ServerWebExchangeMatcher) or other similar methods. A minimal configuration can be found below:

 @EnableWebFluxSecurity
 public class MyMinimalSecurityConfiguration {

     @Bean
     public MapReactiveUserDetailsService userDetailsService() {
          UserDetails user = User.withDefaultPasswordEncoder()
               .username("user")
               .password("password")
               .roles("USER")
               .build();
          return new MapReactiveUserDetailsService(user);
     }
 }

 Below is the same as our minimal configuration, but explicitly declaring the
 ServerHttpSecurity.

 
 @EnableWebFluxSecurity
 public class MyExplicitSecurityConfiguration {
     @Bean
     public SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
          http
               .authorizeExchange()
                    .anyExchange().authenticated()
                         .and()
                    .httpBasic().and()
                    .formLogin();
          return http.build();
     }

     @Bean
     public MapReactiveUserDetailsService userDetailsService() {
          UserDetails user = User.withDefaultPasswordEncoder()
               .username("user")
               .password("password")
               .roles("USER")
               .build();
          return new MapReactiveUserDetailsService(user);
     }
 }

Since:

5.0

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	ServerHttpSecurity.AnonymousSpec Configures anonymous authentication
class	ServerHttpSecurity.AuthorizeExchangeSpec Configures authorization
class	ServerHttpSecurity.CorsSpec Configures CORS support within Spring Security.
class	ServerHttpSecurity.CsrfSpec Configures CSRF Protection
class	ServerHttpSecurity.ExceptionHandlingSpec Configures exception handling
class	ServerHttpSecurity.FormLoginSpec Configures Form Based authentication
class	ServerHttpSecurity.HeaderSpec Configures HTTP Response Headers.
class	ServerHttpSecurity.HttpBasicSpec Configures HTTP Basic Authentication
class	ServerHttpSecurity.HttpsRedirectSpec Configures HTTPS redirection rules
class	ServerHttpSecurity.LogoutSpec Configures log out
class	ServerHttpSecurity.OAuth2ClientSpec
class	ServerHttpSecurity.OAuth2LoginSpec
class	ServerHttpSecurity.OAuth2ResourceServerSpec Configures OAuth2 Resource Server Support
class	ServerHttpSecurity.RequestCacheSpec Configures the request cache which is used when a flow is interrupted (i.e.
class	ServerHttpSecurity.X509Spec Configures X509 authentication

Constructor Summary

Constructors

Modifier	Constructor and Description
protected	ServerHttpSecurity()

Method Summary

Modifier and Type	Method and Description
ServerHttpSecurity	addFilterAfter(org.springframework.web.server.WebFilter webFilter, SecurityWebFiltersOrder order) Adds a WebFilter after specific position.
ServerHttpSecurity	addFilterAt(org.springframework.web.server.WebFilter webFilter, SecurityWebFiltersOrder order) Adds a WebFilter at a specific position.
ServerHttpSecurity	addFilterBefore(org.springframework.web.server.WebFilter webFilter, SecurityWebFiltersOrder order) Adds a WebFilter before specific position.
ServerHttpSecurity.AnonymousSpec	anonymous() Enables and Configures anonymous authentication.
ServerHttpSecurity	authenticationManager(ReactiveAuthenticationManager manager) Configure the default authentication manager.
ServerHttpSecurity.AuthorizeExchangeSpec	authorizeExchange() Configures authorization.
SecurityWebFilterChain	build() Builds the SecurityWebFilterChain
ServerHttpSecurity.CorsSpec	cors() Configures CORS headers.
ServerHttpSecurity.CsrfSpec	csrf() Configures CSRF Protection which is enabled by default.
ServerHttpSecurity.ExceptionHandlingSpec	exceptionHandling() Configures exception handling (i.e.
ServerHttpSecurity.FormLoginSpec	formLogin() Configures form based authentication.
ServerHttpSecurity.HeaderSpec	headers() Configures HTTP Response Headers.
static ServerHttpSecurity	http() Creates a new instance.
ServerHttpSecurity.HttpBasicSpec	httpBasic() Configures HTTP Basic authentication.
ServerHttpSecurity.LogoutSpec	logout() Configures log out.
ServerHttpSecurity.OAuth2ClientSpec	oauth2Client() Configures the OAuth2 client.
ServerHttpSecurity.OAuth2LoginSpec	oauth2Login()
ServerHttpSecurity.OAuth2ResourceServerSpec	oauth2ResourceServer()
ServerHttpSecurity.HttpsRedirectSpec	redirectToHttps() Configures HTTPS redirection rules.
ServerHttpSecurity.RequestCacheSpec	requestCache() Configures the request cache which is used when a flow is interrupted (i.e.
ServerHttpSecurity	securityContextRepository(ServerSecurityContextRepository securityContextRepository) The strategy used with ReactorContextWebFilter.
ServerHttpSecurity	securityMatcher(ServerWebExchangeMatcher matcher) The ServerExchangeMatcher that determines which requests apply to this HttpSecurity instance.
protected void	setApplicationContext(org.springframework.context.ApplicationContext applicationContext)
ServerHttpSecurity.X509Spec	x509() Configures x509 authentication using a certificate provided by a client.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

ServerHttpSecurity

protected ServerHttpSecurity()

Method Detail

securityMatcher

public ServerHttpSecurity securityMatcher(ServerWebExchangeMatcher matcher)

The ServerExchangeMatcher that determines which requests apply to this HttpSecurity instance.

Parameters:

matcher - the ServerExchangeMatcher that determines which requests apply to this HttpSecurity instance. Default is all requests.

Returns:

the ServerHttpSecurity to continue configuring

addFilterAt

public ServerHttpSecurity addFilterAt(org.springframework.web.server.WebFilter webFilter,
                                      SecurityWebFiltersOrder order)

Adds a WebFilter at a specific position.

Parameters:

webFilter - the WebFilter to add

order - the place to insert the WebFilter

Returns:

the ServerHttpSecurity to continue configuring

addFilterBefore

public ServerHttpSecurity addFilterBefore(org.springframework.web.server.WebFilter webFilter,
                                          SecurityWebFiltersOrder order)

Adds a WebFilter before specific position.

Parameters:

webFilter - the WebFilter to add

order - the place before which to insert the WebFilter

Returns:

the ServerHttpSecurity to continue configuring

Since:

5.2.0

addFilterAfter

public ServerHttpSecurity addFilterAfter(org.springframework.web.server.WebFilter webFilter,
                                         SecurityWebFiltersOrder order)

Adds a WebFilter after specific position.

Parameters:

webFilter - the WebFilter to add

order - the place after which to insert the WebFilter

Returns:

the ServerHttpSecurity to continue configuring

Since:

5.2.0

securityContextRepository

public ServerHttpSecurity securityContextRepository(ServerSecurityContextRepository securityContextRepository)

The strategy used with ReactorContextWebFilter. It does not impact how the SecurityContext is saved which is configured on a per AuthenticationWebFilter basis.

Parameters:

securityContextRepository - the repository to use

Returns:

the ServerHttpSecurity to continue configuring

redirectToHttps

public ServerHttpSecurity.HttpsRedirectSpec redirectToHttps()

Configures HTTPS redirection rules. If the default is used:

  @Bean
        public SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
            http
                // ...
                .redirectToHttps();
            return http.build();
        }
 

Then all non-HTTPS requests will be redirected to HTTPS. Typically, all requests should be HTTPS; however, the focus for redirection can also be narrowed:

  @Bean
        public SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
            http
                // ...
                .redirectToHttps()
                    .httpsRedirectWhen(serverWebExchange ->
                        serverWebExchange.getRequest().getHeaders().containsKey("X-Requires-Https"))
            return http.build();
        }
 

Returns:

the ServerHttpSecurity.HttpsRedirectSpec to customize

csrf

public ServerHttpSecurity.CsrfSpec csrf()

Configures CSRF Protection which is enabled by default. You can disable it using:

  @Bean
  public SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
      http
          // ...
          .csrf().disabled();
      return http.build();
  }
 

Additional configuration options can be seen below:

  @Bean
  public SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
      http
          // ...
          .csrf()
              // Handle CSRF failures
              .accessDeniedHandler(accessDeniedHandler)
              // Custom persistence of CSRF Token
              .csrfTokenRepository(csrfTokenRepository)
              // custom matching when CSRF protection is enabled
              .requireCsrfProtectionMatcher(matcher);
      return http.build();
  }
 

Returns:

the ServerHttpSecurity.CsrfSpec to customize

cors

public ServerHttpSecurity.CorsSpec cors()

Configures CORS headers. By default if a CorsConfigurationSource Bean is found, it will be used to create a CorsWebFilter. If ServerHttpSecurity.CorsSpec.configurationSource(CorsConfigurationSource) is invoked it will be used instead. If neither has been configured, the Cors configuration will do nothing.

Returns:

the ServerHttpSecurity.CorsSpec to customize

anonymous

public ServerHttpSecurity.AnonymousSpec anonymous()

Enables and Configures anonymous authentication. Anonymous Authentication is disabled by default.

  @Bean
  public SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
      http
          // ...
          .anonymous().key("key")
          .authorities("ROLE_ANONYMOUS");
      return http.build();
  }
 

Returns:

the ServerHttpSecurity.AnonymousSpec to customize

Since:

5.2.0

httpBasic

public ServerHttpSecurity.HttpBasicSpec httpBasic()

Configures HTTP Basic authentication. An example configuration is provided below:

  @Bean
  public SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
      http
          // ...
          .httpBasic()
              // used for authenticating the credentials
              .authenticationManager(authenticationManager)
              // Custom persistence of the authentication
              .securityContextRepository(securityContextRepository);
      return http.build();
  }
 

Returns:

the ServerHttpSecurity.HttpBasicSpec to customize

formLogin

public ServerHttpSecurity.FormLoginSpec formLogin()

Configures form based authentication. An example configuration is provided below:

  @Bean
  public SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
      http
          // ...
          .formLogin()
              // used for authenticating the credentials
              .authenticationManager(authenticationManager)
              // Custom persistence of the authentication
              .securityContextRepository(securityContextRepository)
              // expect a log in page at "/authenticate"
              // a POST "/authenticate" is where authentication occurs
              // error page at "/authenticate?error"
              .formLogin("/authenticate");
      return http.build();
  }
 

Returns:

the ServerHttpSecurity.FormLoginSpec to customize

x509

public ServerHttpSecurity.X509Spec x509()

Configures x509 authentication using a certificate provided by a client.

  @Bean
  public SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
      http
          .x509()
                .authenticationManager(authenticationManager)
              .principalExtractor(principalExtractor);
      return http.build();
  }
 

Note that if extractor is not specified, SubjectDnX509PrincipalExtractor will be used. If authenticationManager is not specified, ReactivePreAuthenticatedAuthenticationManager will be used.

Returns:

the ServerHttpSecurity.X509Spec to customize

Since:

5.2

oauth2Login

public ServerHttpSecurity.OAuth2LoginSpec oauth2Login()

oauth2Client

public ServerHttpSecurity.OAuth2ClientSpec oauth2Client()

Configures the OAuth2 client.

  @Bean
  public SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
      http
          // ...
          .oauth2Client()
              .clientRegistrationRepository(clientRegistrationRepository)
              .authorizedClientRepository(authorizedClientRepository);
      return http.build();
  }
 

Returns:

the ServerHttpSecurity.OAuth2ClientSpec to customize

oauth2ResourceServer

public ServerHttpSecurity.OAuth2ResourceServerSpec oauth2ResourceServer()

headers

public ServerHttpSecurity.HeaderSpec headers()

Configures HTTP Response Headers. The default headers are:

 Cache-Control: no-cache, no-store, max-age=0, must-revalidate
 Pragma: no-cache
 Expires: 0
 X-Content-Type-Options: nosniff
 Strict-Transport-Security: max-age=31536000 ; includeSubDomains
 X-Frame-Options: DENY
 X-XSS-Protection: 1; mode=block
 

such that "Strict-Transport-Security" is only added on secure requests. An example configuration is provided below:

  @Bean
  public SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
      http
          // ...
          .headers()
              // customize frame options to be same origin
              .frameOptions()
                  .mode(XFrameOptionsServerHttpHeadersWriter.Mode.SAMEORIGIN)
                  .and()
              // disable cache control
              .cache().disable();
      return http.build();
  }
 

Returns:

the ServerHttpSecurity.HeaderSpec to customize

exceptionHandling

public ServerHttpSecurity.ExceptionHandlingSpec exceptionHandling()

Configures exception handling (i.e. handles when authentication is requested). An example configuration can be found below:

  @Bean
  public SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
      http
          // ...
          .exceptionHandling()
              // customize how to request for authentication
              .authenticationEntryPoint(entryPoint);
      return http.build();
  }
 

Returns:

the ServerHttpSecurity.ExceptionHandlingSpec to customize

authorizeExchange

public ServerHttpSecurity.AuthorizeExchangeSpec authorizeExchange()

Configures authorization. An example configuration can be found below:

  @Bean
  public SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
      http
          // ...
          .authorizeExchange()
              // any URL that starts with /admin/ requires the role "ROLE_ADMIN"
              .pathMatchers("/admin/**").hasRole("ADMIN")
              // a POST to /users requires the role "USER_POST"
              .pathMatchers(HttpMethod.POST, "/users").hasAuthority("USER_POST")
              // a request to /users/{username} requires the current authentication's username
              // to be equal to the {username}
              .pathMatchers("/users/{username}").access((authentication, context) ->
                  authentication
                      .map(Authentication::getName)
                      .map(username -> username.equals(context.getVariables().get("username")))
                      .map(AuthorizationDecision::new)
              )
              // allows providing a custom matching strategy that requires the role "ROLE_CUSTOM"
              .matchers(customMatcher).hasRole("CUSTOM")
              // any other request requires the user to be authenticated
              .anyExchange().authenticated();
      return http.build();
  }
 

Returns:

the ServerHttpSecurity.AuthorizeExchangeSpec to customize

logout

public ServerHttpSecurity.LogoutSpec logout()

Configures log out. An example configuration can be found below:

  @Bean
  public SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
      http
          // ...
          .logout()
              // configures how log out is done
              .logoutHandler(logoutHandler)
              // log out will be performed on POST /signout
              .logoutUrl("/signout")
              // configure what is done on logout success
              .logoutSuccessHandler(successHandler);
      return http.build();
  }
 

Returns:

the ServerHttpSecurity.LogoutSpec to customize

requestCache

public ServerHttpSecurity.RequestCacheSpec requestCache()

Configures the request cache which is used when a flow is interrupted (i.e. due to requesting credentials) so that the request can be replayed after authentication. An example configuration can be found below:

  @Bean
  public SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
      http
          // ...
          .requestCache()
              // configures how the request is cached
              .requestCache(requestCache);
      return http.build();
  }
 

Returns:

the ServerHttpSecurity.RequestCacheSpec to customize

authenticationManager

public ServerHttpSecurity authenticationManager(ReactiveAuthenticationManager manager)

Configure the default authentication manager.

Parameters:

manager - the authentication manager to use

Returns:

the ServerHttpSecurity to customize

build

public SecurityWebFilterChain build()

Builds the SecurityWebFilterChain

Returns:

the {@link SecurityWebFilterChain

http

public static ServerHttpSecurity http()

Creates a new instance.

Returns:

the new ServerHttpSecurity instance

setApplicationContext

protected void setApplicationContext(org.springframework.context.ApplicationContext applicationContext)
                              throws org.springframework.beans.BeansException

Throws:

org.springframework.beans.BeansException