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
, we recommend you register 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). You should then set the value of the SANDBOX_DOMAIN
env variable to be mydomain-sandbox.com
.