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 intro edits (#80109)
Jeff Bruemmerfbd41598bfc7
diff --git a/docs/embedding/chart.md b/docs/embedding/chart.mdindex 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 explView-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.mdindex 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 authenticationAll 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 readingdiff --git a/docs/embedding/modular-embedding.md b/docs/embedding/modular-embedding.mdindex 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.mdindex 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).