Embed a published app

Configure Content Security Policy rules to embed a published app in an iframe on another site, in another app, or in a classic app.

By default, Retool blocks other pages from framing your apps as one of many mechanisms that keep your apps safe. To place a published app in an iframe, an admin adds Content Security Policy directive rules that name the pages allowed to frame it. This guide covers the three places you can embed an app: an external website, another app, and a classic app.

note

Certain mechanisms for embedding apps, such as the mechanism for custom authentication with Retool API, are not currently supported for apps.

Requirements

You must be an admin or have the delegated Manage advanced settings permission to change these rules. Refer to Customize the Content Security Policy for apps for how the policy works and which source expressions are accepted.

Each app you embed must be published. Refer to Publish an app for the URL of a published app.

Required directives

You may be required to set one or both of the following directives in the Content Security Policy settings.

Directive	Applies to	Default	Effect	Required for
frame-ancestors	All apps in your organization.	'none'	Names the pages allowed to frame the app.	All parent types (apps, classic apps, and external websites).
frame-src	The page holding the iframe.	'self'	Names what that page can load in an iframe.	When embedding an app in another app.

important

Rules take up to 30 minutes to apply across all of your apps.

Embed an app in an iframe

External website or app

Set frame-ancestors to allow a parent website or app to frame your app:

1. Go to Settings > App security > Content Security Policy.
2. Select Add rule, and choose the frame-ancestors directive. Enter the origin of the page that holds the iframe (which is the scheme, host, and optional port), such as https://portal.example.com. To allow several subdomains of one site, use a single-level wildcard such as https://*.example.com.
3. Add an iframe to that page with the published app URL as its src.

Parent website

<iframe src="https://retool.example.com/rr/app/support-tool" width="100%" height="800"></iframe>

Retool app

Set frame-ancestors and frame-src to allow another Retool app to frame your app:

1. Go to Settings > App security > Content Security Policy.
2. Add a frame-ancestors rule with the origin of the parent app.
3. Add a frame-src rule with the origin of the child app that you want to embed.
4. Navigate to the parent app. Ask the agent to add an iframe with the published URL of the child app as its src.

Caution

Avoid a wildcard such as https://*.retool.example.com to cover every pair at once. Published app URLs from other organizations can sit beneath the same domain, so a wildcard can allow apps outside your organization to frame yours. List each app origin you embed instead.

Classic Retool app

Embedding apps in classic apps is a helpful strategy for organizations that are in the process of converting their classic apps to apps, but haven't fully made the switch.

A classic app embeds content with the IFrame component. Set frame-ancestors to allow a classic app to frame your app, and configure the IFrame component to allow storage and cookies:

Self-hosted

1. Follow the instructions in the Configure same-origin and sandbox for iframes guide to set the ALLOW_SAME_ORIGIN_OPTION environment variable to use the allow-same-origin attribute.
2. Go to Settings > App security > Content Security Policy.
3. Add a frame-ancestors rule with the origin of your Retool organization, such as https://retool.example.com.
4. Add the IFrame component to the classic app and set URL to the published app URL.
5. In the component settings, enable Storage and cookies.

Cloud

1. Go to Settings > App security > Content Security Policy.
2. Add a frame-ancestors rule with the origin of your Retool organization, such as https://retool.example.com.
3. Add the IFrame component to the classic app and set URL to the published app URL.
4. In the Inspector, enable Storage and cookies in the Interaction section.

Troubleshooting

Use this section to diagnose and resolve common issues with apps in an iframe.

Why is the iframe blank?

Open your browser's developer console, and find the Content Security Policy violation. The violation names the directive that blocked it.

• A frame-ancestors violation means the parent page origin is missing from that directive. The following error appears in your developer console: Content Security Policy of your site blocks some resources.
• A frame-src violation means the parent page is a Retool app and the origin of the app in the iframe is missing from that directive. The following error appears in your developer console: Ensure CORS response header values are valid.

Add the missing origin, then reload the parent page.

Why does the app in the iframe ask the user to sign in?

The browser withholds the app's cookies. In a classic app, confirm Storage and cookies is enabled on the IFrame component, and on a self-hosted instance that ALLOW_SAME_ORIGIN_OPTION is set.

Why has a rule not taken effect?

Rules take up to 30 minutes to apply across all of your apps. Reload the parent page after that time. Confirm the rule records an origin with a scheme, such as https://portal.example.com, and not a bare host name.