Content Security Policy (CSP) restrictions

Sometimes, the stagewise companion won't load on your app for various reasons. The most likely reason for this is that a Content-Security-Policy (CSP) is preventing stagewise from loading. This guide will explain what a CSP is, which policies need to be adapted to use stagewise, and why.

Note: If you know that your app deploys a response header-based CSP and all relevant stagewise users use the browser extension, you're probably not affected by CSP problems.

What is a Content-Security-Policy (CSP)?

A Content Security Policy (CSP) is a mechanism that restricts the sources from which different types of content and functionality can be loaded. It is one of the recommended safety measures against Cross-Site Scripting (XSS) attacks.

Response header based CSPs

Response header based CSPs are returned by the serving web server in the response header Content-Security-Policy. The CSP returned by the response containing the main website document is relevant for the CSP restrictions enabled by the browser.

<meta> tag based CSPs

Meta tag based CSPs are returned by the main website document as a meta tag in the head section of the document.

Do I need to update the CSP of my app?

If and what you need to adapt in your CSP policies depends on whether you define them in response headers (recommended) or a meta-tag and if you use the stagewise browser extension (recommended) or integrate stagewise via a script-tag.

CSP defined in response headers

stagewise integrated using browser extension (recommended)

This is the easy case: Thanks to the integrated CSP patcher in the extension, you can use stagewise in your project without having to adapt your CSP settings.

When opening the popover of the extension, you are able to define if the CSP patcher is enabled and in which mode it operates:

• Open the extension popup by clicking on the stagewise icon in the extension list.

• Click on "Advanced options"

• Select which mode you want the CSP patcher to operate in

• "Don't change CSP" disables the CSP patcher

• "Intelligent patching" analyzes the existing CSP and only extends it with the necessary values, making this a safe and easy-to-use option in most cases

• "Disable CSP completely" removes the CSP from all pages where a deployment is registered at stagewise. This is not as safe as intelligent patching but should work fine in dev environments and handles certain edge-cases better.

stagewise integrated using <script> tag

In this case, you have to adapt your web server configuration to enable the CSP. Refer to the section "Required CSP permissions for the stagewise companion".

CSP defined in <meta> tag

If you defined your CSP in a meta tag, you must adapt your CSP since the stagewise extension is not able to patch your CSP in this case. Refer to the section "Required CSP permissions for the stagewise companion".

Required CSP permissions for the stagewise companion

This section explains which permissions are needed. If you need to understand if and why you have to adapt your CSP, read the section below.

script-src

Classic URL approach

If your CSP's script-src directive doesn't contain the tag 'strict-dynamic', you can simply add our domain to the list of allowed sources for scripts:

“

... ...; script-src ... https://stagewise.io ...; ... ...

If your policy allows all scripts from https: contexts, you do not have to add our domain to the list of allowed sources.

'strict-dynamic' approach

If your CSP's script-src directive contains the 'strict-dynamic' tag, you need to use a nonce and apply that to the script tag that loads the stagewise companion. If you include the companion though a script loader like Google Tag Manager, this will be handled for you.

Do not use a (build-time)-hash value to include the companion in the list of allowed scripts, as the companion get's updated regularly.

Note: If you define your CSP in a meta-tag, you are forced to load the companion by using a script-tag, since the extension is not able to inject the script on it's own.

connect-src

Add our domain to the allowed connect sources:

“

... ...; connect-src ... https://stagewise.io ...; ... ...

default-src

If you define a default-src directive, add the capability to load from our domain and from blob: protocol (explained in section media-src).

“

... ...; default-src ... https://stagewise.io blob: ...; ... ...

style-src

Add our domain and 'unsafe-inline' to the allowed list of sources:

“

... ...; style-src ... https://stagewise.io 'unsafe-inline' ...; ... ...

Note: We need the 'unsafe-inline' permission since our companion script ships it's own CSS definition. This could change in the future.

media-src

Add our domain and the blob: protocol to the allowed list of sources:

“

... ...; media-src ... https://stagewise.io blob: ...; ... ...

Note: We need the blob: protocol permission since the companion store work in progress data as blobs in the local storage.

img-src

Just like the media-src directive, you have to add our domain and the blob: protocol to the allowed list of sources:

“

... ...; img-src ... https://stagewise.io blob: ...; ... ...

Best practices and our recommendations

Although it is entirely up to you how you want to define your CSP and what items you whitelist or blacklist, here is a list of recommendations we want to give you:

• Prefer using response header based CSPs. They are patchable by our extension.

• Validate your CSP using a CSP evaluator. Strip directives and values that are redundant to keep a clear overview on your CSP.

• Prefer to define your CSP only in one place (header or single meta tag), since all CSPs will be parsed and may conflict with each other.