Skip to main content

Configure same-origin and sandbox for iframes

Learn how to configure same-origin policy and sandboxing for iframes and custom components.

By default, self-hosted deployments enforce the same-origin policy for iframes and custom components embedded in Retool apps. All embedded content is considered to be from a separate origin and fails the same-origin policy.

This isolates embedded content (e.g., custom components) for security purposes but it can restrict functionality, such as:

  • Accesing cookies.
  • Accessing certain JavaScript APIs.
  • Making any HTTP requests.

If necessary, you can set the ALLOW_SAME_ORIGIN_OPTION environment variable to use the allow-same-origin attribute and bypass these restrictions.

Update environment variables​

You can update your environment variable configuration to use allow-same-origin for iframe content by setting the ALLOW_SAME_ORIGIN_OPTION environment variable to true.

If you need iframes to use allow-same-origin, you should also set the SANDBOX_DOMAIN environment variable.

Configure sandbox domain​

By default, your Retool instance will make use of a single domain, and all access to your Retool backend will arrive via that domain. However, having only a single domain can cause some security issues when ALLOW_SAME_ORIGIN_OPTION is set to true.

Setting up an additonal domain to point to your Retool backend, and then setting the value SANDBOX_DOMAIN to this second domain, can protect you from these security issues.

Once SANDBOX_DOMAIN is set, it provides an alternative origin for the browser to use when executing builder-written JavaScript. This isolates builder-written code from interacting with the the rest of the page and it's contents, including authentication cookies for your Retool backend.

If SANDBOX_DOMAIN is not set, but ALLOW_SAME_ORIGIN_OPTION is set, all builder-written JavaScript code runs on the same origin as your Retool deployment instance, and has access to everything on the page, including all cookies. A malicious builder on your Retool instance could take advantage of this to run their javascript code in other builder's browsers, and take actions on their behalf.

The value you use for SANDBOX_DOMAIN should be a fully functional domain that routes HTTP requests to your Retool instance. In most cases, this requires going through the process of registering a new domain, and configuring it to point to your Retool backend.

For example, if you currently host your Retool backend on mydomain.com, Retool recommends you registering a new domain, such as mydomain-sandbox.com, and set mydomain-sandbox.com to point to your Retool backend (identically to how you setup mydomain.com). Then, set the value of the SANDBOX_DOMAIN environment variable to be https://mydomain-sandbox.com. Note that you must include the protocol in the value, which is usually https.