Security headers quick reference

Before diving into security headers, learn about known threats on the web and why you'd want to use these security headers.

Protect your site from injection vulnerabilities #

Injection vulnerabilities arise when untrusted data processed by your application can affect its behavior and, commonly, lead to the execution of attacker-controlled scripts. The most common vulnerability caused by injection bugs is cross-site scripting (XSS) in its various forms, including reflected XSS, stored XSS, DOM-based XSS, and other variants.

An XSS vulnerability can typically give an attacker complete access to user data processed by the application and any other information hosted in the same web origin.

Traditional defenses against injections include consistent use of autoescaping HTML template systems, avoiding the use of dangerous JavaScript APIs, and properly processing user data by hosting file uploads in a separate domain and sanitizing user-controlled HTML.

• Use Content Security Policy (CSP) to control which scripts can be executed by your application to mitigate the risk of injections.
• Use Trusted Types to enforce sanitization of data passed into dangerous JavaScript APIs.
• Use X-Content-Type-Options to prevent the browser from misinterpreting the MIME types of your website's resources, which can lead to script execution.

Isolate your site from other websites #

The openness of the web allows websites to interact with each other in ways that can violate an application's security expectations. This includes unexpectedly making authenticated requests or embedding data from another application in the attacker's document, allowing the attacker to modify or read application data.

Common vulnerabilities that undermine web isolation include clickjacking, cross-site request forgery (CSRF), cross-site script inclusion (XSSI), and various cross-site leaks.

• Use X-Frame-Options to prevent your documents from being embedded by a malicious website.
• Use Cross-Origin Resource Policy (CORP) to prevent your website's resources from being included by a cross-origin website.
• Use Cross-Origin Opener Policy (COOP) to protect your website's windows from interactions by malicious websites.
• Use Cross-Origin Resource Sharing (CORS) to control access to your website's resources from cross-origin documents.

Post-Spectre Web Development is a great read if you are interested in these headers.

Build a powerful website securely #

Spectre puts any data loaded into the same browsing context group potentially readable despite same-origin policy. Browsers restrict features that may possibly exploit the vulnerability behind a special environment called "cross-origin isolation". With cross-origin isolation, you can use powerful features such as SharedArrayBuffer.

• Use Cross-Origin Embedder Policy (COEP) along with COOP to enable cross-origin isolation.

Encrypt traffic to your site #

Encryption issues appear when an application does not fully encrypt data in transit, allowing eavesdropping attackers to learn about the user's interactions with the application.

Insufficient encryption can arise in the following cases: not using HTTPS, mixed content, setting cookies without the Secure attribute (or __Secure prefix), or lax CORS validation logic.

• Use HTTP Strict Transport Security (HSTS) to consisitently serve your contents through HTTPS.

Recommended usages #

1. Use a nonce-based strict CSP #

If you render your HTML pages on the server, use a nonce-based strict CSP.

Generate a new script nonce value for every request on the server side and set the following header:

server configuration file

Content-Security-Policy:
  script-src 'nonce-{RANDOM1}' 'strict-dynamic' https: 'unsafe-inline';
  object-src 'none';
  base-uri 'none';

In HTML, in order to load the scripts, set the nonce attribute of all <script> tags to the same {RANDOM1} string.

index.html

<script nonce="{RANDOM1}" src="https://example.com/script1.js"></script>
<script nonce="{RANDOM1}">
  // Inline scripts can be used with the `nonce` attribute.
</script>

Google Photos is a good nonce-based strict CSP example. Use DevTools to see how it's used.

2. Use a hash-based strict CSP #

If your HTML has to be served statically or cached, for example if you're building a single-page application, use a hash-based strict CSP.

server configuration file

Content-Security-Policy:
  script-src 'sha256-{HASH1}' 'sha256-{HASH2}' 'strict-dynamic' https: 'unsafe-inline';
  object-src 'none';
  base-uri 'none';

In HTML, you'll need to inline your scripts in order to apply a hash-based policy, because most browsers don't support hashing external scripts.

index.html

<script>
...// your script1, inlined
</script>
<script>
...// your script2, inlined
</script>

To load external scripts, read "Load sourced scripts dynamically" under Option B: Hash-based CSP Response Header section.

CSP Evaluator is a good tool to evaluate your CSP, but at the same time a good nonce-based strict CSP example. Use DevTools to see how it's used.

Supported browsers #

Other things to note about CSP #

• frame-ancestors directive protects your site from clickjacking—a risk that arises if you allow untrusted sites to embed yours. If you prefer simpler solution, you can use X-Frame-Options to block being loaded, but frame-ancestors gives you an advanced configuration to only allow specific origins as embedders.
• You may have used a CSP to ensure that all of your site's resources are loaded over HTTPS. This has become less relevant: nowadays, most browsers block mixed-content.
• You can also set a CSP in report-only mode.
• If you can't set a CSP as a header server-side, you can also set it as a meta tag. Note that you can't use report-only mode for meta tags (though this may change).

Learn more #

• Mitigate XSS with a Strict Content Security Policy (CSP)
• Content Security Policy Cheat Sheet

Recommended usages #

1. Enforce Trusted Types for dangerous DOM sinks

   CSP and Trusted Types header:

   Content-Security-Policy: require-trusted-types-for 'script'

   Currently 'script' is the only acceptable value for require-trusted-types-for directive.

   Of course, you can combine Trusted Types with other CSP directives:

   Merging a nonce-based CSP from above with Trusted Types:

   Content-Security-Policy:
     script-src 'nonce-{RANDOM1}' 'strict-dynamic' https: 'unsafe-inline';
     object-src 'none';
     base-uri 'none';
     require-trusted-types-for 'script';

2. Define a policy

   Policy:

   // Feature detection
   if (window.trustedTypes && trustedTypes.createPolicy) {
     // Name and create a policy
     const policy = trustedTypes.createPolicy('escapePolicy', {
       createHTML: str => {
         return str.replace(/\</g, '&lt;').replace(/>/g, '&gt;');
       }
     });
   }

3. Apply the policy

   Use the policy when writing data to the DOM:

   // Assignment of raw strings are blocked by Trusted Types.
   el.innerHTML = 'some string'; // This throws an exception.
   
   // Assignment of Trusted Types is accepted safely.
   const escaped = policy.createHTML('<img src=x onerror=alert(1)>');
   el.innerHTML = escaped;  // '&lt;img src=x onerror=alert(1)&gt;'

   With require-trusted-types-for 'script', using a trusted type is a requirement. Using any dangerous DOM API with a string will result in an error.

Supported browsers #

Learn more #

• Prevent DOM-based cross-site scripting vulnerabilities with Trusted Types
• CSP: require-trusted-types-for - HTTP | MDN
• CSP: trusted-types - HTTP | MDN
• Trusted Types demo—open DevTools Inspector and see what is happening

Recommended usages #

X-Content-Type-Options: nosniff is recommended for all resources served from your server along with the correct Content-Type header.

Example headers sent with a document HTML

X-Content-Type-Options: nosniff
Content-Type: text/html; charset=utf-8

Supported browsers #

Learn more #

• X-Content-Type-Options - HTTP MDN

Recommended usages #

All documents that are not designed to be embedded should use X-Frame-Options header.

You can try how the following configurations affect loading an iframe on this demo. Change the X-Frame-Options dropdown menu and click the Reload the iframe button.

Protects your website from being embedded by any other websites #

Deny being embedded by any other documents.

X-Frame-Options: DENY

Protects your website from being embedded by any cross-origin websites #

Allow being embedded only by same-origin documents.

X-Frame-Options: SAMEORIGIN

Supported browsers #

Learn more #

• X-Frame-Options - HTTP

Recommended usages #

It is recommended that all resources are served with one of the following three headers.

You can try how the following configurations affect loading resources under a Cross-Origin-Embedder-Policy: require-corp environment on this demo. Change the Cross-Origin-Resource-Policy dropdown menu and click the Reload the iframe or Reload the image button to see the effect.

Allow resources to be loaded cross-origin #

It's recommended that CDN-like services apply cross-origin to resources (since they are usually loaded by cross-origin pages), unless they are already served through CORS which has a similar effect.

Cross-Origin-Resource-Policy: cross-origin

Limit resources to be loaded from the same-origin #

same-origin should be applied to resources that are intended to be loaded only by same-origin pages. You should apply this to resources that include sensitive information about the user, or responses of an API that is intended to be called only from the same origin.

Keep in mind that resources with this header can still be loaded directly, for example by navigating to the URL in a new browser window. Cross-Origin Resource Policy only protects the resource from being embedded by other websites.

Cross-Origin-Resource-Policy: same-origin

Limit resources to be loaded from the same-site #

same-site is recommended to be applied to resources that are similar to above but are intended to be loaded by other subdomains of your site.

Cross-Origin-Resource-Policy: same-site

Supported browsers #

Learn more #

• Consider deploying cross-origin resource policy
• Making your website "cross-origin isolated" using COOP and COEP
• Why you need "cross-origin isolated" for powerful features

Recommended usages #

You can try how the following configurations affect communication with a cross-origin popup window on this demo. Change the Cross-Origin-Opener-Policy dropdown menu for both the document and the popup window, click the Open a popup button then click Send a postMessage to see if the message is actually delivered.

Isolate a document from cross-origin windows #

Setting same-origin puts the document to be isolated from cross-origin document windows.

Cross-Origin-Opener-Policy: same-origin

Isolate a document from cross-origin windows but allow popups #

Setting same-origin-allow-popups allows a document to retain a reference to its popup windows unless they set COOP with same-origin or same-origin-allow-popups. This means same-origin-allow-popups can still protect the document from being referenced when opened as a popup window, but allow it to communicate with its own popups.

Cross-Origin-Opener-Policy: same-origin-allow-popups

Allow a document to be referenced by cross-origin windows #

unsafe-none is the default value but you can explicitly indicate that this document can be opened by a cross-origin window and retain mutual access.

Cross-Origin-Opener-Policy: unsafe-none

Report patterns incompatible with COOP #

You can receive reports when COOP prevents cross-window interactions with the Reporting API.

Cross-Origin-Opener-Policy: same-origin; report-to="coop"

COOP also supports a report-only mode so you can receive reports without actually blocking communication between cross-origin documents.

Cross-Origin-Opener-Policy-Report-Only: same-origin; report-to="coop"

Supported browsers #

Learn more #

• Why you need "cross-origin isolated" for powerful features

Before looking into how to configure CORS, it's helpful to understand the distinction between request types. Depending on request details, a request will be classified as a simple request or a preflighted request.

Criteria for a simple request:

• The method is GET, HEAD, or POST.
• The custom headers only include Accept, Accept-Language, Content-Language, and Content-Type.
• The Content-Type is application/x-www-form-urlencoded, multipart/form-data, or text/plain.

Everything else is classified as a preflighted request. For more details, check out Cross-Origin Resource Sharing (CORS) - HTTP | MDN.

Recommended usages #

Simple request #

When a request meets the simple request criteria, the browser sends a cross-origin request with an Origin header that indicates the requesting origin.

Example request header

Get / HTTP/1.1
Origin: https://example.com

Example response header

Access-Control-Allow-Origin: https://example.com
Access-Control-Allow-Credentials: true

• Access-Control-Allow-Origin: https://example.com indicates that the https://example.com can access the contents of the response. Resources meant to be readable by any site can set this header to *, in which case the browser will only require the request to be made without credentials.
• Access-Control-Allow-Credentials: true indicates that requests which carry credentials (cookies) are allowed to load the resource. Otherwise, authenticated requests will be rejected even if the requesting origin is present in the Access-Control-Allow-Origin header.

You can try how the simple request affect loading resources under a Cross-Origin-Embedder-Policy: require-corp environment on this demo. Click the Cross-Origin Resource Sharing checkbox and click the Reload the image button to see the effect.

Preflighted requests #

A preflighted request is preceded with an OPTIONS request to check if the subsequent request is allowed to be sent.

Example request header

OPTIONS / HTTP/1.1
Origin: https://example.com
Access-Control-Request-Method: POST
Access-Control-Request-Headers: X-PINGOTHER, Content-Type

• Access-Control-Request-Method: POST allows the following request to be made with the POST method.
• Access-Control-Request-Headers: X-PINGOTHER, Content-Type allows the requester to set the X-PINGOTHER and Content-Type HTTP headers in the subsequent request.

Example response headers

Access-Control-Allow-Origin: https://example.com
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: POST, GET, OPTIONS
Access-Control-Allow-Headers: X-PINGOTHER, Content-Type
Access-Control-Max-Age: 86400

• Access-Control-Allow-Methods: POST, GET, OPTIONS indicates that subsequent requests can be made with the POST, GET and OPTIONS methods.
• Access-Control-Allow-Headers: X-PINGOTHER, Content-Type indicates subsequent requests can include the X-PINGOTHER and Content-Type headers.
• Access-Control-Max-Age: 86400 indicates that the result of the preflighted request can be cached for 86400 seconds.

Supported browsers #

Learn more #

• Cross-Origin Resource Sharing (CORS)
• Cross-Origin Resource Sharing (CORS) - HTTP | MDN

Example usages #

COEP takes a single value of require-corp. By sending this header, you can instruct the browser to block loading resources that do not opt-in via CORS or CORP.

You can try how the following configurations affect loading resources on this demo. Change the Cross-Origin-Embedder-Policy dropdown menu, the Cross-Origin-Resource-Policy dropdown menu, the Report Only checkbox etc to see how they affect loading resources. Also, open the reporting endpoint demo to see if the blocked resources are reported.

Enable cross-origin isolation #

Enable cross-origin isolation by sending Cross-Origin-Embedder-Policy: require-corp along with Cross-Origin-Opener-Policy: same-origin.

Cross-Origin-Embedder-Policy: require-corp
Cross-Origin-Opener-Policy: same-origin

Report resources incompatible withn COEP #

You can receive reports of blocked resources caused by COEP with the Reporting API.

Cross-Origin-Embedder-Policy: require-corp; report-to="coep"

COEP also supports report-only mode so you can receive reports without actually blocking loading resources.

Cross-Origin-Embedder-Policy-Report-Only: require-corp; report-to="coep"

Supported browsers #

Learn more #

• Making your website "cross-origin isolated" using COOP and COEP
• Why you need "cross-origin isolated" for powerful features
• A guide to enable cross-origin isolation

Recommended usages #

All websites that transition from HTTP to HTTPS should respond with a Strict-Transport-Security header when a request with HTTP is received.

Strict-Transport-Security: max-age=31536000

Supported browsers #

Learn more #

• Strict-Transport-Security - HTTP