Skip to content

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

feat(embed-js): better error message when useExistingUserSession fails (#63125)

Phoomparin Mano3fddbec54e20
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 0afcf0c5844..8f76dc43d40 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
@@ -48,6 +48,37 @@ describe("scenarios > embedding > sdk iframe embedding > authentication", () =>
assertDashboardLoaded(frame);
});
+ it("cannot use existing user session when there is no session", () => {
+ H.prepareSdkIframeEmbedTest({ enabledAuthMethods: [], signOut: true });
+
+ const frame = H.loadSdkIframeEmbedTestPage({
+ elements: [
+ {
+ component: "metabase-dashboard",
+ attributes: { dashboardId: ORDERS_DASHBOARD_ID },
+ },
+ ],
+
+ metabaseConfig: { useExistingUserSession: true },
+ });
+
+ frame.within(() => {
+ cy.findByTestId("sdk-error-container", { timeout: 10_000 }).should(
+ "contain",
+ /Failed to authenticate using an existing Metabase user session./,
+ );
+
+ cy.findByRole("link", { name: "Read more." })
+ .should("have.attr", "href")
+ .and(
+ "include",
+ "https://www.metabase.com/docs/latest/embedding/embedded-analytics-js#use-existing-user-session-to-test-embeds",
+ );
+
+ cy.findByTestId("sdk-error-container").should("be.visible");
+ });
+ });
+
it("cannot use existing user session when useExistingUserSession is false", () => {
H.prepareSdkIframeEmbedTest({ enabledAuthMethods: [], signOut: false });
diff --git a/enterprise/frontend/src/embedding-sdk-bundle/components/private/PublicComponentWrapper/PublicComponentWrapper.tsx b/enterprise/frontend/src/embedding-sdk-bundle/components/private/PublicComponentWrapper/PublicComponentWrapper.tsx
index 148031fab29..ceb331824da 100644
--- a/enterprise/frontend/src/embedding-sdk-bundle/components/private/PublicComponentWrapper/PublicComponentWrapper.tsx
+++ b/enterprise/frontend/src/embedding-sdk-bundle/components/private/PublicComponentWrapper/PublicComponentWrapper.tsx
@@ -31,7 +31,9 @@ export const PublicComponentWrapper = forwardRef<
}
if (loginStatus.status === "error") {
- content = <SdkError message={loginStatus.error.message} />;
+ content = (
+ <SdkError message={loginStatus.error.message} error={loginStatus.error} />
+ );
}
// The SDK components should not load if there is a license error.
diff --git a/enterprise/frontend/src/embedding-sdk-bundle/components/private/PublicComponentWrapper/SdkError.tsx b/enterprise/frontend/src/embedding-sdk-bundle/components/private/PublicComponentWrapper/SdkError.tsx
index 0bcd5637e23..aa87cdd4480 100644
--- a/enterprise/frontend/src/embedding-sdk-bundle/components/private/PublicComponentWrapper/SdkError.tsx
+++ b/enterprise/frontend/src/embedding-sdk-bundle/components/private/PublicComponentWrapper/SdkError.tsx
@@ -1,17 +1,20 @@
import { useDisclosure } from "@mantine/hooks";
-import type { CSSProperties, PropsWithChildren } from "react";
+import { type CSSProperties, type PropsWithChildren, useMemo } from "react";
import { jt, t } from "ttag";
+import { ERROR_DOC_LINKS } from "embedding-sdk-bundle/errors";
+import type { MetabaseErrorCode } from "embedding-sdk-bundle/errors/error-code";
import { useSdkSelector } from "embedding-sdk-bundle/store";
import { getErrorComponent } from "embedding-sdk-bundle/store/selectors";
import type { SdkErrorComponentProps } from "embedding-sdk-bundle/types";
import Alert from "metabase/common/components/Alert";
import { EMBEDDING_SDK_PORTAL_ROOT_ELEMENT_ID } from "metabase/embedding-sdk/config";
import { color } from "metabase/lib/colors";
-import { Box, Center, Code, Flex, Portal } from "metabase/ui";
+import { Anchor, Box, Center, Code, Flex, Portal } from "metabase/ui";
export const SdkError = ({
message,
+ error,
type = "relative",
withCloseButton = false,
}: Omit<SdkErrorComponentProps, "onClose">) => {
@@ -19,6 +22,27 @@ export const SdkError = ({
const CustomError = useSdkSelector(getErrorComponent);
+ const errorMessage = useMemo(() => {
+ if (error && "code" in error && typeof error.code === "string") {
+ const docsLink = ERROR_DOC_LINKS[error.code as MetabaseErrorCode];
+
+ if (docsLink) {
+ return (
+ <span>
+ {error.message || message}{" "}
+ <Anchor
+ href={docsLink}
+ target="_blank"
+ rel="noopener noreferrer"
+ >{t`Read more.`}</Anchor>
+ </span>
+ );
+ }
+ }
+
+ return message;
+ }, [message, error]);
+
if (!visible) {
return null;
}
@@ -33,7 +57,7 @@ export const SdkError = ({
<Center h="100%" w="100%" mx="auto" data-testid="sdk-error-container">
<ErrorMessageComponent
type={type}
- message={message}
+ message={errorMessage}
{...(withCloseButton && {
onClose: handleBannerClose,
})}
diff --git a/enterprise/frontend/src/embedding-sdk-bundle/errors/base.ts b/enterprise/frontend/src/embedding-sdk-bundle/errors/base.ts
index eb2c61849b6..e3ab7948cc0 100644
--- a/enterprise/frontend/src/embedding-sdk-bundle/errors/base.ts
+++ b/enterprise/frontend/src/embedding-sdk-bundle/errors/base.ts
@@ -1,4 +1,6 @@
-export class MetabaseError<C extends string, P> extends Error {
+import type { MetabaseErrorCode } from "./error-code";
+
+export class MetabaseError<C extends MetabaseErrorCode, P> extends Error {
public readonly code: C;
public readonly params?: P;
diff --git a/enterprise/frontend/src/embedding-sdk-bundle/errors/error-code.ts b/enterprise/frontend/src/embedding-sdk-bundle/errors/error-code.ts
new file mode 100644
index 00000000000..ceecd6e1ac1
--- /dev/null
+++ b/enterprise/frontend/src/embedding-sdk-bundle/errors/error-code.ts
@@ -0,0 +1,17 @@
+export type MetabaseErrorCode =
+ | "EXISTING_USER_SESSION_FAILED"
+ | "SDK_VERSION_INCOMPATIBLE"
+ | "INVALID_SESSION_OBJECT"
+ | "INVALID_SESSION_SCHEMA"
+ | "BACKEND_ERROR_STATUS"
+ | "CUSTOM_FETCH_ERROR"
+ | "DEFAULT_ENDPOINT_ERROR"
+ | "CANNOT_FETCH_JWT_TOKEN"
+ | "SAML_POPUP_BLOCKED"
+ | "SAML_POPUP_CLOSED"
+ | "SAML_TIMEOUT"
+ | "USER_FETCH_FAILED"
+ | "CANNOT_CONNECT_TO_INSTANCE"
+ | "INVALID_AUTH_METHOD"
+ | "AUTH_TIMEOUT"
+ | "EMBED_TAG_ERROR";
diff --git a/enterprise/frontend/src/embedding-sdk-bundle/errors/error-docs-links.ts b/enterprise/frontend/src/embedding-sdk-bundle/errors/error-docs-links.ts
new file mode 100644
index 00000000000..9395d087b94
--- /dev/null
+++ b/enterprise/frontend/src/embedding-sdk-bundle/errors/error-docs-links.ts
@@ -0,0 +1,14 @@
+import type { MetabaseErrorCode } from "./error-code";
+
+type ErrorDocLinks = Partial<Record<MetabaseErrorCode, string>>;
+
+/**
+ * Provide documentation links for each error codes.
+ * Custom fields get removed when serializing errors, so
+ * we need to store doc urls separately.
+ **/
+export const ERROR_DOC_LINKS: ErrorDocLinks = {
+ EXISTING_USER_SESSION_FAILED:
+ // eslint-disable-next-line 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",
+};
diff --git a/enterprise/frontend/src/embedding-sdk-bundle/errors/generic.ts b/enterprise/frontend/src/embedding-sdk-bundle/errors/generic.ts
index e3c1773a837..7c9c425d70b 100644
--- a/enterprise/frontend/src/embedding-sdk-bundle/errors/generic.ts
+++ b/enterprise/frontend/src/embedding-sdk-bundle/errors/generic.ts
@@ -42,3 +42,11 @@ export function AUTH_TIMEOUT() {
"Authentication has not been completed in time.",
);
}
+
+export function EXISTING_USER_SESSION_FAILED() {
+ return new MetabaseError(
+ "EXISTING_USER_SESSION_FAILED",
+ // eslint-disable-next-line no-literal-metabase-strings -- developer-facing error message explaining authentication failure
+ "Failed to authenticate using an existing Metabase user session.",
+ );
+}
diff --git a/enterprise/frontend/src/embedding-sdk-bundle/errors/index.ts b/enterprise/frontend/src/embedding-sdk-bundle/errors/index.ts
index e66dfc3f2bf..b8add82f3d3 100644
--- a/enterprise/frontend/src/embedding-sdk-bundle/errors/index.ts
+++ b/enterprise/frontend/src/embedding-sdk-bundle/errors/index.ts
@@ -3,3 +3,4 @@ export * from "./jwt";
export * from "./version";
export * from "./saml";
export * from "./generic";
+export * from "./error-docs-links";
diff --git a/enterprise/frontend/src/embedding-sdk-bundle/store/auth/auth.ts b/enterprise/frontend/src/embedding-sdk-bundle/store/auth/auth.ts
index ae8d9091a1b..50cdfb1b3a6 100644
--- a/enterprise/frontend/src/embedding-sdk-bundle/store/auth/auth.ts
+++ b/enterprise/frontend/src/embedding-sdk-bundle/store/auth/auth.ts
@@ -80,6 +80,10 @@ export const initAuth = createAsyncThunk(
]);
if (!user.payload) {
+ if (EMBEDDING_SDK_IFRAME_EMBEDDING_CONFIG.useExistingUserSession) {
+ throw MetabaseError.EXISTING_USER_SESSION_FAILED();
+ }
+
throw MetabaseError.USER_FETCH_FAILED();
}
if (!siteSettings.payload) {
diff --git a/enterprise/frontend/src/embedding-sdk-bundle/types/ui.ts b/enterprise/frontend/src/embedding-sdk-bundle/types/ui.ts
index f82a6aeac5a..344dd0a1141 100644
--- a/enterprise/frontend/src/embedding-sdk-bundle/types/ui.ts
+++ b/enterprise/frontend/src/embedding-sdk-bundle/types/ui.ts
@@ -12,6 +12,7 @@ export type { MetabaseFontFamily } from "metabase/embedding-sdk/theme/fonts";
export type SdkErrorComponentProps = {
type?: "relative" | "fixed";
message: ReactNode;
+ error?: Error;
withCloseButton?: boolean;
onClose?: () => void;
};
@@ -19,4 +20,5 @@ export type SdkErrorComponentProps = {
export type SdkErrorComponent = ({
type,
message,
+ error,
}: SdkErrorComponentProps) => JSX.Element;
diff --git a/enterprise/frontend/src/metabase-enterprise/embedding_iframe_sdk/components/SdkIframeEmbedRoute.tsx b/enterprise/frontend/src/metabase-enterprise/embedding_iframe_sdk/components/SdkIframeEmbedRoute.tsx
index a66589bce02..7644115667b 100644
--- a/enterprise/frontend/src/metabase-enterprise/embedding_iframe_sdk/components/SdkIframeEmbedRoute.tsx
+++ b/enterprise/frontend/src/metabase-enterprise/embedding_iframe_sdk/components/SdkIframeEmbedRoute.tsx
@@ -1,6 +1,8 @@
import type { ReactNode } from "react";
import { P, match } from "ts-pattern";
+import { PublicComponentStylesWrapper } from "embedding-sdk-bundle/components/private/PublicComponentStylesWrapper";
+import { SdkError } from "embedding-sdk-bundle/components/private/PublicComponentWrapper";
import { SdkBreadcrumbsProvider } from "embedding-sdk-bundle/components/private/SdkBreadcrumbs";
import { ComponentProvider } from "embedding-sdk-bundle/components/public/ComponentProvider";
import { SdkQuestion } from "embedding-sdk-bundle/components/public/SdkQuestion";
@@ -9,7 +11,8 @@ import {
InteractiveDashboard,
StaticDashboard,
} from "embedding-sdk-bundle/components/public/dashboard";
-import { getSdkStore } from "embedding-sdk-bundle/store";
+import { getSdkStore, useSdkSelector } from "embedding-sdk-bundle/store";
+import { getLoginStatus } from "embedding-sdk-bundle/store/selectors";
import type { MetabaseAuthConfig } from "embedding-sdk-package";
import { EMBEDDING_SDK_IFRAME_EMBEDDING_CONFIG } from "metabase/embedding-sdk/config";
import { createTracker } from "metabase/lib/analytics-untyped";
@@ -92,6 +95,18 @@ const SdkIframeEmbedView = ({
settings: SdkIframeEmbedSettings;
}): ReactNode => {
const rerenderKey = useParamRerenderKey(settings);
+ const loginStatus = useSdkSelector(getLoginStatus);
+
+ if (loginStatus?.status === "error") {
+ return (
+ <PublicComponentStylesWrapper>
+ <SdkError
+ error={loginStatus.error}
+ message={loginStatus.error.message}
+ />
+ </PublicComponentStylesWrapper>
+ );
+ }
return match(settings)
.with(
diff --git a/enterprise/frontend/src/metabase-enterprise/embedding_iframe_sdk/embed.ts b/enterprise/frontend/src/metabase-enterprise/embedding_iframe_sdk/embed.ts
index 01c985cceeb..08462fd5f46 100644
--- a/enterprise/frontend/src/metabase-enterprise/embedding_iframe_sdk/embed.ts
+++ b/enterprise/frontend/src/metabase-enterprise/embedding_iframe_sdk/embed.ts
@@ -93,7 +93,7 @@ if (typeof window !== "undefined") {
}
const raiseError = (message: string) => {
- throw new MetabaseError("EMBED_ERROR", message);
+ throw new MetabaseError("EMBED_TAG_ERROR", message);
};
function assertFieldCanBeUpdated(
diff --git a/enterprise/frontend/src/metabase-enterprise/embedding_iframe_sdk/types/embed.ts b/enterprise/frontend/src/metabase-enterprise/embedding_iframe_sdk/types/embed.ts
index 3d2d02500a8..7452aa18726 100644
--- a/enterprise/frontend/src/metabase-enterprise/embedding_iframe_sdk/types/embed.ts
+++ b/enterprise/frontend/src/metabase-enterprise/embedding_iframe_sdk/types/embed.ts
@@ -1,4 +1,5 @@
import type { MetabaseError } from "embedding-sdk-bundle/errors";
+import type { MetabaseErrorCode } from "embedding-sdk-bundle/errors/error-code";
import type { MetabaseAuthMethod } from "embedding-sdk-bundle/types";
import type { MetabaseEmbeddingSessionToken } from "embedding-sdk-bundle/types/refresh-token";
import type {
@@ -33,7 +34,7 @@ export type SdkIframeEmbedMessage =
| {
type: "metabase.embed.reportAuthenticationError";
data: {
- error: MetabaseError<string, unknown>;
+ error: MetabaseError<MetabaseErrorCode, unknown>;
};
}
| {