Full app embedding

Embed the entire Metabase application in an iframe with SSO integration

Full app embedding requires a Pro or Enterprise plan.

Full app embedding lets you embed the entire Metabase app in an iframe. It integrates your permissions and SSO to give people the right level of access to query and drill down into your data.

If you’re just starting with Metabase embedding, consider using Modular embedding instead—it’s more customizable and offers better control over individual components.

When to use full app embedding

Full app embedding is ideal when you want to:

• Embed all of Metabase’s functionality
• Provide a complete analytics workspace
• Give users access to the full Metabase experience
• Minimize setup time (less granular control needed)

Consider modular embedding if you need:

• Custom layouts for specific components
• Fine-grained control over UI elements
• Modern React-based integration
• Advanced theming and plugins

Full app embedding demo

Check out our Full app embedding demo to see it in action.

To see the query builder in action, click on Reports > + New > Question.

Prerequisites

1. License token

   Get a license token for a Pro or Enterprise plan.

2. Organize users into groups

   Create groups in Metabase for different user types or customers.

3. Set up permissions

   Configure permissions for each group to control data access.

4. Configure SSO

   Set up SSO to automatically apply permissions. We recommend JWT SSO.

For multi-tenant applications, see our guide on configuring permissions for different customer schemas.

Quick start

Check out the Full app embedding quick start guide for a hands-on tutorial.

Enable full app embedding in Metabase

1. Navigate to embedding settings

   Go to Admin > Embedding

2. Enable full app embedding

   Click Enable Full app embedding

3. Add authorized origins

   Under Authorized origins, add the URL of the website or web app where you want to embed Metabase (such as https://*.example.com)

Set up embedding on your website

Basic iframe setup

Create an iframe pointing to your Metabase URL:

Direct URL

Point directly to the Metabase page you want to embed:

<iframe
  src="https://metabase.yourcompany.com/dashboard/entity/Dc_7X8N7zf4iDK9Ps1M3b"
  frameborder="0"
  width="100%"
  height="800"
></iframe>

Authentication endpoint

Point to an auth endpoint that redirects to Metabase after login:

<iframe
  src="https://metabase.example.com/auth/sso?jwt=<token>&return_to=%2Fdashboard%2F1"
  frameborder="0"
  width="100%"
  height="800"
></iframe>

Pointing to a Metabase URL

To embed a specific page, use the Entity ID URL format:

1. Get the Entity ID

   1. Visit the dashboard, question, or collection in Metabase
   2. Click the info button (ⓘ)
   3. In the Overview tab, copy the Entity ID
2. Build the URL

   Use the format: /[item-type]/entity/[Entity-ID]

   Examples:

   • Dashboard: https://metabase.yourcompany.com/dashboard/entity/Dc_7X8N7zf4iDK9Ps1M3b
   • Question: https://metabase.yourcompany.com/question/entity/q1A2b3C4d5E6f7G8h9
   • Collection: https://metabase.yourcompany.com/collection/entity/c1A2b3C4d5E6
   • Model: https://metabase.yourcompany.com/model/entity/m1A2b3C4d5E6

Use Entity IDs instead of sequential IDs. Entity IDs are stable across different environments (staging, production), making them ideal for serialization.

Linking to a specific dashboard tab

If your dashboard has multiple tabs, add the tab ID to the URL:

https://metabase.yourcompany.com/dashboard/entity/Dc_7X8N7zf4iDK9Ps1M3b?tab=YLNdEYtzuSMA0lqO7u3FD

Get the tab ID from the URL when you select the tab in Metabase.

Pointing to an authentication endpoint

To send users directly to your SSO login screen (skipping the Metabase login page):

SAML example

https://metabase.example.com/auth/sso?return_to=http%3A%2F%2Fmetabase.yourcompany.com%2Fdashboard%2F1

URL encode all parameters in your redirect link, including filters (e.g., filter=value) and UI settings (e.g., top_nav=true).

Example with filters:

https://metabase.example.com/auth/sso?jwt=<token>&redirect=%2Fdashboard%2F1%3Ffilter1%3Dvalue%26filter2%3Dvalue

Cross-browser compatibility

To ensure full app embeds work in all browsers (especially Safari and iOS), put Metabase and the embedding app in the same top-level domain (TLD).

The TLD is the last part of a web address (.com, .org, etc.).

Example:

• ✅ Good: metabase.example.com embedded on app.example.com
• ❌ Problematic: metabase.example.com embedded on example.io

Your full app embed must be compatible with Safari to run on any browser in iOS (including Chrome on iOS, which uses Safari’s engine).

Embedding in a different domain

If you must embed Metabase in a different domain, configure the session cookie’s SameSite value:

1. Configure SameSite setting

   Go to Admin > Embedding > Security > SameSite cookie setting

2. Choose appropriate value

   Lax (default)

   For same-domain embedding in production.

   None

   For cross-domain embedding. Requires HTTPS. Incompatible with Safari and iOS browsers.

   Strict

   Disables session sharing. Use only if you don’t want embedding.

Alternatively, set the MB_SESSION_COOKIE_SAMESITE environment variable.

Safari users: You’ll need to allow cross-site tracking. Private/incognito tabs may also have issues.

Learn more about SameSite cookies.

Security best practices

Metabase uses HTTP cookies to authenticate people and keep them signed in.

Limit session duration

Set MAX_SESSION_AGE in minutes (default: 20,160 = two weeks).

Example: 24-hour sessions

MAX_SESSION_AGE=1440

Clear cookies on browser close

Automatically clear login cookies when users end their browser session:

MB_SESSION_COOKIES=true

Manual logout

Load this URL to log someone out (e.g., in a hidden iframe on your logout page):

https://metabase.yourcompany.com/auth/logout

JWT expiration

If using JWT SSO, set the exp property to a short duration (e.g., 1 minute).

For detailed auth flows, see Full app embedding with SSO.

Communication with embedded Metabase

Use postMessage to communicate between your app and the embedded Metabase:

Messages from embedded Metabase

Location changes

Listen for URL changes (e.g., when filters are applied):

window.addEventListener("message", (event) => {
  if (event.data.metabase?.type === "location") {
    console.log("URL changed:", event.data.metabase.location);
  }
});

Message format:

{
  "metabase": {
    "type": "location",
    "location": LOCATION_OBJECT_OR_URL
  }
}

Frame size (normal mode)

Set iframe to fill entire space:

{
  "metabase": {
    "type": "frame",
    "frame": {
      "mode": "normal"
    }
  }
}

Frame size (fit mode)

Set iframe to match content size:

{
  "metabase": {
    "type": "frame",
    "frame": {
      "mode": "fit",
      "height": HEIGHT_IN_PIXELS
    }
  }
}

Messages to embedded Metabase

Change the embedded URL programmatically:

const iframe = document.querySelector("iframe");
iframe.contentWindow.postMessage(
  {
    metabase: {
      type: "location",
      location: "/dashboard/2"
    }
  },
  "https://metabase.yourcompany.com"
);

Showing or hiding UI components

Control which Metabase UI components are visible using URL parameters. See full app UI components for details.

For more granular control over embedded components, use Modular embedding instead.

Group strategies for permissions

For multi-tenant applications where multiple users from a single customer need to collaborate:

1. Customer-specific groups

   Create one group per customer account. Users in this group can collaborate on questions and dashboards.

2. Security group

   Create a separate group for row and column security. Apply data permissions via attributes that span all customers.

3. Assign users to both

   Each user belongs to:

   • Their customer’s collaboration group
   • The security group with appropriate data permissions

This approach allows collaboration within customer accounts while maintaining proper data segregation.

Reference apps

Build a sample full app embed with these reference implementations:

Node.js + Express

With quick start guide

Node.js + React

Complete React implementation

Common use cases

Embed the home page

<iframe src="https://metabase.yourcompany.com/" />

Embed a specific dashboard

<iframe src="https://metabase.yourcompany.com/dashboard/entity/Dc_7X8N7zf4iDK9Ps1M3b" />

Embed with dashboard filters pre-applied

<iframe src="https://metabase.yourcompany.com/dashboard/1?status=active&date=2024-01-01" />

Embed a collection

<iframe src="https://metabase.yourcompany.com/collection/entity/c1A2b3C4d5E6" />

Embed with SSO redirect

<iframe src="https://metabase.example.com/auth/sso?jwt=<token>&return_to=%2Fdashboard%2F1" />

Troubleshooting

Cookies not working in Safari

• Ensure Metabase and your app are on the same top-level domain
• Or set SameSite to “None” (requires HTTPS, still may not work in Safari)
• Users may need to enable cross-site tracking in Safari settings

Authentication issues

• Verify JWT configuration in Admin > Settings > Authentication
• Check that JWT tokens have valid exp (expiration) values
• Ensure SSO endpoint returns tokens correctly
• Test with API key first for debugging

CORS errors

• Add your domain to Authorized origins in Admin > Embedding
• Make sure to include the protocol (https://)
• Wildcards are supported: https://*.example.com

Iframe not displaying

• Check browser console for errors
• Verify the Metabase URL is accessible
• Ensure your license token is valid
• Check that Full app embedding is enabled in Admin settings

Next steps

Quick start guide

Follow the step-by-step tutorial

Authentication

Set up JWT SSO

Permissions

Configure data access

UI components

Control visible UI elements

Further reading

• Strategies for delivering customer-facing analytics
• Permissions strategies
• Customizing Metabase’s appearance
• Securing embedded Metabase