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 in classic apps.

Note

This page applies to classic apps: the IFrame component and custom components. It doesn't apply to apps built with the app builder. To serve those apps and their app builder preview on their own hostnames, refer to Configure app hostnames.

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

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

  • Accessing 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.

Set SANDBOX_DOMAIN to avoid security risks

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 uses a single domain, and all access to your Retool backend arrives through that domain. However, having only a single domain can cause security issues when ALLOW_SAME_ORIGIN_OPTION is set to true.

Setting up an additional domain that points to your Retool backend, and then setting SANDBOX_DOMAIN to this second domain, protects 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 rest of the page and its 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 runs on the same origin as your Retool 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 JavaScript in other builders' 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 registering a new domain and configuring it to point to your Retool backend.

For example, if you host your Retool backend on retool.example.com, Retool recommends registering a new domain, such as example-sandbox.com, and configuring it to point to your Retool backend in the same way as retool.example.com. Then, set the SANDBOX_DOMAIN environment variable to https://example-sandbox.com. You must include the protocol in the value, which is usually https.