跳到主要内容
版本：7.0.2

安全 HTTP 响应头

DeepSeek V3 中英对照 Headers Security HTTP Response Headers

您可以使用安全HTTP响应头来增强Web应用程序的安全性。本节专门介绍基于WebFlux的安全HTTP响应头支持。

默认安全头部​

Spring Security 提供了一套默认的安全HTTP响应头集，以提供安全的默认配置。虽然这些响应头都被视为最佳实践，但需要注意的是，并非所有客户端都会使用这些响应头，因此建议进行额外的测试。

您可以自定义特定的响应头。例如，假设您希望使用默认设置，但希望为 X-Frame-Options 指定 SAMEORIGIN。

您可以通过以下配置实现：

@Bean
SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
	http
		// ...
		.headers((headers) -> headers
			.frameOptions((frameOptions) -> frameOptions
				.mode(Mode.SAMEORIGIN)
			)
		);
	return http.build();
}

如果您不希望添加默认配置，并希望明确控制应使用的内容，可以禁用默认设置：

@Bean
SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
	http
		// ...
		.headers((headers) -> headers.disable());
	return http.build();
}

缓存控制​

Spring Security 默认包含缓存控制头部。

然而，如果您确实希望缓存特定响应，您的应用程序可以有选择地将它们添加到 ServerHttpResponse 中，以覆盖 Spring Security 设置的标头。这对于确保 CSS、JavaScript 和图像等内容被正确缓存非常有用。

在使用Spring WebFlux时，通常会在配置中进行相关设置。具体操作方法可参阅Spring参考文档的静态资源章节。

如有必要，您也可以禁用Spring Security的缓存控制HTTP响应头。

@Bean
SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
	http
		// ...
		.headers((headers) -> headers
			.cache((cache) -> cache.disable())
		);
	return http.build();
}

Content Type Options​

默认情况下，Spring Security 包含 Content-Type 头部。但您也可以禁用它：

@Bean
SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
	http
		// ...
		.headers((headers) -> headers
			.contentTypeOptions((contentTypeOptions) -> contentTypeOptions.disable())
		);
	return http.build();
}

HTTP 严格传输安全（HSTS）​

默认情况下，Spring Security 提供 Strict Transport Security 头部。但是，你可以显式地自定义结果。例如，以下示例显式地提供了 HSTS：

@Bean
SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
	http
		// ...
		.headers((headers) -> headers
			.hsts((hsts) -> hsts
				.includeSubdomains(true)
				.preload(true)
				.maxAge(Duration.ofDays(365))
			)
		);
	return http.build();
}

X-Frame-Options​

默认情况下，Spring Security 通过使用 X-Frame-Options 来禁止在 iframe 内进行渲染。

您可以自定义框架选项以使用相同的来源：

@Bean
SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
	http
		// ...
		.headers((headers) -> headers
			.frameOptions((frameOptions) -> frameOptions
				.mode(SAMEORIGIN)
			)
		);
	return http.build();
}

X-XSS-Protection​

默认情况下，Spring Security 通过使用 <<headers-xss-protection,X-XSS-Protection header> 来指示浏览器禁用 XSS 审计器。你也可以完全禁用 X-XSS-Protection 头部：

@Bean
SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
	http
		// ...
		.headers((headers) -> headers
			.xssProtection((xssProtection) -> xssProtection.disable())
		);
	return http.build();
}

您也可以更改标头值：

@Bean
SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
	http
		// ...
		.headers((headers) -> headers
			.xssProtection((xssProtection) -> xssProtection.headerValue(XXssProtectionServerHttpHeadersWriter.HeaderValue.ENABLED_MODE_BLOCK))
		);
	return http.build();
}

内容安全策略 (CSP)​

默认情况下，Spring Security 不会添加内容安全策略，因为在不了解应用程序上下文的情况下，无法确定合理的默认策略。Web 应用程序的作者必须声明要强制执行和/或监控受保护资源的安全策略。

例如，考虑以下安全策略：

Content-Security-Policy: script-src 'self' https://trustedscripts.example.com; object-src https://trustedplugins.example.com; report-uri /csp-report-endpoint/

根据前述策略，您可以启用CSP头：

@Bean
SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
	http
		// ...
		.headers((headers) -> headers
			.contentSecurityPolicy((policy) -> policy
				.policyDirectives("script-src 'self' https://trustedscripts.example.com; object-src https://trustedplugins.example.com; report-uri /csp-report-endpoint/")
			)
		);
	return http.build();
}

要启用 CSP report-only 标头，请提供以下配置：

@Bean
SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
	http
		// ...
		.headers((headers) -> headers
			.contentSecurityPolicy((policy) -> policy
				.policyDirectives("script-src 'self' https://trustedscripts.example.com; object-src https://trustedplugins.example.com; report-uri /csp-report-endpoint/")
				.reportOnly()
			)
		);
	return http.build();
}

Referrer Policy​

Spring Security 默认添加 Referrer Policy 头部，其指令为 no-referrer。你可以通过如下配置来更改 Referrer Policy 头部：

@Bean
SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
	http
		// ...
		.headers((headers) -> headers
			.referrerPolicy((referrer) -> referrer
				.policy(ReferrerPolicy.SAME_ORIGIN)
			)
		);
	return http.build();
}

功能策略​

默认情况下，Spring Security 不会添加 Feature Policy 头信息。请参考以下 Feature-Policy 头信息示例：

Feature-Policy: geolocation 'self'

您可以启用上述功能策略头：

@Bean
SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
	http
		// ...
		.headers((headers) -> headers
			.featurePolicy("geolocation 'self'")
		);
	return http.build();
}

权限策略​

默认情况下，Spring Security 不会添加 Permissions Policy 标头。请考虑以下 Permissions-Policy 标头：

Permissions-Policy: geolocation=(self)

您可以启用上述权限策略头：

@Bean
SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
	http
		// ...
		.headers((headers) -> headers
			.permissionsPolicy((permissions) -> permissions
				.policy("geolocation=(self)")
			)
		);
	return http.build();
}

清除站点数据​

默认情况下，Spring Security 不会添加 Clear-Site-Data 头部。请参考以下 Clear-Site-Data 头部示例：

Clear-Site-Data: "cache", "cookies"

您可以在登出时发送 Clear-Site-Data 标头：

@Bean
SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
	ServerLogoutHandler securityContext = new SecurityContextServerLogoutHandler();
	ClearSiteDataServerHttpHeadersWriter writer = new ClearSiteDataServerHttpHeadersWriter(CACHE, COOKIES);
	ServerLogoutHandler clearSiteData = new HeaderWriterServerLogoutHandler(writer);
	DelegatingServerLogoutHandler logoutHandler = new DelegatingServerLogoutHandler(securityContext, clearSiteData);

	http
		// ...
		.logout()
			.logoutHandler(logoutHandler);
	return http.build();
}