本站内所有文档均为中英对照文档，点击中文可以显示英文。此提醒连续关闭5次后，将不再显示。

文档内容来源于 spring.io，由 springdoc.tech 翻译，版权归属于 SPRING.IO (Broadcom. Inc)。可供个人学习、研究，未经许可，不得进行转载或用于商业行为。

安全 HTTP 响应头

QWen Max 中英对照 Security HTTP Response Headers

你可以使用安全 HTTP 响应头来提高 Web 应用程序的安全性。本节专门介绍基于 servlet 的安全 HTTP 响应头支持。

默认安全头

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

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

你可以通过以下配置来实现：

Java
XML
Kotlin

@Configuration
@EnableWebSecurity
public class WebSecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            // ...
            .headers(headers -> headers
                .frameOptions(frameOptions -> frameOptions
                    .sameOrigin()
                )
            );
        return http.build();
    }
}
java

<http>
    <!-- ... -->

    <headers>
        <frame-options policy="SAMEORIGIN" />
    </headers>
</http>
xml

@Configuration
@EnableWebSecurity
class SecurityConfig {
    @Bean
    open fun filterChain(http: HttpSecurity): SecurityFilterChain {
        http {
            // ...
            headers {
                frameOptions {
                    sameOrigin = true
                }
            }
        }
        return http.build()
    }
}
kotlin

如果你不希望添加默认值，并希望明确控制应使用的内容，你可以禁用默认值。下面的代码示例展示了如何做到这一点。

如果你使用 Spring Security 的配置，以下仅添加缓存控制：

Java
XML
Kotlin

@Configuration
@EnableWebSecurity
public class WebSecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            // ...
            .headers(headers -> headers
                // do not use any default headers unless explicitly listed
                .defaultsDisabled()
                .cacheControl(withDefaults())
            );
        return http.build();
    }
}
java

<http>
    <!-- ... -->

    <headers defaults-disabled="true">
        <cache-control/>
    </headers>
</http>
xml

@Configuration
@EnableWebSecurity
class SecurityConfig {
    @Bean
    open fun filterChain(http: HttpSecurity): SecurityFilterChain {
        http {
            // ...
            headers {
                // do not use any default headers unless explicitly listed
                defaultsDisabled = true
                cacheControl {
                }
            }
        }
        return http.build()
    }
}
kotlin

如果需要，您可以使用以下配置禁用所有HTTP安全响应头：

Java
XML
Kotlin

@Configuration
@EnableWebSecurity
public class WebSecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            // ...
            .headers(headers -> headers.disable());
        return http.build();
    }
}
java

<http>
    <!-- ... -->

    <headers disabled="true" />
</http>
xml

@Configuration
@EnableWebSecurity
class SecurityConfig {
    @Bean
    open fun filterChain(http: HttpSecurity): SecurityFilterChain {
        http {
            // ...
            headers {
                disable()
            }
        }
        return http.build()
    }
}
kotlin

缓存控制

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

但是，如果你确实想要缓存特定的响应，你的应用程序可以有选择地调用 HttpServletResponse.setHeader(String,String) 来覆盖 Spring Security 设置的头信息。你可以使用这种方法来确保内容（如 CSS、JavaScript 和图片）被正确地缓存。

当你使用 Spring Web MVC 时，这通常在你的配置中完成。你可以在 Spring 参考文档的静态资源部分找到如何操作的详细信息。

如果需要，你也可以禁用 Spring Security 的缓存控制 HTTP 响应头。

Java
XML
Kotlin

@Configuration
@EnableWebSecurity
public class WebSecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            // ...
            .headers(headers -> headers
                .cacheControl(cache -> cache.disable())
            );
        return http.build();
    }
}
java

<http>
    <!-- ... -->

    <headers>
        <cache-control disabled="true"/>
    </headers>
</http>
xml

@Configuration
@EnableWebSecurity
class SecurityConfig {

    @Bean
    open fun filterChain(http: HttpSecurity): SecurityFilterChain {
       http {
            headers {
                cacheControl {
                    disable()
                }
            }
        }
        return http.build()
    }
}
kotlin

Content Type Options

Spring Security 默认包含 Content-Type 头。但是，您可以禁用它：

Java
XML
Kotlin

@Configuration
@EnableWebSecurity
public class WebSecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            // ...
            .headers(headers -> headers
                .contentTypeOptions(contentTypeOptions -> contentTypeOptions.disable())
            );
        return http.build();
    }
}
java

<http>
    <!-- ... -->

    <headers>
        <content-type-options disabled="true"/>
    </headers>
</http>
xml

@Configuration
@EnableWebSecurity
class SecurityConfig {

    @Bean
    open fun filterChain(http: HttpSecurity): SecurityFilterChain {
       http {
            headers {
                contentTypeOptions {
                    disable()
                }
            }
        }
        return http.build()
    }
}
kotlin

HTTP 严格传输安全 (HSTS)

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

Java
XML
Kotlin

@Configuration
@EnableWebSecurity
public class WebSecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            // ...
            .headers(headers -> headers
                .httpStrictTransportSecurity(hsts -> hsts
                    .includeSubDomains(true)
                    .preload(true)
                    .maxAgeInSeconds(31536000)
                )
            );
        return http.build();
    }
}
java

<http>
    <!-- ... -->

    <headers>
        <hsts
            include-subdomains="true"
            max-age-seconds="31536000"
            preload="true" />
    </headers>
</http>
xml

@Configuration
@EnableWebSecurity
class SecurityConfig {

    @Bean
    open fun filterChain(http: HttpSecurity): SecurityFilterChain {
        http {
            headers {
                httpStrictTransportSecurity {
                    includeSubDomains = true
                    preload = true
                    maxAgeInSeconds = 31536000
                }
            }
        }
        return http.build()
    }
}
kotlin

HTTP 公钥固定 (HPKP)

Spring Security 为 HTTP 公钥固定提供了 servlet 支持，但它不再被推荐。

您可以使用以下配置启用 HPKP 头部：

Java
XML
Kotlin

@Configuration
@EnableWebSecurity
public class WebSecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            // ...
            .headers(headers -> headers
                .httpPublicKeyPinning(hpkp -> hpkp
                    .includeSubDomains(true)
                    .reportUri("https://example.net/pkp-report")
                    .addSha256Pins("d6qzRu9zOECb90Uez27xWltNsj0e1Md7GkYYkVoZWmM=", "E9CZ9INDbd+2eRQozYqqbQ2yXLVKB9+xcprMF+44U1g=")
                )
            );
        return http.build();
    }
}
java

<http>
    <!-- ... -->

    <headers>
        <hpkp
            include-subdomains="true"
            report-uri="https://example.net/pkp-report">
            <pins>
                <pin algorithm="sha256">d6qzRu9zOECb90Uez27xWltNsj0e1Md7GkYYkVoZWmM=</pin>
                <pin algorithm="sha256">E9CZ9INDbd+2eRQozYqqbQ2yXLVKB9+xcprMF+44U1g=</pin>
            </pins>
        </hpkp>
    </headers>
</http>
xml

@Configuration
@EnableWebSecurity
class SecurityConfig {

    @Bean
    open fun filterChain(http: HttpSecurity): SecurityFilterChain {
        http {
            headers {
                httpPublicKeyPinning {
                    includeSubDomains = true
                    reportUri = "https://example.net/pkp-report"
                    pins = mapOf("d6qzRu9zOECb90Uez27xWltNsj0e1Md7GkYYkVoZWmM=" to "sha256",
                            "E9CZ9INDbd+2eRQozYqqbQ2yXLVKB9+xcprMF+44U1g=" to "sha256")
                }
            }
        }
        return http.build()
    }
}
kotlin

X-Frame-Options

默认情况下，Spring Security 通过使用 X-Frame-Options 指示浏览器阻止反射型 XSS 攻击。

例如，以下配置指定 Spring Security 不应再指示浏览器阻止内容：

Java
XML
Kotlin

@Configuration
@EnableWebSecurity
public class WebSecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            // ...
            .headers(headers -> headers
                .frameOptions(frameOptions -> frameOptions
                    .sameOrigin()
                )
            );
        return http.build();
    }
}
java

<http>
    <!-- ... -->

    <headers>
        <frame-options
        policy="SAMEORIGIN" />
    </headers>
</http>
xml

@Configuration
@EnableWebSecurity
class SecurityConfig {

    @Bean
    open fun filterChain(http: HttpSecurity): SecurityFilterChain {
        http {
            headers {
                frameOptions {
                    sameOrigin = true
                }
            }
        }
        return http.build()
    }
}
kotlin

X-XSS-Protection

默认情况下，Spring Security 通过使用 <<headers-xss-protection,X-XSS-Protection header> 指示浏览器禁用 XSS 审核器。但是，你可以更改此默认设置。例如，以下配置指定 Spring Security 指示兼容的浏览器启用过滤，并阻止内容：

Java
XML
Kotlin

@Configuration
@EnableWebSecurity
public class WebSecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            // ...
            .headers(headers -> headers
                .xssProtection(xss -> xss
                    .headerValue(XXssProtectionHeaderWriter.HeaderValue.ENABLED_MODE_BLOCK)
                )
            );
        return http.build();
    }
}
java

<http>
    <!-- ... -->

    <headers>
        <xss-protection headerValue="1; mode=block"/>
    </headers>
</http>
xml

@Configuration
@EnableWebSecurity
class SecurityConfig {

    @Bean
    open fun filterChain(http: HttpSecurity): SecurityFilterChain {
        // ...
        http {
            headers {
                xssProtection {
                    headerValue = XXssProtectionHeaderWriter.HeaderValue.ENABLED_MODE_BLOCK
                }
            }
        }
        return http.build()
    }
}
kotlin

内容安全策略 (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/
http

根据前面的安全策略，您可以启用 CSP 标头：

Java
XML
Kotlin

@Configuration
@EnableWebSecurity
public class WebSecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            // ...
            .headers(headers -> headers
                .contentSecurityPolicy(csp -> csp
                    .policyDirectives("script-src 'self' https://trustedscripts.example.com; object-src https://trustedplugins.example.com; report-uri /csp-report-endpoint/")
                )
            );
        return http.build();
    }
}
java

<http>
    <!-- ... -->

    <headers>
        <content-security-policy
            policy-directives="script-src 'self' https://trustedscripts.example.com; object-src https://trustedplugins.example.com; report-uri /csp-report-endpoint/" />
    </headers>
</http>
xml

@Configuration
@EnableWebSecurity
class SecurityConfig {

    @Bean
    open fun filterChain(http: HttpSecurity): SecurityFilterChain {
        http {
            // ...
            headers {
                contentSecurityPolicy {
                    policyDirectives = "script-src 'self' https://trustedscripts.example.com; object-src https://trustedplugins.example.com; report-uri /csp-report-endpoint/"
                }
            }
        }
        return http.build()
    }
}
kotlin

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

Java
XML
Kotlin

@Configuration
@EnableWebSecurity
public class WebSecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            // ...
            .headers(headers -> headers
                .contentSecurityPolicy(csp -> csp
                    .policyDirectives("script-src 'self' https://trustedscripts.example.com; object-src https://trustedplugins.example.com; report-uri /csp-report-endpoint/")
                    .reportOnly()
                )
            );
        return http.build();
    }
}
java

<http>
    <!-- ... -->

    <headers>
        <content-security-policy
            policy-directives="script-src 'self' https://trustedscripts.example.com; object-src https://trustedplugins.example.com; report-uri /csp-report-endpoint/"
            report-only="true" />
    </headers>
</http>
xml

@Configuration
@EnableWebSecurity
class SecurityConfig {

    @Bean
    open fun filterChain(http: HttpSecurity): SecurityFilterChain {
        http {
            // ...
            headers {
                contentSecurityPolicy {
                    policyDirectives = "script-src 'self' https://trustedscripts.example.com; object-src https://trustedplugins.example.com; report-uri /csp-report-endpoint/"
                    reportOnly = true
                }
            }
        }
        return http.build()
    }
}
kotlin

引荐来源政策

Spring Security 默认不会添加 Referrer Policy 头。您可以通过以下配置启用 Referrer Policy 头：

Java
XML
Kotlin

@Configuration
@EnableWebSecurity
public class WebSecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            // ...
            .headers(headers -> headers
                .referrerPolicy(referrer -> referrer
                    .policy(ReferrerPolicy.SAME_ORIGIN)
                )
            );
        return http.build();
    }
}
java

<http>
    <!-- ... -->

    <headers>
        <referrer-policy policy="same-origin" />
    </headers>
</http>
xml

@Configuration
@EnableWebSecurity
class SecurityConfig {

    @Bean
    open fun filterChain(http: HttpSecurity): SecurityFilterChain {
        http {
            // ...
            headers {
                referrerPolicy {
                    policy = ReferrerPolicy.SAME_ORIGIN
                }
            }
        }
        return http.build()
    }
}
kotlin

功能策略

Spring Security 默认不添加 Feature Policy 头。请考虑以下 Feature-Policy 头：

Feature-Policy: geolocation 'self'

none

你可以通过以下配置启用前面的特性策略标头：

Java
XML
Kotlin

@Configuration
@EnableWebSecurity
public class WebSecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            // ...
            .headers(headers -> headers
                .featurePolicy("geolocation 'self'")
            );
        return http.build();
    }
}
java

<http>
    <!-- ... -->

    <headers>
        <feature-policy policy-directives="geolocation 'self'" />
    </headers>
</http>
xml

@Configuration
@EnableWebSecurity
class SecurityConfig {

    @Bean
    open fun filterChain(http: HttpSecurity): SecurityFilterChain {
        http {
            // ...
            headers {
                featurePolicy("geolocation 'self'")
            }
        }
        return http.build()
    }
}
kotlin

权限策略

Spring Security 默认不添加权限策略头。请考虑以下 Permissions-Policy 头：

Permissions-Policy: geolocation=(self)

none

您可以使用以下配置启用前面的权限策略标头：

Java
XML
Kotlin

@Configuration
@EnableWebSecurity
public class WebSecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            // ...
            .headers(headers -> headers
                .permissionsPolicy(permissions -> permissions
                    .policy("geolocation=(self)")
                )
            );
        return http.build();
    }
}
java

<http>
    <!-- ... -->

    <headers>
        <permissions-policy policy="geolocation=(self)" />
    </headers>
</http>
xml

@Configuration
@EnableWebSecurity
class SecurityConfig {

    @Bean
    open fun filterChain(http: HttpSecurity): SecurityFilterChain {
        http {
            // ...
            headers {
                permissionPolicy {
                    policy = "geolocation=(self)"
                }
            }
        }
        return http.build()
    }
}
kotlin

清除站点数据

Spring Security 默认不会添加 Clear-Site-Data 头。请考虑以下 Clear-Site-Data 头：

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

您可以通过以下配置在登出时发送前面的标头：

Java
Kotlin

@Configuration
@EnableWebSecurity
public class WebSecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            // ...
            .logout((logout) -> logout
                .addLogoutHandler(new HeaderWriterLogoutHandler(new ClearSiteDataHeaderWriter(CACHE, COOKIES)))
            );
        return http.build();
    }
}
java

@Configuration
@EnableWebSecurity
class SecurityConfig {

    @Bean
    open fun filterChain(http: HttpSecurity): SecurityFilterChain {
        http {
            // ...
            logout {
                addLogoutHandler(HeaderWriterLogoutHandler(ClearSiteDataHeaderWriter(CACHE, COOKIES)))
            }
        }
        return http.build()
    }
}
kotlin

自定义标头

Spring Security 有机制可以方便地为应用程序添加更常见的安全头。但是，它也提供了钩子来启用添加自定义头。

静态头

有时你可能希望在应用程序中注入自定义的安全头，而这些安全头是开箱即用不支持的。请考虑以下自定义安全头：

X-Custom-Security-Header: header-value

none

根据前面的头部信息，您可以使用以下配置将头部添加到响应中：

Java
XML
Kotlin

@Configuration
@EnableWebSecurity
public class WebSecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            // ...
            .headers(headers -> headers
                .addHeaderWriter(new StaticHeadersWriter("X-Custom-Security-Header","header-value"))
            );
        return http.build();
    }
}
java

<http>
    <!-- ... -->

    <headers>
        <header name="X-Custom-Security-Header" value="header-value"/>
    </headers>
</http>
xml

@Configuration
@EnableWebSecurity
class SecurityConfig {

    @Bean
    open fun filterChain(http: HttpSecurity): SecurityFilterChain {
        http {
            // ...
            headers {
                addHeaderWriter(StaticHeadersWriter("X-Custom-Security-Header","header-value"))
            }
        }
        return http.build()
    }
}
kotlin

Headers Writer

当命名空间或 Java 配置不支持你所需的头部时，你可以创建一个自定义的 HeadersWriter 实例，甚至提供一个自定义的 HeadersWriter 实现。

下一个示例使用自定义的 XFrameOptionsHeaderWriter 实例。如果你想要显式配置 X-Frame-Options，可以使用以下配置：

Java
XML
Kotlin

@Configuration
@EnableWebSecurity
public class WebSecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            // ...
            .headers(headers -> headers
                .addHeaderWriter(new XFrameOptionsHeaderWriter(XFrameOptionsMode.SAMEORIGIN))
            );
        return http.build();
    }
}
java

<http>
    <!-- ... -->

    <headers>
        <header ref="frameOptionsWriter"/>
    </headers>
</http>
<!-- Requires the c-namespace.
See https://docs.spring.io/spring/docs/current/spring-framework-reference/htmlsingle/#beans-c-namespace
-->
<beans:bean id="frameOptionsWriter"
    class="org.springframework.security.web.header.writers.frameoptions.XFrameOptionsHeaderWriter"
    c:frameOptionsMode="SAMEORIGIN"/>
xml

@Configuration
@EnableWebSecurity
class SecurityConfig {

    @Bean
    open fun filterChain(http: HttpSecurity): SecurityFilterChain {
        http {
            // ...
            headers {
                addHeaderWriter(XFrameOptionsHeaderWriter(XFrameOptionsMode.SAMEORIGIN))
            }
        }
        return http.build()
    }
}
kotlin

DelegatingRequestMatcherHeaderWriter

有时，你可能只想为某些请求编写头信息。例如，也许你只想保护登录页面不被嵌入框架。你可以使用 DelegatingRequestMatcherHeaderWriter 来实现这一点。

以下配置示例使用了 DelegatingRequestMatcherHeaderWriter：

Java
XML
Kotlin

@Configuration
@EnableWebSecurity
public class WebSecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        RequestMatcher matcher = new AntPathRequestMatcher("/login");
        DelegatingRequestMatcherHeaderWriter headerWriter =
            new DelegatingRequestMatcherHeaderWriter(matcher,new XFrameOptionsHeaderWriter());
        http
            // ...
            .headers(headers -> headers
                .frameOptions(frameOptions -> frameOptions.disable())
                .addHeaderWriter(headerWriter)
            );
        return http.build();
    }
}
java

<http>
    <!-- ... -->

    <headers>
        <frame-options disabled="true"/>
        <header ref="headerWriter"/>
    </headers>
</http>

<beans:bean id="headerWriter"
    class="org.springframework.security.web.header.writers.DelegatingRequestMatcherHeaderWriter">
    <beans:constructor-arg>
        <bean class="org.springframework.security.web.util.matcher.AntPathRequestMatcher"
            c:pattern="/login"/>
    </beans:constructor-arg>
    <beans:constructor-arg>
        <beans:bean
            class="org.springframework.security.web.header.writers.frameoptions.XFrameOptionsHeaderWriter"/>
    </beans:constructor-arg>
</beans:bean>
xml

@Configuration
@EnableWebSecurity
class SecurityConfig {

    @Bean
    open fun filterChain(http: HttpSecurity): SecurityFilterChain {
        val matcher: RequestMatcher = AntPathRequestMatcher("/login")
        val headerWriter = DelegatingRequestMatcherHeaderWriter(matcher, XFrameOptionsHeaderWriter())
       http {
            headers {
                frameOptions {
                    disable()
                }
                addHeaderWriter(headerWriter)
            }
        }
        return http.build()
    }
}
kotlin

默认安全头​

缓存控制​

Content Type Options​

HTTP 严格传输安全 (HSTS)​

HTTP 公钥固定 (HPKP)​

X-Frame-Options​

X-XSS-Protection​

内容安全策略 (CSP)​

引荐来源政策​

功能策略​

权限策略​

清除站点数据​

自定义标头​

静态头​

Headers Writer​

DelegatingRequestMatcherHeaderWriter​

默认安全头

缓存控制

Content Type Options

HTTP 严格传输安全 (HSTS)

HTTP 公钥固定 (HPKP)

X-Frame-Options

X-XSS-Protection

内容安全策略 (CSP)

引荐来源政策

功能策略

权限策略

清除站点数据

自定义标头

静态头

Headers Writer

DelegatingRequestMatcherHeaderWriter