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 for security purposes but it can restrict functionality, such as:

  • Storing data or cookies.
  • Access to certain JavaScript APIs.

If necessary, you can update your deployment configuration to use the allow-same-origin attribute.

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 to true.

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

Configure sandbox domain​

All JavaScript within Retool apps runs in the browser. If a user writes JavaScript code that can perform malicious actions, setting SANDBOX_DOMAIN can help protect your other users.

Setting SANDBOX_DOMAIN provides an alternative origin for the browser when executing JavaScript. All user-written code that runs in the browser uses the origin defined by SANDBOX_DOMAIN. This isolates the code from interacting with the base domain. This includes authentication cookies for your Retool backend.

If SANDBOX_DOMAIN is not set, any custom JavaScript code runs on the same domain as your Retool deployment instance.

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.