1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
|
---
title: Using Feature Policy
slug: Web/HTTP/Feature_Policy/Using_Feature_Policy
translation_of: Web/HTTP/Feature_Policy/Using_Feature_Policy
original_slug: Web/HTTP/策略特征/Using_Feature_Policy
---
<div>{{HTTPSidebar}} {{SeeCompatTable}}</div>
<p><a href="/en-US/docs/Web/HTTP/Feature_Policy">Feature Policy</a> allows you to control which origins can use which features, both in the top-level page and in embedded frames. Essentially, you write a policy, which is an allowed list of origins for each feature. For every feature controlled by Feature Policy, the feature is only enabled in the current document or frame if its origin matches the allowed list of origins.</p>
<p>For each policy-controlled feature, the browser maintains a list of origins for which the feature is enabled, known as an allowlist. If you do not specify a policy for a feature, then a default allowlist will be used. The default allowlist is specific to each feature.</p>
<h2 id="Writing_a_policy">Writing a policy</h2>
<p>A policy is described using a set of individual policy directives. A policy directive is a combination of a defined feature name, and an allowlist of origins that can use the feature.</p>
<h3 id="allowlist">allowlist</h3>
<p>allowlist可以使用以下一个或多个值。</p>
<ul>
<li><code>*</code>: 允许在当前文档和所有包含的内容（比如iframes）中使用本特性。</li>
<li><code>'self'</code>: 允许在当前文档中使用本特性，但在包含的内容（比如iframes）仍使用原值。</li>
<li><code>'src'</code>: (只在iframe中允许) 只要在{{HTMLElement('iframe','src','#Attributes')}} 中的URL和加载iframe用的URL相同，则本特性在iframe中允许，</li>
<li><code>'none'</code>: 从最上层到包含的内容都禁止本特性。</li>
<li><origin(s)>: 在特定的源中允许，源URL以空格分割。</li>
</ul>
<p><code>*</code>(在所有源地址启用)<code><font face="Arial, x-locale-body, sans-serif"><span style="background-color: #ffffff;">或</span></font>'none'</code>(在所有源地址禁用)只允许单独使用，而<code>'self'</code>和<code>'src'</code>可以与多个源地址一起使用。</p>
<p>所有的特性都有一个如下的默认的allowlist</p>
<ul>
<li><code>*</code>: 本特性默认在最上层和包含的内容中（iframes）允许。</li>
<li><code>'self'</code>: 本特性默认在最上层允许，而包含的内容中（iframes）使用源地址相同设定。也就是说本特性在iframe中不允许跨域访问。</li>
<li><code>'none'</code>: 本特性默认在最上层和包含的内容中（iframes）都禁止。</li>
</ul>
<h2 id="Specifying_your_policy">Specifying your policy</h2>
<p>Feature Policy provides two ways to specify policies to control features:</p>
<ul>
<li>The {{httpheader('Feature-Policy')}} HTTP header.</li>
<li>The {{htmlattrxref("allow", "iframe")}} attribute on {{htmlelement("iframe")}}s.</li>
</ul>
<p>The primary difference between the HTTP header and the <code>allow</code> attribute is that the allow attribute only controls features within an iframe. The header controls features in the response and any embedded content within the page.</p>
<h3 id="The_Feature-Policy_HTTP_header">The Feature-Policy HTTP header</h3>
<p>You can send the <code>Feature-Policy</code> HTTP header with the response of a page. The value of this header is a policy to be enforced by the browser for the given page. It has the following structure.</p>
<pre class="brush: bash">Feature-Policy: <feature name> <allowlist of origin(s)></pre>
<p>For example, to block all content from using the Geolocation API across your site:</p>
<pre class="brush: bash">Feature-Policy: geolocation 'none'</pre>
<p>Several features can be controlled at the same time by sending the HTTP header with a semicolon-separated list of policy directives, or by sending a separate header for each policy.</p>
<p>For example, the following are equivalent:</p>
<pre class="brush: bash">Feature-Policy: unsized-media 'none'; geolocation 'self' https://example.com; camera *;
Feature-Policy: unsized-media 'none'
Feature-Policy: geolocation 'self' https://example.com
Feature-Policy: camera *;
</pre>
<h3 id="The_iframe_allow_attribute">The iframe allow attribute</h3>
<p>The second way to use Feature Policy is for controlling content within an iframe. Use the <code>allow</code> attribute to specify a policy list for embedded content.</p>
<p>For example, allow all browsing contexts within this iframe to use fullscreen:</p>
<pre class="brush: html"><iframe src="https://example.com..." allow="fullscreen"></iframe></pre>
<p>This is equivalent to:</p>
<pre class="brush: html"><iframe src="https://example.com..." allow="fullscreen 'src'"></iframe></pre>
<p>This example allows <code><iframe></code> content on a particular origin to access the user's location:</p>
<pre class="brush: html"><iframe src="https://google-developers.appspot.com/demos/..."
allow="geolocation https://google-developers.appspot.com"></iframe>
</pre>
<p>Similar to the HTTP header, several features can be controlled at the same time by specifying a semicolon-separated list of policy directives.</p>
<p>For example, this blocks the <code><iframe></code> from using the camera and microphone:</p>
<pre class="brush: html"><iframe allow="camera 'none'; microphone 'none'">
</pre>
<h2 id="Inheritance_of_policy_for_embedded_content">Inheritance of policy for embedded content</h2>
<p>Scripts inherit the policy of their browsing context, regardless of their origin. That means that top-level scripts inherit the policy from the main document.</p>
<p>All iframes inherit the policy of their parent page. If the iframe has an <code>allow</code> attribute, the policies of the parent page and the <code>allow</code> attribute are combined, using the most restrictive subset. For an iframe to have a feature enabled, the origin must be in the allowlist for both the parent page and the allow attribute.</p>
<p>Disabling a feature in a policy is a one-way toggle. If a feature has been disabled for a child frame by its parent frame, the child cannot re-enable it, and neither can any of the child's descendants.</p>
<h2 id="Enforcing_best_practices_for_good_user_experiences">Enforcing best practices for good user experiences</h2>
<p>It's difficult to build a website that uses all the latest best practices and provides great performance and user experiences. As the website evolves, it can become even harder to maintain the user experience over time. You can use feature policies to specify the desired best practices, and rely on the browser to enforce the policies to prevent regressions.</p>
<p>There are several policy-controlled features designed to represent functionality that can negatively impact the user experience. These features include:</p>
<ul>
<li>Layout-inducing Animations</li>
<li>Unoptimized (poorly compressed) images</li>
<li>Oversized images</li>
<li>Synchronous scripts</li>
<li>Synchronous XMLHttpRequest</li>
<li>Unsized media</li>
</ul>
<p>To avoid breaking existing web content, the default for such policy-controlled features is to allow the functionality to be used by all origins. That is, the default allowlist is <code>'*'</code> for each feature. Preventing the use of the sub-optimal functionality requires explicitly specifying a policy that disables the features.</p>
<p>For new content, you can start developing with a policy that disables all the features. This approach ensures that none of the functionality is introduced. When applying a policy to existing content, testing is likely required to verify it continues to work as expected. This is especially important for embedded or third-party content that you do not control.</p>
<p>To turn on the enforcement of all the best practices, specify the policy as below.</p>
<p>Send the following the HTTP header:</p>
<pre class="brush: bash">Feature-Policy: layout-animations 'none'; unoptimized-images 'none'; oversized-images 'none'; sync-script 'none'; sync-xhr 'none'; unsized-media 'none';</pre>
<p>Using the <code><iframe></code> <code>allow</code> attribute:</p>
<pre class="brush: html"><iframe src="https://example.com..." allow="layout-animations 'none'; unoptimized-images 'none'; oversized-images 'none'; sync-script 'none'; sync-xhr 'none'; unsized-media 'none';"></iframe></pre>
<h2 id="See_also">See also</h2>
<ul>
<li><a href="/en-US/docs/Web/HTTP/Feature_Policy">Feature Policy</a></li>
<li>{{HTTPHeader("Feature-Policy")}} header</li>
<li>{{HTMLElement('iframe','allow','#Attributes')}} attribute on iframes</li>
<li>{{HTTPHeader("Content-Security-Policy")}} header</li>
<li>{{HTTPHeader("Referrer-Policy")}} header</li>
</ul>
|
