Skip to content

The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:

docs - embedding intro edits (#80109)

Jeff Bruemmerfbd41598bfc7
diff --git a/docs/embedding/chart.md b/docs/embedding/chart.md
index 8c4b3faf59d..15f463943bf 100644
--- a/docs/embedding/chart.md
+++ b/docs/embedding/chart.md
@@ -23,10 +23,10 @@ A view-only (a.k.a. "static") chart displays results without letting people expl
View-only isn't tied to one kind of embed. You can make a chart view-only in any embedding type:
-- **[Guest embeds](./introduction.md#guest-embedding)**: always view-only. Nobody logs in to a guest embed, so Metabase has no account to check permissions against, and no way to tell whether a new query is one that person should be allowed to run. The published question is the only thing Metabase can safely run, which is why there's no drill-through or ad-hoc querying to turn off.
-- **[SSO embeds](./introduction.md#sso-embeds)**: interactive out of the box. To make one view-only, turn off drill-through with `drills="false"` (web component) or `drills={false}` (SDK), and turn off saving with `is-save-enabled="false"` or `isSaveEnabled={false}`. You can also manage what people can do through [data permissions](../permissions/data.md) and [collection permissions](../permissions/collections.md).
+- **[Guest embeds](./introduction.md#components-with-guest-authentication)**: always view-only. Nobody logs in to a guest embed, so Metabase has no account to check permissions against, and no way to tell whether a new query is one that person should be allowed to run. The published question is the only thing Metabase can safely run, which is why there's no drill-through or ad-hoc querying to turn off.
+- **[SSO embeds](./introduction.md#components-with-sso-authentication)**: interactive out of the box. To make one view-only, turn off drill-through with `drills="false"` (web component) or `drills={false}` (SDK), and turn off saving with `is-save-enabled="false"` or `isSaveEnabled={false}`. You can also manage what people can do through [data permissions](../permissions/data.md) and [collection permissions](../permissions/collections.md).
-So pick your authentication based on what your app needs---plans, permissions, whether Metabase should know who's viewing---not on whether you want a view-only chart. Check out [SSO or guest embeds](./introduction.md#comparison-between-sso-and-guest-embeds).
+So pick your authentication based on what your app needs---plans, permissions, whether Metabase should know who's viewing---not on whether you want a view-only chart. Check out [SSO or guest embeds](./introduction.md#comparison-between-sso-and-guest-authentication).
This section covers setting up a view-only chart with guest authentication.
diff --git a/docs/embedding/introduction.md b/docs/embedding/introduction.md
index 8ce3ddfd324..360a1055523 100644
--- a/docs/embedding/introduction.md
+++ b/docs/embedding/introduction.md
@@ -16,43 +16,24 @@ There are two ways to embed Metabase.
Most people go with modular embedding, so you can integrate Metabase components into your app.
+Whichever way you embed, you'll also pick how Metabase authenticates the people looking at it. Authentication is a setting on what you embed, not a different kind of embedding.
+
If you just want to share a chart or dashboard with anyone who has the link, and you don't need any authentication, take a look at [public links and embeds](#public-links-and-embeds).
## Modular embedding
-With [modular embedding](./modular-embedding.md), you can embed individual Metabase components in your web app. You can use guest embeds for basic functionality, or use SSO to take full advantage of Metabase.
-
-You can use two different ways to authenticate modular embeds:
-
-- [SSO](#sso-embeds)
-- [Guest](#guest-embedding)
-
-### SSO embeds
-
-With SSO, Metabase can know who's viewing what, which unlocks a lot of power. You can automatically apply [data permissions](../permissions/embedding.md), which means you can give people access to all the cool tools Metabase provides, and everyone will only ever see the data they're allowed to.
+With [modular embedding](./modular-embedding.md), you can embed individual Metabase [components](./components.md) in your web app: dashboards, questions, the query builder, AI chat, and a collection browser.
-**When to use SSO**: You want to offer multi-tenant, self-service analytics, or you want to include the query builder, AI chat, drill-through, or a collection browser.
-
-If you're building a SaaS product with embedded analytics for multiple customers, you can keep customer data isolated with [Tenants](./tenants.md).
+When you setting up an embed, you need to pick an authentication method:
-Accounts for these embedded users in your Metabase count toward the [accounts billed in your Metabase plan](https://www.metabase.com/docs/latest/cloud/how-billing-works). But by letting your customers self-serve their data, you save time on developing bespoke charts. And you can charge _more_ for a premium analytics experience. If you plan on giving a lot of your customers self-service access to their data, you should consider an enterprise plan, with custom pricing that scales with your business.
+- **Metabase account (SSO)**, for [components with SSO authentication](#components-with-sso-authentication)
+- **Guest**, for [components with guest authentication](#components-with-guest-authentication)
-### Guest embedding
+The authentication method you choose determines what people can do (see the comparison below).
-[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.
+You can only use one authentication method per page of your app. A single page can't mix a question that uses SSO with a question that uses guest authentication.
-**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).
-
-### Set up modular embeds with web components or React
-
-Whichever way you authenticate, you can set up modular embeds two ways.
-
-- **Web components**: a script tag plus HTML elements like `<metabase-question>`. Web components have no build step and no framework requirement, so they work in plain HTML, Vue, Svelte, Rails, React, or any framework you like. Metabase's [in-app wizard](./modular-embedding.md) writes the code for you.
-- **React SDK**: React components that you import and compose yourself. The [SDK](./sdk/introduction.md) gives you more control: you can build custom layouts and [customize behavior with plugins](./sdk/plugins.md).
-
-If your app runs on React and you want that extra control, go with the SDK. Otherwise start with web components. You can always move to the SDK later.
-
-## Comparison between SSO and guest embeds
+## Comparison between SSO and guest authentication
All SSO options require a Pro or Enterprise plan.
@@ -76,11 +57,40 @@ All SSO options require a Pro or Enterprise plan.
| Customize layouts and behavior with [plugins](./sdk/plugins.md) | ✅ | ❌ |
| [Locked filters](./guest-embedding.md#locked-parameters)\*\*\* | ❌ | ✅ |
-\* Each embedding type allows data downloads by default, but only [Pro and Enterprise](https://www.metabase.com/pricing/) plans can disable data downloads.
+\* Each authentication method allows data downloads by default, but only [Pro and Enterprise](https://www.metabase.com/pricing/) plans can disable data downloads.
+
+\*\* Requires a [Pro and Enterprise](https://www.metabase.com/pricing/) plan with either authentication method.
+
+\*\*\* Components that use SSO don't need locked filters. Since Metabase knows who's viewing, you can segregate data with [permissions](../permissions/embedding.md) instead. There's a little more set up, but much less long-term overhead.
-\*\* Requires a [Pro and Enterprise](https://www.metabase.com/pricing/) plan for any embedding type.
+### Components with SSO authentication
-\*\*\* SSO embeds don't need locked filters. Since Metabase knows who's viewing an SSO embed, you can segregate data with [permissions](../permissions/embedding.md) instead. There's a little more set up, but much less long-term overhead.
+With SSO, Metabase can know who's viewing what, which unlocks a lot of stuff. You can automatically apply [data permissions](../permissions/embedding.md), which means you can give people access to all the cool tools Metabase provides, and everyone will only ever see the data they're allowed to.
+
+**When to use SSO**: You want to offer multi-tenant, self-service analytics, or you want to include the query builder, AI chat, drill-through, or a collection browser.
+
+SSO requires a Pro or Enterprise plan, and everyone viewing the embedded component needs their own Metabase account. To set up JWT or SAML, check out [modular embedding authentication](./authentication.md).
+
+If you're building a SaaS product with embedded analytics for multiple customers, you can keep customer data isolated with [Tenants](./tenants.md).
+
+Accounts for these embedded people in your Metabase count toward the [accounts billed in your Metabase plan](https://www.metabase.com/docs/latest/cloud/how-billing-works). But by letting your customers self-serve their data, you save time on developing bespoke charts. And you can charge _more_ for a premium analytics experience. If you plan on giving a lot of your customers self-service access to their data, you should consider an enterprise plan, with custom pricing that scales with your business.
+
+### Components with guest authentication
+
+With [guest authentication](./guest-embedding.md), Metabase doesn't create a session for the person viewing the component, so you don't have to create a Metabase account for everyone who sees your charts and dashboards. Guest authentication works on all Metabase plans, including OSS and Starter.
+
+Guest doesn't mean unsecured. Metabase only loads the component if the request carries a JWT signed with a secret shared between your app and your Metabase. What Metabase doesn't have is an identity: with no account to check permissions against, Metabase can't tell whether a new query is one that person should be allowed to run. That's why components with guest authentication are view-only.
+
+**When to use guest**: embedding charts and dashboards where you don't want to offer ad-hoc querying or chart drill-through. To filter data down to what's relevant to the person viewing, use [locked parameters](./guest-embedding.md#locked-parameters), where your app sets the filter value in the signed token.
+
+## Set up modular embeds with web components or React
+
+Whichever way you authenticate, you can set up modular embeds two ways.
+
+- **Web components**: a script tag plus HTML elements like `<metabase-question>`. Web components have no build step and no framework requirement, so they work in plain HTML, Vue, Svelte, Rails, React, or any framework you like. Metabase's [in-app wizard](./modular-embedding.md) writes the code for you.
+- **React SDK**: React components that you import and compose yourself. The [SDK](./sdk/introduction.md) gives you more control: you can build custom layouts and [customize behavior with plugins](./sdk/plugins.md).
+
+If your app runs on React and you want that extra control, go with the SDK. Otherwise start with web components. You can always move to the SDK later.
## Full app embedding
@@ -107,7 +117,7 @@ For information about the anonymous usage data Metabase collects from embedded c
## Embedding limitations
- Currently, you can't embed [documents](../documents/introduction.md) (though you can create [public documents](./public-links.md)).
-- [Modular embeds](./modular-embedding.md) that use SSO can render [custom visualizations](../questions/visualizations/custom.md), but only the custom visualizations you add to your [allowlist](./custom-visualizations.md). Guest embeds fall back to the default visualization.
+- [Modular embeds](./modular-embedding.md) that use SSO can render [custom visualizations](../questions/visualizations/custom.md), but only the custom visualizations you add to your [allowlist](./custom-visualizations.md). Components that use guest authentication fall back to the default visualization.
## Further reading
diff --git a/docs/embedding/modular-embedding.md b/docs/embedding/modular-embedding.md
index 45b4c7e04c9..6821daad9f4 100644
--- a/docs/embedding/modular-embedding.md
+++ b/docs/embedding/modular-embedding.md
@@ -51,7 +51,7 @@ You can also go to **Admin > Embedding > Modular embedding** and click **New emb
{% include plans-blockquote.html feature="Authenticated modular embedding" convert_pro_link_to_embedding=true %}
-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-between-sso-and-guest-embeds)).
+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-between-sso-and-guest-authentication)).
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).
diff --git a/docs/embedding/query-builder.md b/docs/embedding/query-builder.md
index b663c85d0fb..13ae64ddf75 100644
--- a/docs/embedding/query-builder.md
+++ b/docs/embedding/query-builder.md
@@ -12,7 +12,7 @@ You can embed one of Metabase's query editors so people can build questions from
- [Visual query builder](#embed-the-visual-query-builder)
- [SQL editor](#embed-the-sql-editor)
-Both query editors need a logged-in Metabase account: to run a new query, Metabase has to know who's asking, so it can work out which data they're allowed to see. In an embed, [SSO](./introduction.md#sso-embeds) is how you provide that account, so neither editor works in a [guest embed](./introduction.md#guest-embedding). Check out [SSO or guest embeds](./introduction.md#comparison-between-sso-and-guest-embeds).
+Both query editors need a logged-in Metabase account: to run a new query, Metabase has to know who's asking, so it can work out which data they're allowed to see. In an embed, [SSO](./introduction.md#components-with-sso-authentication) is how you provide that account, so neither editor works in a [guest embed](./introduction.md#components-with-guest-authentication). Check out [SSO or guest embeds](./introduction.md#comparison-between-sso-and-guest-authentication).
And because everyone queries through their own Metabase account, people can only build questions on databases their groups have permission to query. See [data permissions](../permissions/data.md).