Sometimes your website has to rely on content from other sources. Embedding content through an iframe or embedding a document like a PDF for instance. When loading data through an iframe, it is possible that the content doesn't conform with the standards you set for your own site, like loading time, effective network usage, etc. Another risk when embedding documents is that the source could get hacked, causing your site to embed and execute malicious code or show unwanted content.

There are many permissions currently available to webdevs to limit what the content in an iframe can do. It's called the "Sandbox"-attribute. When an iframe with the attribute "sandbox" is loaded, the browser can adjust the iframe privileges. For instance:

  • treat the content as being from a unique origin
  • block form submission
  • block script execution
  • disable APIs
  • prevent links from targeting other browsing contexts
  • prevent content from using plugins (through <embed>, <object>, <applet>, or other)
  • prevent the content to navigate its top-level browsing context
  • block automatically triggered permissions (such as automatically playing a video or automatically focusing a form control)

The webdev can specify if all these permissions or a selection of it is sandboxed. This way it's possible to block form submissions, but allow API-calls within the iframe.

The rise of the Permission Policy

As an addition to the iframe sandbox permissions (and other stuff), the Permissions Policy (previously referred to as Feature Policy) header was created. Permissions Policy allows webdevs to selectively enable, disable, and modify the behavior of certain features and APIs in the browser. It is similar to Content Security Policy but controls features instead of security behavior, hence the name. Permissions Policy also uses the Reporting API (again, like the Content Security Policy) to report violations to a monitoring tool like 🤘

In a nutshell; Permissions Policy allows you to opt-in to a set of policies for the browser to enforce on specific features used throughout your website. These policies can restrict what browser API's your website can access or modify. Here are some examples:

  • Change the default behavior on autoplaying videos
  • Restrict a site from using the camera or microphone
  • Block outdated API's like synchronous XHR
  • Ensure images are sized properly for the current viewport
  • and many more!

Extending Permissions Policy with Document Policies

There is a proposal for extending the Permissions Policy with what is called "Document Policies". Those are policies that are less security focused and more about configuring a document or remove extra features from a document or iframe (like sandboxing).

You might be thinking: Why use Document Policies when we already have sandboxed iframes with many configurable options? The idea of Document Policies is to be a framework for individual features that can be defined instead of being a set of concrete features itself. And while iframe sandboxing does a lot, it has very security-focused semantics and is difficult to extend. Document Policies try to fix that by creating an extensible framework.

So how do Document Policies work?

Document Policies can be set in the HTTP response headers of a resource. It sets the policy on the document that it's served with. It's possible to create restrictions on image sizes, compression ratios, lazy loading of frames, use of sync API calls, etc.

There are multiple proposed ways to use Document Policies. Here are the two most important: HTTP headers and iframes.

HTTP headers

The main document like index.html is loaded with a response-header like:

Document-Policy: no-unsized-media, no-document-write,
                 image-compression;bpp=2, frame-loading;lazy

Now when an embedded content is being loaded on that page, the request header for that embedded content will also send:

GET / HTTP/1.1
Sec-Required-Document-Policy: no-unsized-media,image-compression;bpp=2

Now the browser is asking for the content and gives the set document policies that the content must comply with. If the content doesn't comply with the request document policy, the content will be discarded.


It is possible to set the document policy in the iframe-tag like so:

<iframe src="" policy="image-compression;bpp=2">

The GET request headers will then look like:

GET / HTTP/1.1
Sec-Required-Document-Policy: image-compression;bpp=2

So now the loaded document in the iframe must have a good image compression. If not, it will be discarded.

Document Policies and iframe sandboxing are close friends and can and should be used together for an ultimate fine-tuning and control of embedded content through iframes. Read the complete proposal for Document Policies including nice samples.

Why should you use Document Policies?

When using Document Policies, you can get a little more grip on embedded content on your site. Sandboxing an iframe helps a lot but is really security focused. Document Policy is an extension for Permissions Policy and allows you to fine-tune a policy for the structure of a document. Like:

  • Restricting the use of poorly-performing images
  • Disabling slow synchronous JS APIs
  • Configuring frame, image or script loading styles
  • Restricting overall document sizes or network usage
  • Restricting patterns which cause slow page re-layout

It has the potential of being an awesome tool to get more control over what content is embedded on your site.

When to start implementation?

Since the Document-Policy extension is still just a proposal, I don't recommend implementing this just yet. Even though Chrome has released an Intent to Implement, at the time of writing, no other browsers have shown public signals of doing the same. We will keep an eye on future developments and keep you updated. The proposal looks promising so I think we will hear more about this extension in the near future.

Reporting of Document Policies violations

Because Document Policies will be an extension on Permissions Policy, violations can easily be tracked in your account under the section Permissions Policy.

We'll keep you updated in this blog when Document Policies is implemented in Chrome and when other browsers show public signs of implementing this new technology.

Thanks for reading!