Skip to content

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

Embedding wizard: fix docs link and show error when Site URL is misconfigured (#74635)

Sébastien2bfca17fa30a
diff --git a/e2e/test/scenarios/embedding/sdk-iframe-embedding/authentication.cy.spec.ts b/e2e/test/scenarios/embedding/sdk-iframe-embedding/authentication.cy.spec.ts
index f3f29dc26bc..5974b8650be 100644
--- a/e2e/test/scenarios/embedding/sdk-iframe-embedding/authentication.cy.spec.ts
+++ b/e2e/test/scenarios/embedding/sdk-iframe-embedding/authentication.cy.spec.ts
@@ -160,7 +160,7 @@ describe("scenarios > embedding > sdk iframe embedding > authentication", () =>
.should("have.attr", "href")
.and(
"include",
- "https://www.metabase.com/docs/latest/embedding/embedded-analytics-js#use-existing-user-session-to-test-embeds",
+ "https://www.metabase.com/docs/latest/embedding/authentication#configure-session-cookies-when-testing-locally",
);
cy.findByTestId("sdk-error-container").should("be.visible");
diff --git a/frontend/src/embedding-sdk-bundle/errors/error-docs-links.ts b/frontend/src/embedding-sdk-bundle/errors/error-docs-links.ts
index 7f594e71a38..fe6956b6cf4 100644
--- a/frontend/src/embedding-sdk-bundle/errors/error-docs-links.ts
+++ b/frontend/src/embedding-sdk-bundle/errors/error-docs-links.ts
@@ -10,5 +10,5 @@ type ErrorDocLinks = Partial<Record<MetabaseErrorCode, string>>;
export const ERROR_DOC_LINKS: ErrorDocLinks = {
EXISTING_USER_SESSION_FAILED:
// eslint-disable-next-line metabase/no-unconditional-metabase-links-render -- error documentation link
- "https://www.metabase.com/docs/latest/embedding/embedded-analytics-js#use-existing-user-session-to-test-embeds",
+ "https://www.metabase.com/docs/latest/embedding/authentication#configure-session-cookies-when-testing-locally",
};
diff --git a/frontend/src/metabase/embedding/embedding-iframe-sdk-setup/components/SdkIframeEmbedSetupModal.tsx b/frontend/src/metabase/embedding/embedding-iframe-sdk-setup/components/SdkIframeEmbedSetupModal.tsx
index d4564cab1fe..11864e1b056 100644
--- a/frontend/src/metabase/embedding/embedding-iframe-sdk-setup/components/SdkIframeEmbedSetupModal.tsx
+++ b/frontend/src/metabase/embedding/embedding-iframe-sdk-setup/components/SdkIframeEmbedSetupModal.tsx
@@ -7,9 +7,11 @@ import "react-resizable/css/styles.css";
import noResultsSource from "assets/img/no_results.svg";
import { useUpdateSettingsMutation } from "metabase/api";
+import { useSetting } from "metabase/common/hooks";
import { SdkIframeGuestEmbedStatusBar } from "metabase/embedding/embedding-iframe-sdk-setup/components/SdkIframeGuestEmbedStatusBar";
import { EMBED_STEPS } from "metabase/embedding/embedding-iframe-sdk-setup/constants";
import { isQuestionOrDashboardSettings } from "metabase/embedding/embedding-iframe-sdk-setup/utils/is-question-or-dashboard-settings";
+import { isSiteUrlMatchingCurrentOrigin } from "metabase/embedding/embedding-iframe-sdk-setup/utils/is-site-url-matching-current-origin";
import type { SdkIframeEmbedSetupModalProps } from "metabase/plugins";
import { useDispatch } from "metabase/redux";
import { closeModal } from "metabase/redux/ui";
@@ -32,6 +34,7 @@ import { useSdkIframeEmbedSetupContext } from "../context";
import { SdkIframeEmbedPreview } from "./SdkIframeEmbedPreview";
import S from "./SdkIframeEmbedSetup.module.css";
import { SdkIframeEmbedSetupProvider } from "./SdkIframeEmbedSetupProvider";
+import { SdkIframeEmbedSiteUrlMismatchError } from "./SdkIframeEmbedSiteUrlMismatchError";
export const SdkIframeEmbedSetupContent = () => {
const dispatch = useDispatch();
@@ -77,6 +80,9 @@ export const SdkIframeEmbedSetupContent = () => {
const isMissingResource =
isQuestionOrDashboard && !isLoading && (!resource || resource.archived);
+ const siteUrl = useSetting("site-url");
+ const isSiteUrlMismatched = !isSiteUrlMatchingCurrentOrigin(siteUrl);
+
const nextStepButton = match(currentStep)
.with("get-code", () => (
<Button
@@ -143,7 +149,11 @@ export const SdkIframeEmbedSetupContent = () => {
<SdkIframeGuestEmbedStatusBar />
{allowPreviewAndNavigation && !isMissingResource ? (
- <SdkIframeEmbedPreview />
+ isSiteUrlMismatched ? (
+ <SdkIframeEmbedSiteUrlMismatchError siteUrl={siteUrl} />
+ ) : (
+ <SdkIframeEmbedPreview />
+ )
) : (
<Card h="100%">
<Flex h="100%" align="center" justify="center">
diff --git a/frontend/src/metabase/embedding/embedding-iframe-sdk-setup/components/SdkIframeEmbedSiteUrlMismatchError.tsx b/frontend/src/metabase/embedding/embedding-iframe-sdk-setup/components/SdkIframeEmbedSiteUrlMismatchError.tsx
new file mode 100644
index 00000000000..d953bbf7a73
--- /dev/null
+++ b/frontend/src/metabase/embedding/embedding-iframe-sdk-setup/components/SdkIframeEmbedSiteUrlMismatchError.tsx
@@ -0,0 +1,56 @@
+import { jt, t } from "ttag";
+
+import { Link } from "metabase/common/components/Link";
+import { useSelector } from "metabase/redux";
+import { getApplicationName } from "metabase/selectors/whitelabel";
+import { Card, Code, Flex, Icon, Stack, Text } from "metabase/ui";
+
+interface SdkIframeEmbedSiteUrlMismatchErrorProps {
+ siteUrl: string;
+}
+
+export const SdkIframeEmbedSiteUrlMismatchError = ({
+ siteUrl,
+}: SdkIframeEmbedSiteUrlMismatchErrorProps) => {
+ const applicationName = useSelector(getApplicationName);
+
+ const siteUrlSettingLink = (
+ <Link key="link" to="/admin/settings/general" target="_blank">
+ {t`Site URL`}
+ </Link>
+ );
+
+ return (
+ <Card h="100%" data-testid="sdk-iframe-embed-site-url-mismatch-error">
+ <Flex
+ h="100%"
+ align="center"
+ justify="center"
+ direction="column"
+ gap="md"
+ maw={520}
+ mx="auto"
+ p="xl"
+ >
+ <Icon name="warning" size={48} c="warning" />
+
+ <Text fw="bold" size="lg" ta="center">
+ {t`The preview can't load because the Site URL doesn't match the host you're using.`}
+ </Text>
+
+ <Stack gap="xs" align="center">
+ <Text ta="center" c="text-secondary">
+ {jt`Configured: ${<Code key="configured">{siteUrl}</Code>}`}
+ </Text>
+ <Text ta="center" c="text-secondary">
+ {jt`Current: ${<Code key="current">{window.location.origin}</Code>}`}
+ </Text>
+ </Stack>
+
+ <Text ta="center">
+ {jt`Update the ${siteUrlSettingLink} setting to match the host you're using to access ${applicationName}, or open ${applicationName} via the configured Site URL.`}
+ </Text>
+ </Flex>
+ </Card>
+ );
+};
diff --git a/frontend/src/metabase/embedding/embedding-iframe-sdk-setup/components/tests/SdkIframeEmbedSetup.unit.spec.tsx b/frontend/src/metabase/embedding/embedding-iframe-sdk-setup/components/tests/SdkIframeEmbedSetup.unit.spec.tsx
index 6daf6c4d9dd..2f430d542c0 100644
--- a/frontend/src/metabase/embedding/embedding-iframe-sdk-setup/components/tests/SdkIframeEmbedSetup.unit.spec.tsx
+++ b/frontend/src/metabase/embedding/embedding-iframe-sdk-setup/components/tests/SdkIframeEmbedSetup.unit.spec.tsx
@@ -31,6 +31,64 @@ describe("Embed flow > initial setup", () => {
});
});
+describe("Embed flow > misconfigured Site URL (EMB-1747)", () => {
+ beforeEach(() => {
+ PLUGIN_EMBEDDING_IFRAME_SDK_SETUP.isEnabled = jest.fn(() => true);
+ });
+
+ afterEach(() => {
+ PLUGIN_EMBEDDING_IFRAME_SDK_SETUP.isEnabled = () => false;
+ });
+
+ it("renders a Site URL mismatch error in the preview area when the configured Site URL origin doesn't match the current host", async () => {
+ setup({
+ simpleEmbeddingEnabled: true,
+ siteUrl: "http://different-host.example:9999",
+ initialState: {
+ resourceType: "dashboard",
+ resourceId: 1,
+ isGuest: false,
+ useExistingUserSession: true,
+ },
+ });
+
+ expect(
+ await screen.findByTestId("sdk-iframe-embed-site-url-mismatch-error"),
+ ).toBeInTheDocument();
+
+ expect(
+ screen.getByText(/Site URL doesn't match the host/i),
+ ).toBeInTheDocument();
+
+ expect(
+ screen.getByText("http://different-host.example:9999"),
+ ).toBeInTheDocument();
+ });
+
+ it("does not render the Site URL mismatch error when origins match", async () => {
+ setup({
+ simpleEmbeddingEnabled: true,
+ siteUrl: window.location.origin,
+ initialState: {
+ resourceType: "dashboard",
+ resourceId: 1,
+ isGuest: false,
+ useExistingUserSession: true,
+ },
+ });
+
+ await waitFor(() => {
+ expect(
+ screen.getByTestId("sdk-iframe-embed-setup-modal-content"),
+ ).toBeInTheDocument();
+ });
+
+ expect(
+ screen.queryByTestId("sdk-iframe-embed-site-url-mismatch-error"),
+ ).not.toBeInTheDocument();
+ });
+});
+
describe("Embed flow > forward and backward navigation", () => {
beforeEach(() => {
PLUGIN_EMBEDDING_IFRAME_SDK_SETUP.isEnabled = jest.fn(() => true);
diff --git a/frontend/src/metabase/embedding/embedding-iframe-sdk-setup/components/tests/test-setup.tsx b/frontend/src/metabase/embedding/embedding-iframe-sdk-setup/components/tests/test-setup.tsx
index de55db721f8..1a7b23b5949 100644
--- a/frontend/src/metabase/embedding/embedding-iframe-sdk-setup/components/tests/test-setup.tsx
+++ b/frontend/src/metabase/embedding/embedding-iframe-sdk-setup/components/tests/test-setup.tsx
@@ -36,6 +36,7 @@ export const setup = (options?: {
initialState?: SdkIframeEmbedSetupModalInitialState;
hasEmailSetup?: boolean;
metabotEnabled?: boolean;
+ siteUrl?: string;
}) => {
const { enterprisePlugins } = options ?? {};
@@ -62,6 +63,9 @@ export const setup = (options?: {
"jwt-enabled-and-configured": options?.jwtReady ?? false,
"embedded-metabot-enabled?": options?.metabotEnabled ?? false,
"llm-metabot-configured?": options?.metabotEnabled ?? false,
+ // Default to the jsdom test origin so the embed wizard preview renders
+ // (mismatched origins surface a Site URL configuration error).
+ "site-url": options?.siteUrl ?? window.location.origin,
});
setupRecentViewsAndSelectionsEndpoints([], ["selections", "views"]);
diff --git a/frontend/src/metabase/embedding/embedding-iframe-sdk-setup/utils/is-site-url-matching-current-origin.ts b/frontend/src/metabase/embedding/embedding-iframe-sdk-setup/utils/is-site-url-matching-current-origin.ts
new file mode 100644
index 00000000000..da7cdd2f45e
--- /dev/null
+++ b/frontend/src/metabase/embedding/embedding-iframe-sdk-setup/utils/is-site-url-matching-current-origin.ts
@@ -0,0 +1,22 @@
+/**
+ * The embed wizard preview renders the Metabase instance in an iframe loaded
+ * from the configured Site URL. The page's CSP includes `frame-src 'self'`,
+ * which only allows iframes from the same origin as the wizard page. When the
+ * Site URL setting points to a different origin than the host the user is on
+ * (e.g. site-url=`localhost:3000` but accessed at `metabase.localhost:3000`),
+ * the iframe is silently blocked and the preview never loads.
+ */
+export const isSiteUrlMatchingCurrentOrigin = (
+ siteUrl: string | null | undefined,
+ currentOrigin: string = window.location.origin,
+): boolean => {
+ if (!siteUrl) {
+ return true;
+ }
+
+ try {
+ return new URL(siteUrl).origin === currentOrigin;
+ } catch {
+ return true;
+ }
+};
diff --git a/frontend/src/metabase/embedding/embedding-iframe-sdk-setup/utils/is-site-url-matching-current-origin.unit.spec.ts b/frontend/src/metabase/embedding/embedding-iframe-sdk-setup/utils/is-site-url-matching-current-origin.unit.spec.ts
new file mode 100644
index 00000000000..ade6ce6c308
--- /dev/null
+++ b/frontend/src/metabase/embedding/embedding-iframe-sdk-setup/utils/is-site-url-matching-current-origin.unit.spec.ts
@@ -0,0 +1,66 @@
+import { isSiteUrlMatchingCurrentOrigin } from "./is-site-url-matching-current-origin";
+
+describe("isSiteUrlMatchingCurrentOrigin", () => {
+ it("returns true when site URL origin matches the current origin", () => {
+ expect(
+ isSiteUrlMatchingCurrentOrigin(
+ "http://localhost:3000",
+ "http://localhost:3000",
+ ),
+ ).toBe(true);
+ });
+
+ it("ignores trailing slashes on the site URL", () => {
+ expect(
+ isSiteUrlMatchingCurrentOrigin(
+ "http://localhost:3000/",
+ "http://localhost:3000",
+ ),
+ ).toBe(true);
+ });
+
+ it("returns false when site URL host differs from the current host", () => {
+ expect(
+ isSiteUrlMatchingCurrentOrigin(
+ "http://localhost:3000",
+ "http://metabase.localhost:3000",
+ ),
+ ).toBe(false);
+ });
+
+ it("returns false when site URL port differs from the current port", () => {
+ expect(
+ isSiteUrlMatchingCurrentOrigin(
+ "http://localhost:4000",
+ "http://localhost:3000",
+ ),
+ ).toBe(false);
+ });
+
+ it("returns false when site URL scheme differs from the current scheme", () => {
+ expect(
+ isSiteUrlMatchingCurrentOrigin(
+ "http://example.com",
+ "https://example.com",
+ ),
+ ).toBe(false);
+ });
+
+ it("returns true when the site URL is empty or null (treated as not configured)", () => {
+ expect(isSiteUrlMatchingCurrentOrigin("", "http://localhost:3000")).toBe(
+ true,
+ );
+ expect(isSiteUrlMatchingCurrentOrigin(null, "http://localhost:3000")).toBe(
+ true,
+ );
+ expect(
+ isSiteUrlMatchingCurrentOrigin(undefined, "http://localhost:3000"),
+ ).toBe(true);
+ });
+
+ it("returns true when the site URL is malformed (let other validation surface it)", () => {
+ expect(
+ isSiteUrlMatchingCurrentOrigin("not a url", "http://localhost:3000"),
+ ).toBe(true);
+ });
+});