The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:
TypeScript analyticsbibusiness-intelligencebusinessintelligenceclojuredashboarddatadata-analysisdata-visualizationdatabasemetabasemysqlpostgrespostgresqlreportingslacksql-editorvisualization
docs - embedding edits (#68567)
Jeff Bruemmer781282dd4055
diff --git a/docs/embedding/authentication.md b/docs/embedding/authentication.mdindex a4882947d1c..d97e469db72 100644--- a/docs/embedding/authentication.md+++ b/docs/embedding/authentication.md@@ -280,3 +280,33 @@ app.get("/sso/metabase", async (req, res) => {}});```++## Embedding Metabase in a different domain++{% include plans-blockquote.html feature="Authenticated modular embeds" convert_pro_link_to_embbedding=true is_plural=true %}++This section applies only to **authenticated embeds**. Guest embeds work cross-domain without additional configuration.++If you want to embed Metabase in another domain (say, if Metabase is hosted at `metabase.yourcompany.com`, but you want to embed Metabase at `yourcompany.github.io`), you'll need to [allow your domain in CORS](#allow-your-domain-in-cors).++### Allow your domain in CORS++Go to **Admin settings** > **Embedding** > **Modular embedding** and add your embedding domain under **Cross-Origin Resource Sharing (CORS)** (such as `https://*.example.com`).++### Configure session cookies when testing locally++When you use `useExistingUserSession: true` during development on a different domain, the browser must send the existing Metabase session cookie cross-origin into the iframe. To allow this, you'll need to set the session cookie's SameSite value to "none".++You can set session cookie's SameSite value in **Admin settings** > **Embedding** > **Security** > **SameSite cookie setting**.++SameSite values include:++- **Lax** (default): Allows Metabase session cookies to be shared on the same domain. Used for production instances on the same domain.+- **None (requires HTTPS)**: Use "None" when your app and Metabase are hosted on different domains. Incompatible with Safari and iOS-based browsers.+- **Strict** (not recommended): Does not allow Metabase session cookies to be shared with embedded instances. Use this if you do not want to enable session sharing with embedding.++You can also set the [`MB_SESSION_COOKIE_SAMESITE` environment variable](../configuring-metabase/environment-variables.md#mb_session_cookie_samesite).++If you're using Safari, you'll need to [allow cross-site tracking](https://support.apple.com/en-tj/guide/safari/sfri40732/mac). Depending on the browser, you may also run into issues when viewing embedded items in private/incognito tabs.++Learn more about [SameSite cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite).diff --git a/docs/embedding/introduction.md b/docs/embedding/introduction.mdindex d68b634e524..1e707f1ba88 100644--- a/docs/embedding/introduction.md+++ b/docs/embedding/introduction.md@@ -46,9 +46,9 @@ With SSO, Metabase can know who's viewing what, which unlocks a lot of power. Yo### Guest embedding-[Guest embeds](./guest-embedding.md) are a secure way to embed charts and dashboards.+[Guest embeds](./guest-embedding.md) are a secure way to embed charts and dashboards. Guest embedding works on all Metabase plans, including OSS and Starter.-**When to use guest embeds**: simple embedding use cases where you don't want to offer ad-hoc querying or chart drill-through. To filter data relevant to the viewer, you can use guest embeds with [locked parameters](./static-embedding-parameters.md#locked-parameters-limit-the-values-available-to-other-editable-parameters).+**When to use guest embeds**: simple embedding use cases where you don't want to offer ad-hoc querying or chart drill-through. To filter data relevant to the viewer, you can use guest embeds with [locked parameters](./guest-embedding.md#locked-parameters).## Public links and embedsdiff --git a/docs/embedding/modular-embedding.md b/docs/embedding/modular-embedding.mdindex 0376c359543..2c4c5e8e787 100644--- a/docs/embedding/modular-embedding.md+++ b/docs/embedding/modular-embedding.md@@ -15,12 +15,19 @@ Modular embedding lets you embed and customize Metabase [components](./componentIf you're using React, check out the [Modular embedding SDK](./sdk/introduction.md).+> **Want guest embeds?** For modular embedding without authentication (available on all plans), see [Guest Embeds](./guest-embedding.md).+## Enable modular embedding1. In Metabase, go to **Admin settings > Embedding**.2. Toggle on **Enable modular embedding**.++**For guest embeds**: You're done! Skip to [Create a new embed](#create-a-new-embed) or see the [Guest embedding guide](./guest-embedding.md) for detailed setup instructions.++**For authenticated embeds** (Pro/Enterprise only), some more steps:+3. Under **Cross-Origin Resource Sharing (CORS)**, add the URLs of the websites where you want to embed Metabase (such as `https://*.example.com`). For testing embeds, you can use `localhost` which is always included in CORS policy.-4. If you're embedding Metabase components in a domain that's different from your Metabase's domain (including when you're testing the app locally but use Metabase Cloud), go to **Admin settings > Embedding > Security** and set **SameSite cookie** to **None**.+4. If embedding on a different domain, see [Embedding Metabase in a different domain](./authentication.md#embedding-metabase-in-a-different-domain).## Create a new embed@@ -46,7 +53,9 @@ You can also go to **Admin settings > Embedding > Modular embedding** and click{% include plans-blockquote.html feature="Authenticated modular embedding" convert_pro_link_to_embbedding=true %}-How you authenticate the embed determines how cool the embed can get. This page covers the SSO setup, which lets you do everything. This setup requires you to have [set up SSO for your Metabase](./authentication.md). You can check out a [comparison between SSO and guest](./introduction.md#comparison-of-embedding-types), or jump straight to the [guest embed docs](./guest-embedding.md). But we recommend setting up modular embedding with SSO.+With SSO, Metabase can know who is viewing the embed, and it can unlock all of its bells and whistles (see this [comparison between SSO and guest embeds](./introduction.md#comparison-of-embedding-types)).++This page covers the [SSO setup for your Metabase](./authentication.md). If you don't need to set up SSO, check out the [guest embed docs](./guest-embedding.md).### 3. Customize your embed@@ -177,48 +186,4 @@ To define the configuration that applies to every embed on the page, use the `de## Authentication-### Use API keys to test embeds--> API keys can only be used for testing embeds locally. To make your embeds production-ready or deploy them to another domain, you'll need to implement SSO.--To use an API key to test your embeds:--1. Create an [API key](../people-and-groups/api-keys.md)-2. Add `apiKey: "YOUR_API_KEY"` to `defineMetabaseConfig()`:--```html-<script>- defineMetabaseConfig({- instanceUrl: "https://your-metabase-url",- apiKey: "mb_hopeyouhaveaniceday",- });-</script>-```--API keys should only be used for testing with trusted people. Anyone with access to the front-end can grab the API key and use it to make requests against the Metabase API. For this reason, we only allow using API keys on localhost.--## Embedding Metabase in a different domain--{% include plans-blockquote.html feature="Authenticated modular embeds" convert_pro_link_to_embbedding=true is_plural=true %}--If you want to embed Metabase in another domain (say, if Metabase is hosted at `metabase.yourcompany.com`, but you want to embed Metabase at `yourcompany.github.io`), you can tell Metabase to set the session cookie's SameSite value to "none".--You can set session cookie's SameSite value in **Admin settings** > **Embedding** > **Security** > **SameSite cookie setting**.--SameSite values include:--- **Lax** (default): Allows Metabase session cookies to be shared on the same domain. Used for production instances on the same domain.-- **None (requires HTTPS)**: Use "None" when your app and Metabase are hosted on different domains. Incompatible with Safari and iOS-based browsers.-- **Strict** (not recommended): Does not allow Metabase session cookies to be shared with embedded instances. Use this if you do not want to enable session sharing with embedding.--You can also set the [`MB_SESSION_COOKIE_SAMESITE` environment variable](../configuring-metabase/environment-variables.md#mb_session_cookie_samesite).--If you're using Safari, you'll need to [allow cross-site tracking](https://support.apple.com/en-tj/guide/safari/sfri40732/mac). Depending on the browser, you may also run into issues when viewing embedded items in private/incognito tabs.--Learn more about [SameSite cookies](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite).--## Setting up SSO--{% include plans-blockquote.html feature="Authenticated modular embeds" convert_pro_link_to_embbedding=true is_plural=true %}--For production use, you'll need to set up SSO authentication. See [Modular embedding - authentication](./authentication.md) for details on setting up JWT or SAML authentication.+For authentication setup including API keys for local testing, SSO with JWT/SAML, and cross-domain configuration, see [Modular embedding - authentication](./authentication.md).diff --git a/docs/embedding/start.md b/docs/embedding/start.mdindex 2352e65cc76..44def237dd8 100644--- a/docs/embedding/start.md+++ b/docs/embedding/start.md@@ -14,6 +14,8 @@ What is embedding, and how does it work?Embed individual dashboards, questions, or the query builder in your app with an interactive wizard and simple drop-in script, with minimal or no coding required. Control component UI and theming. Integrate your app's auth with Metabase SSO.+If you're on Metabase OSS or Starter, you can only embed components without SSO. See [Guest embeds](./guest-embedding.md).+### [Modular embedding SDK](./sdk/introduction.md)With the Modular embedding SDK, you can embed individual Metabase components with React (like standalone charts, dashboards, the query builder, and more). You can manage access and interactivity per component, and you have advanced customization for seamless styling.@@ -24,11 +26,7 @@ Jump to a SDK quickstart with a sample React application.### [Guest embedding](./guest-embedding.md)-Guest embedding is a secure way to embed charts and dashboards. Guest embeds are view only; people won't be able to drill-through charts and tables.--### [Parameters for guest embeds](./static-embedding-parameters.md)--You can pass parameters between Metabase and your website via the embedding URL to specify how Metabase items should look and behave inside the iframe on your website.+Guest embedding is a secure way to embed charts and dashboards. Guest embeds are view-only; people won't be able to drill-through charts and tables.### [Translating guest embeds](./translations.md)