Reactive Migrations (Reactive Migrations) | Spring Security5.8.14中文文档|Spring官方文档|SpringBoot 教程|Spring中文网

For the latest stable version, please use Spring Security 6.3.3!spring-doc.cn

If you have already performed the initial migration steps for your Reactive application, you’re now ready to perform steps specific to Reactive applications.spring-doc.cn

Exploit Protection Migrations

The following steps relate to changes around how to configure CSRF.spring-doc.cn

Configure `tokenFromMultipartDataEnabled`

In Spring Security 5.8, the method tokenFromMultipartDataEnabled was deprecated in favor of ServerCsrfTokenRequestAttributeHandler#setTokenFromMultipartDataEnabled.spring-doc.cn

To address the deprecation, the following code:spring-doc.cn

Configure tokenFromMultipartDataEnabled with DSL

Javaspring-doc.cn
Kotlinspring-doc.cn

@Bean
SecurityWebFilterChain securityWebFilterChain(ServerHttpSecurity http) {
	http
		// ...
		.csrf((csrf) -> csrf
			.tokenFromMultipartDataEnabled(true)
		);
	return http.build();
}

@Bean
open fun securityWebFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
	return http {
		// ...
		csrf {
			tokenFromMultipartDataEnabled = true
		}
	}
}

can be replaced with:spring-doc.cn

Configure tokenFromMultipartDataEnabled with ServerCsrfTokenRequestAttributeHandler

Javaspring-doc.cn
Kotlinspring-doc.cn

@Bean
SecurityWebFilterChain securityWebFilterChain(ServerHttpSecurity http) {
	ServerCsrfTokenRequestAttributeHandler requestHandler = new ServerCsrfTokenRequestAttributeHandler();
	requestHandler.setTokenFromMultipartDataEnabled(true);
	http
		// ...
		.csrf((csrf) -> csrf
			.csrfTokenRequestHandler(requestHandler)
		);
	return http.build();
}

@Bean
open fun securityWebFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
	val requestHandler = ServerCsrfTokenRequestAttributeHandler()
	requestHandler.tokenFromMultipartDataEnabled = true
	return http {
		// ...
		csrf {
			csrfTokenRequestHandler = requestHandler
		}
	}
}

Protect against CSRF BREACH

You can opt into Spring Security 6’s default support for BREACH protection of the CsrfToken using the following configuration:spring-doc.cn

CsrfToken BREACH Protection

Javaspring-doc.cn
Kotlinspring-doc.cn

@Bean
SecurityWebFilterChain securityWebFilterChain(ServerHttpSecurity http) {
	XorServerCsrfTokenRequestAttributeHandler requestHandler = new XorServerCsrfTokenRequestAttributeHandler();
	// ...
	http
		// ...
		.csrf((csrf) -> csrf
			.csrfTokenRequestHandler(requestHandler)
		);
	return http.build();
}

@Bean
open fun securityWebFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
	val requestHandler = XorServerCsrfTokenRequestAttributeHandler()
	// ...
	return http {
		// ...
		csrf {
			csrfTokenRequestHandler = requestHandler
		}
	}
}

Opt-out Steps

If configuring CSRF BREACH protection gives you trouble, take a look at these scenarios for optimal opt out behavior:spring-doc.cn

I am using AngularJS or another Javascript framework

If you are using AngularJS and the HttpClientXsrfModule (or a similar module in another framework) along with CookieServerCsrfTokenRepository.withHttpOnlyFalse(), you may find that automatic support no longer works.spring-doc.cn

In this case, you can configure Spring Security to validate the raw CsrfToken from the cookie while keeping CSRF BREACH protection of the response using a custom ServerCsrfTokenRequestHandler with delegation, like so:spring-doc.cn

Configure CsrfToken BREACH Protection to validate raw tokens

Javaspring-doc.cn
Kotlinspring-doc.cn

@Bean
SecurityWebFilterChain securityWebFilterChain(ServerHttpSecurity http) {
	CookieServerCsrfTokenRepository tokenRepository = CookieServerCsrfTokenRepository.withHttpOnlyFalse();
	XorServerCsrfTokenRequestAttributeHandler delegate = new XorServerCsrfTokenRequestAttributeHandler();
	// Use only the handle() method of XorServerCsrfTokenRequestAttributeHandler and the
	// default implementation of resolveCsrfTokenValue() from ServerCsrfTokenRequestHandler
	ServerCsrfTokenRequestHandler requestHandler = delegate::handle;
	http
		// ...
		.csrf((csrf) -> csrf
			.csrfTokenRepository(tokenRepository)
			.csrfTokenRequestHandler(requestHandler)
		);

	return http.build();
}

@Bean
WebFilter csrfCookieWebFilter() {
	return (exchange, chain) -> {
		Mono<CsrfToken> csrfToken = exchange.getAttributeOrDefault(CsrfToken.class.getName(), Mono.empty());
		return csrfToken.doOnSuccess(token -> {
			/* Ensures the token is subscribed to. */
		}).then(chain.filter(exchange));
	};
}

@Bean
open fun securityWebFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
	val tokenRepository = CookieServerCsrfTokenRepository.withHttpOnlyFalse()
	val delegate = XorServerCsrfTokenRequestAttributeHandler()
	// Use only the handle() method of XorServerCsrfTokenRequestAttributeHandler and the
	// default implementation of resolveCsrfTokenValue() from ServerCsrfTokenRequestHandler
	val requestHandler = ServerCsrfTokenRequestHandler(delegate::handle)
	return http.invoke {
		// ...
		csrf {
			csrfTokenRepository = tokenRepository
			csrfTokenRequestHandler = requestHandler
		}
	}
}

@Bean
fun csrfCookieWebFilter(): WebFilter {
	return WebFilter { exchange, chain ->
		val csrfToken = exchange.getAttribute<Mono<CsrfToken>>(CsrfToken::class.java.name) ?: Mono.empty()
		csrfToken.doOnSuccess {
            /* Ensures the token is subscribed to. */
		}.then(chain.filter(exchange))
	}
}

I need to opt out of CSRF BREACH protection for another reason

If CSRF BREACH protection does not work for you for another reason, you can opt out using the following configuration:spring-doc.cn

Opt out of CsrfToken BREACH protection

Javaspring-doc.cn
Kotlinspring-doc.cn

@Bean
SecurityWebFilterChain securityWebFilterChain(ServerHttpSecurity http) {
	ServerCsrfTokenRequestAttributeHandler requestHandler = new ServerCsrfTokenRequestAttributeHandler();
	http
		// ...
		.csrf((csrf) -> csrf
			.csrfTokenRequestHandler(requestHandler)
		);
	return http.build();
}

@Bean
open fun securityWebFilterChain(http: ServerHttpSecurity): SecurityWebFilterChain {
	val requestHandler = ServerCsrfTokenRequestAttributeHandler()
	return http {
		// ...
		csrf {
			csrfTokenRequestHandler = requestHandler
		}
	}
}

Use `AuthorizationManager` for Method Security

Method Security has been improved through the AuthorizationManager API and direct use of Spring AOP.spring-doc.cn

Should you run into trouble with making these changes, you can follow the opt out steps at the end of this section.spring-doc.cn

In Spring Security 5.8, useAuthorizationManager was added to @EnableReactiveMethodSecurity to allow applications to opt in to AuthorizationManager's features.spring-doc.cn

Change `useAuthorizationManager` to `true`

To opt in, change useAuthorizationManager to true like so:spring-doc.cn

Javaspring-doc.cn
Kotlinspring-doc.cn

@EnableReactiveMethodSecurity

@EnableReactiveMethodSecurity

changes to:spring-doc.cn

Javaspring-doc.cn
Kotlinspring-doc.cn

@EnableReactiveMethodSecurity(useAuthorizationManager = true)

@EnableReactiveMethodSecurity(useAuthorizationManager = true)

Check for `AnnotationConfigurationException`s

useAuthorizationManager activates stricter enforcement of Spring Security’s non-repeatable or otherwise incompatible annotations. If after turning on useAuthorizationManager you see AnnotationConfigurationExceptions in your logs, follow the instructions in the exception message to clean up your application’s method security annotation usage.spring-doc.cn

Opt-out Steps

If you ran into trouble with AuthorizationManager for reactive method security, you can opt out by changing:spring-doc.cn

Javaspring-doc.cn
Kotlinspring-doc.cn

@EnableReactiveMethodSecurity

@EnableReactiveMethodSecurity

to:spring-doc.cn

Javaspring-doc.cn
Kotlinspring-doc.cn

@EnableReactiveMethodSecurity(useAuthorizationManager = false)

@EnableReactiveMethodSecurity(useAuthorizationManager = false)

Propagate `AuthenticationServiceException`s

AuthenticationFilter propagates AuthenticationServiceExceptions to the ServerAuthenticationEntryPoint. Because AuthenticationServiceExceptions represent a server-side error instead of a client-side error, in 6.0, this changes to propagate them to the container.spring-doc.cn

Configure `ServerAuthenticationFailureHandler` to rethrow `AuthenticationServiceException`s

To prepare for the 6.0 default, httpBasic and oauth2ResourceServer should be configured to rethrow AuthenticationServiceExceptions.spring-doc.cn

For each, construct the appropriate authentication entry point for httpBasic and for oauth2ResourceServer:spring-doc.cn

Javaspring-doc.cn
Kotlinspring-doc.cn

ServerAuthenticationEntryPoint bearerEntryPoint = new BearerTokenServerAuthenticationEntryPoint();
ServerAuthenticationEntryPoint basicEntryPoint = new HttpStatusServerEntryPoint(HttpStatus.UNAUTHORIZED);

val bearerEntryPoint: ServerAuthenticationEntryPoint = BearerTokenServerAuthenticationEntryPoint()
val basicEntryPoint: ServerAuthenticationEntryPoint = HttpStatusServerEntryPoint(HttpStatus.UNAUTHORIZED)

If you use a custom AuthenticationEntryPoint for either or both mechanisms, use that one instead for the remaining steps.spring-doc.cn

Then, construct and configure a ServerAuthenticationEntryPointFailureHandler for each one:spring-doc.cn

Javaspring-doc.cn
Kotlinspring-doc.cn

AuthenticationFailureHandler bearerFailureHandler = new ServerAuthenticationEntryPointFailureHandler(bearerEntryPoint);
bearerFailureHandler.setRethrowAuthenticationServiceException(true);
AuthenticationFailureHandler basicFailureHandler = new ServerAuthenticationEntryPointFailureHandler(basicEntryPoint);
basicFailureHandler.setRethrowAuthenticationServiceException(true)

val bearerFailureHandler: AuthenticationFailureHandler = ServerAuthenticationEntryPointFailureHandler(bearerEntryPoint)
bearerFailureHandler.setRethrowAuthenticationServiceException(true)
val basicFailureHandler: AuthenticationFailureHandler = ServerAuthenticationEntryPointFailureHandler(basicEntryPoint)
basicFailureHandler.setRethrowAuthenticationServiceException(true)

Finally, wire each authentication failure handler into the DSL, like so:spring-doc.cn

Javaspring-doc.cn
Kotlinspring-doc.cn

http
    .httpBasic((basic) -> basic.authenticationFailureHandler(basicFailureHandler))
    .oauth2ResourceServer((oauth2) -> oauth2.authenticationFailureHandler(bearerFailureHandler))

http {
    httpBasic {
        authenticationFailureHandler = basicFailureHandler
    }
    oauth2ResourceServer {
        authenticationFailureHandler = bearerFailureHandler
    }
}

Opt-out Steps

To opt-out of the 6.0 defaults and instead continue to pass AuthenticationServiceException on to ServerAuthenticationEntryPoints, you can follow the same steps as above, except set rethrowAuthenticationServiceException to false.spring-doc.cn

If you use a custom AuthenticationEntryPoint for either or both mechanisms, use that one instead for the remaining steps.spring-doc.cn

Add `@Configuration` annotation

In 6.0, @Configuration is removed from @EnableWebFluxSecurity and @EnableReactiveMethodSecurity.spring-doc.cn

To prepare for this, wherever you are using one of these annotations, you may need to add @Configuration. For example, @EnableReactiveMethodSecurity changes from:spring-doc.cn

Javaspring-doc.cn

@EnableReactiveMethodSecurity
public class MyConfiguration {
	// ...
}

Kotlinspring-doc.cn

@EnableReactiveMethodSecurity
open class MyConfiguration {
	// ...
}

to:spring-doc.cn

Javaspring-doc.cn

@Configuration
@EnableReactiveMethodSecurity
public class MyConfiguration {
	// ...
}

Kotlinspring-doc.cn

@Configuration
@EnableReactiveMethodSecurity
open class MyConfiguration {
	// ...
}

Address OAuth2 Client Deprecations

`ServerOAuth2AuthorizedClientExchangeFilterFunction`

The method setAccessTokenExpiresSkew(…) can be replaced with one of:spring-doc.cn

ClientCredentialsReactiveOAuth2AuthorizedClientProvider#setClockSkew(…)spring-doc.cn
RefreshTokenReactiveOAuth2AuthorizedClientProvider#setClockSkew(…)spring-doc.cn
JwtBearerReactiveOAuth2AuthorizedClientProvider#setClockSkew(…)spring-doc.cn

The method setClientCredentialsTokenResponseClient(…) can be replaced with the constructor ServerOAuth2AuthorizedClientExchangeFilterFunction(ReactiveOAuth2AuthorizedClientManager).spring-doc.cn

See Client Credentials for more information.spring-doc.cn

`WebSessionOAuth2ServerAuthorizationRequestRepository`

The method setAllowMultipleAuthorizationRequests(…) has no direct replacement.spring-doc.cn

`UnAuthenticatedServerOAuth2AuthorizedClientRepository`

The class UnAuthenticatedServerOAuth2AuthorizedClientRepository has no direct replacement. Usage of the class can be replaced with AuthorizedClientServiceReactiveOAuth2AuthorizedClientManager.spring-doc.cn

See Client Credentials for more information.spring-doc.cn

Add `@Configuration` to `@Enable*` annotations

In 6.0, all Spring Security’s @Enable* annotations had their @Configuration removed. While convenient, it was not consistent with the rest of the Spring projects and most notably Spring Framework’s @Enable* annotations. Additionally, the introduction of support for @Configuration(proxyBeanMethods=false) in Spring Framework provides another reason to remove @Configuration meta-annotation from Spring Security’s @Enable* annotations and allow users to opt into their preferred configuration mode.spring-doc.cn

The following annotations had their @Configuration removed:spring-doc.cn

@EnableGlobalAuthenticationspring-doc.cn
@EnableGlobalMethodSecurityspring-doc.cn
@EnableMethodSecurityspring-doc.cn
@EnableReactiveMethodSecurityspring-doc.cn
@EnableWebSecurityspring-doc.cn
@EnableWebFluxSecurityspring-doc.cn

For example, if you are using @EnableWebFluxSecurity, you will need to change:spring-doc.cn

Javaspring-doc.cn

@EnableWebFluxSecurity
public class SecurityConfig {
	// ...
}

to:spring-doc.cn

Javaspring-doc.cn

@Configuration
@EnableWebFluxSecurity
public class SecurityConfig {
	// ...
}

And the same applies to every other annotation listed above.spring-doc.cn

Exploit Protection Migrations

Configure tokenFromMultipartDataEnabled

Protect against CSRF BREACH

Opt-out Steps

I am using AngularJS or another Javascript framework

I need to opt out of CSRF BREACH protection for another reason

Use AuthorizationManager for Method Security

Change useAuthorizationManager to true

Check for AnnotationConfigurationExceptions

Opt-out Steps

Propagate AuthenticationServiceExceptions

Configure ServerAuthenticationFailureHandler to rethrow AuthenticationServiceExceptions

Opt-out Steps

Add @Configuration annotation

Address OAuth2 Client Deprecations

ServerOAuth2AuthorizedClientExchangeFilterFunction

WebSessionOAuth2ServerAuthorizationRequestRepository

UnAuthenticatedServerOAuth2AuthorizedClientRepository

Add @Configuration to @Enable* annotations

Configure `tokenFromMultipartDataEnabled`

Use `AuthorizationManager` for Method Security

Change `useAuthorizationManager` to `true`

Check for `AnnotationConfigurationException`s

Propagate `AuthenticationServiceException`s

Configure `ServerAuthenticationFailureHandler` to rethrow `AuthenticationServiceException`s

Add `@Configuration` annotation

`ServerOAuth2AuthorizedClientExchangeFilterFunction`

`WebSessionOAuth2ServerAuthorizationRequestRepository`

`UnAuthenticatedServerOAuth2AuthorizedClientRepository`

Add `@Configuration` to `@Enable*` annotations