docs - domain page (#82683)

docs/README.md

@@ -233,6 +233,7 @@ Metabase's reference documentation.
 - [Configuration overview](./configuring-metabase/start.md)
 - [Setting up Metabase](./configuring-metabase/setting-up-metabase.md)
 - [General settings](./configuring-metabase/settings.md)
+- [Allow iframes and images from other domains](./configuring-metabase/domains.md)
 - [Email](./configuring-metabase/email.md)
 - [Slack](./configuring-metabase/slack.md)
 - [Webhooks](./configuring-metabase/webhooks.md)

docs/cloud/custom-domain.md

@@ -16,6 +16,8 @@ By default, Metabase will automatically provision a domain name for your Metabas
 
 [Pro and Enterprise](https://www.metabase.com/pricing) plans allow you to add a custom domain. Setting a custom domain will update your instance's [Site URL](../configuring-metabase/settings.md#site-url). The Site URL is used for things like creating links in emails, auth redirects, and in some embedding scenarios.
 
+> This page is about the web address of your Metabase Cloud instance. To control which sites dashboards can embed iframes and images from, see [Allow iframes and images from other domains](../configuring-metabase/domains.md).
+
 ## Add a custom domain to your Metabase
 
 To add a custom domain to your Metabase:

docs/configuring-metabase/domains.md

@@ -0,0 +1,59 @@
+---
+title: Allow iframes and images from other domains
+summary: Let people embed iframes from sites you trust in dashboards, and control which domains images can load from in text cards, descriptions, table columns, and custom visualizations.
+---
+
+# Allow iframes and images from other domains
+
+_Admin > Settings > Domains_
+
+By default, Metabase only lets dashboards embed iframes from a short list of popular sites, and lets images load from anywhere. Admins can allow iframes from more sites, or lock images down to trustworthy domains.
+
+> To change the web address people use to reach your Metabase, see [Changing your domain name](../cloud/custom-domain.md). On self-hosted Metabases, set the [Site URL](./settings.md#site-url).
+
+## Allow iframes from a site in dashboards
+
+_Admin > Settings > Domains_
+
+If someone adds an [iframe card](../dashboards/introduction.md#iframe-cards) to a dashboard and Metabase blocks it, the site isn't on the allowlist. To allow it:
+
+1. Under **Allowed domains for iframes in dashboards**, add the site's domain (like `example.com`). Separate multiple domains with commas. See [How domain matching works](#how-domain-matching-works).
+2. Click **Save changes**.
+
+Only allow sites you trust. An iframe can show whatever the site serves, so anyone who can edit a dashboard can put that content in front of everyone who views it.
+
+Metabase ships with a starter list (YouTube, Loom, Vimeo, Google Docs, and a few others). You can add to that list or clear it entirely. See [How domain matching works](#how-domain-matching-works).
+
+You can also set the list with the [`MB_ALLOWED_IFRAME_HOSTS`](./environment-variables.md#mb_allowed_iframe_hosts) environment variable.
+
+## Restrict where images can load from
+
+_Admin > Settings > Domains_
+
+People can link to images in [dashboard text cards](../dashboards/dashboard-markdown.md#add-an-image), entity descriptions, table columns that [display URLs as images](../questions/visualizations/table.md#display-url-as-an-image), and [custom visualizations](../questions/visualizations/custom.md). If you don't want those images to load from just anywhere, you can restrict them to your Metabase instance plus domains you choose. You also need image restriction on _before_ you can turn on custom visualizations, which limits where a visualization's code can load assets from.
+
+1. Turn on **Restrict image domains**.
+2. Under **Allowed domains for images**, add the domains images can load from (like `images.example.com`). Separate multiple domains with commas. Leave the list empty to only allow images hosted by your Metabase instance. See [How domain matching works](#how-domain-matching-works).
+3. Click **Save changes**.
+
+Under the hood, this sets the browser's Content Security Policy so images can only load from your Metabase instance, the map tile server that map visualizations use, and any domains you allow. You don't need to add the map tile server yourself.
+
+While custom visualizations are enabled, you can't turn off **Restrict image domains**. Disable custom visualizations first.
+
+You can also set these with the [`MB_CSP_IMG_ENABLED`](./environment-variables.md#mb_csp_img_enabled) and [`MB_CSP_IMG_ALLOWED_HOSTS`](./environment-variables.md#mb_csp_img_allowed_hosts) environment variables.
+
+## How domain matching works
+
+Both allowlists use the same rules. Including a subdomain is more restrictive than including the domain.
+
+- A **domain** like `example.com` allows the domain itself _and_ all of its subdomains (`data.example.com`, `docs.example.com`, and so on).
+- A **subdomain** like `data.example.com` allows only that subdomain. Metabase blocks everything else, including `example.com` itself and its other subdomains.
+
+So if your allowlist is:
+
+```
+data.example.com,
+docs.example.com
+```
+
+Metabase only allows `data.example.com` and `docs.example.com`. It blocks `example.com` and every other subdomain.

docs/configuring-metabase/settings.md

@@ -66,39 +66,3 @@ To manually label field or table names in Metabase, check out the [Table Metadat
 ## Enable X-rays
 
 [X-rays](../exploration-and-organization/x-rays.md) are a great way for people to get quick summary stats on your data. If these X-ray queries get too slow or expensive, you can turn them off here.
-
-## Allowed domains for iframes in dashboards
-
-Make sure you trust the sources that you allow people to embed in dashboards.
-
-You can include multiple domains separated by a comma. Including a subdomain is more restrictive than including the domain.
-
-- For **Domains**, (e.g., `example.com`), Metabase will allow any iframe from the domain (`example.com`) _and_ its subdomains (e.g., `data.example.com`, `docs.example.com`, etc.).
-- For **Subdomains** (e.g., `data.example.com`) Metabase will restrict iframes to those subdomains. In this case, iframes _must_ be from `data.example.com` (or any of the other allowed domains). Metabase will block iframes from all other subdomains, including `example.com`.
-
-So if you included the following:
-
-```
-data.example.com,
-docs.example.com
-```
-
-Metabase would only allow iframes from `data.example.com` and `docs.example.com`. Metabase would block iframes from all other domains, including iframes from `example.com` and its other subdomains.
-
-See [iframes in dashboards](../dashboards/introduction.md#iframe-cards).
-
-## Restrict image domains
-
-When on, Metabase restricts the browser's Content Security Policy so images can only load from this Metabase instance, the map tile server used by map visualizations, or the domains listed in [Allowed domains for images](#allowed-domains-for-images).
-
-By default, images from any domain are allowed.
-
-You must turn on this setting to enable [Custom visualizations](../questions/visualizations/custom.md). While custom visualizations are enabled, you can't turn it back off.
-
-## Allowed domains for images
-
-When the [Restrict image domains](#restrict-image-domains) setting is on, Metabase will only allow images served from this Metabase instance, the map tile server used by map visualizations, and any domains listed on this page.
-
-Leave this input empty to allow images hosted by your Metabase instance and the map tile server. The map tile server is always allowed so map visualizations keep working; you don't need to manually add it here.
-
-Add multiple domains separated by a comma. Domains follow the same matching rules as [Allowed domains for iframes in dashboards](#allowed-domains-for-iframes-in-dashboards): listing a domain like `example.com` also allows its subdomains, while listing a subdomain like `images.example.com` allows only that subdomain.

docs/configuring-metabase/start.md

@@ -14,6 +14,10 @@ A walkthrough of when you first boot up your Metabase.
 
 Site name, report timezone, and more settings.
 
+## [Allow iframes and images from other domains](./domains.md)
+
+Allowlist sites for iframe cards, and restrict which domains images can load from.
+
 ## [Email](./email.md)
 
 Set up email for [Alerts](../questions/alerts.md) and [Dashboard subscriptions](../dashboards/subscriptions.md).

docs/dashboards/dashboard-markdown.md

@@ -82,10 +82,10 @@ To add a filter value to a card:
 
 ## Add an image
 
-If your admin has [allowed domains for images](../configuring-metabase/settings.md#allowed-domains-for-images), you can add an image to a dashboard. Add a text card and use Markdown image syntax:
+You can add an image to a dashboard, as long as your admin hasn't [restricted the domain it's hosted on](../configuring-metabase/domains.md#restrict-where-images-can-load-from). Add a text card and use Markdown image syntax:
 
 ```text
 ![A description of the image](https://example.com/image.png)
 ```
 
-You can't upload an image to Metabase, only link to images hosted elsewhere.
+You can't upload an image to Metabase, only link to images hosted elsewhere.

docs/dashboards/introduction.md

@@ -167,6 +167,8 @@ src="https://www.youtube.com/embed/{{video_id}}
 
 To provide values for the variable, you'll need to add a filter to the dashboard, and connect that filter to the card's variable (in this case `video_id`). You can optionally set a default value for the variable. See [Connecting a filter or parameter widget to dashboard cards](./filters.md#connecting-a-filter-or-parameter-widget-to-dashboard-cards).
 
+If Metabase blocks the iframe, an admin needs to [allow iframes from that site](../configuring-metabase/domains.md#allow-iframes-from-a-site-in-dashboards).
+
 ## Dashboard tabs
 
 You can add multiple tabs to a dashboard to keep your cards organized.

docs/dashboards/markdown.md

@@ -96,7 +96,7 @@ To add an image, type an exclamation point (`!`), then a description of the imag
 ![A cat wearing a tiny hat](https://example.com/cat-in-hat.png)
 ```
 
-You can't upload an image to Metabase. Link to an image that's already online, using a URL your Metabase can access. Your admin can also [restrict which domains images load from](../configuring-metabase/settings.md#allowed-domains-for-images).
+You can't upload an image to Metabase. Link to an image that's already online, using a URL your Metabase can access. Your admin can also [restrict which domains images load from](../configuring-metabase/domains.md#restrict-where-images-can-load-from).
 
 The same syntax works for GIFs. Just use the URL of a GIF instead of an image.
 

docs/developers-guide/custom-visualizations.md

@@ -366,7 +366,7 @@ Canvas-based charting libraries (like ECharts and Chart.js) can't read CSS varia
 
 The build produces a single JavaScript bundle (`dist/index.js`), and the [icon](#the-visualization-icon) is the only file Metabase serves alongside it. Metabase doesn't serve arbitrary static files, so bundling images into your plugin is the most reliable approach. The [sandbox](#sandbox-restrictions) blocks scripted network access like `fetch` and `XMLHttpRequest`, but it doesn't stop the browser from loading an `<img>` or CSS `url()`: an external image still loads as long as its domain is allowed by the image-domains Content Security Policy (see below).
 
-Bundled images always render, including when an admin has turned on [Restrict image domains](../configuring-metabase/settings.md#restrict-image-domains). That Content Security Policy setting limits which external hosts images can load from, but inline and `data:` images ship inside your bundle, so they're never blocked.
+Bundled images always render, including when an admin has turned on [Restrict image domains](../configuring-metabase/domains.md#restrict-where-images-can-load-from). That Content Security Policy setting limits which external hosts images can load from, but inline and `data:` images ship inside your bundle, so they're never blocked.
 
 Your `npm` dependencies are bundled in too. You can pull in a charting library (the calendar-heatmap example bundles [ECharts](https://echarts.apache.org/)), but everything ships in that single `dist/index.js`, so your code and its dependencies all count toward the packaged plugin's [size limits](#build-and-package-the-plugin).
 

docs/embedding/custom-visualizations.md

@@ -77,7 +77,7 @@ Pass the `allowedCustomVisualizations` prop to `MetabaseProvider`. Like the page
 
 A custom visualization runs third-party JavaScript in your app. Metabase runs that code in an isolated sandbox, so a visualization can't reach the rest of your app or make network requests. The sandbox doesn't block passive image loads, though: a visualization can still trigger outbound requests through `<img>` tags or CSS `url()`.
 
-To limit where custom visualizations can load images from, set a [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CSP) with an `img-src` allowlist in your app. The core Metabase app sets this CSP with [Restrict image domains](../configuring-metabase/settings.md#restrict-image-domains), but you should also set a CSP in your app.
+To limit where custom visualizations can load images from, set a [Content Security Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CSP) with an `img-src` allowlist in your app. The core Metabase app sets this CSP with [Restrict image domains](../configuring-metabase/domains.md#restrict-where-images-can-load-from), but you should also set a CSP in your app.
 
 ## Custom visualizations don't work in guest embeds
 

docs/permissions/application.md

@@ -18,6 +18,7 @@ To set application permissions, go to the top right of the screen and click the
 Settings access defines which groups can view and edit the settings under the Admin > Settings tab. These settings include:
 
 - [Settings](../configuring-metabase/settings.md)
+- [Domains](../configuring-metabase/domains.md)
 - [Email](../configuring-metabase/email.md)
 - [Slack](../configuring-metabase/slack.md)
 - [Webhooks](../configuring-metabase/webhooks.md)

docs/questions/visualizations/custom.md

@@ -19,7 +19,7 @@ This page covers how to add a custom visualization to your Metabase. To _create_
 
 ### Restrict image domains first
 
-Before you can turn on custom visualizations, you need to enable [Restrict image domains](../../configuring-metabase/settings.md#restrict-image-domains). A custom visualization runs third-party JavaScript in your Metabase. By restricting image (and font) domains, you limit where that code can load assets from, which narrows the ways a custom visualization could leak data through outbound asset requests. See [Only add visualizations you trust](#only-add-visualizations-you-trust).
+Before you can turn on custom visualizations, you need to enable [Restrict image domains](../../configuring-metabase/domains.md#restrict-where-images-can-load-from). A custom visualization runs third-party JavaScript in your Metabase. By restricting image (and font) domains, you limit where that code can load assets from, which narrows the ways a custom visualization could leak data through outbound asset requests. See [Only add visualizations you trust](#only-add-visualizations-you-trust).
 
 While custom visualizations are enabled, you can't turn **Restrict image domains** back off. You'll need to first disable custom visualizations.
 

docs/util/data/nav.yml

@@ -427,6 +427,8 @@ categories:
             url: "configuring-metabase/setting-up-metabase"
           - name: "General settings"
             url: "configuring-metabase/settings"
+          - name: "Allowed domains"
+            url: "configuring-metabase/domains"
           - name: "Set up email"
             url: "configuring-metabase/email"
           - name: "Set up Slack"

frontend/src/metabase/admin/settings/components/SettingsPages/DomainsSettingsPage.tsx

@@ -42,11 +42,11 @@ export function DomainsSettingsPage() {
       "csp-img-allowed-hosts",
     ]);
 
-  const { url: iframeDocsUrl } = useDocsUrl("configuring-metabase/settings", {
-    anchor: "allowed-domains-for-iframes-in-dashboards",
+  const { url: iframeDocsUrl } = useDocsUrl("configuring-metabase/domains", {
+    anchor: "allow-iframes-from-a-site-in-dashboards",
   });
-  const { url: imgDocsUrl } = useDocsUrl("configuring-metabase/settings", {
-    anchor: "allowed-domains-for-images",
+  const { url: imgDocsUrl } = useDocsUrl("configuring-metabase/domains", {
+    anchor: "restrict-where-images-can-load-from",
   });
 
   const customVizAvailable = useHasTokenFeature("custom-viz-available");

frontend/src/metabase/dashboard/visualizations/IFrameViz/IFrameViz.tsx

@@ -163,8 +163,8 @@ function IFrameVizInner({
 function ForbiddenDomainError({ url }: { url: string }) {
   const isAdmin = useSelector(getUserIsAdmin);
   const { url: docsUrl, showMetabaseLinks } = useDocsUrl(
-    "configuring-metabase/settings",
-    { anchor: "allowed-domains-for-iframes-in-dashboards" },
+    "configuring-metabase/domains",
+    { anchor: "allow-iframes-from-a-site-in-dashboards" },
   );
 
   const domain = useMemo(() => {