Skip to content

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

Update in-app JWT onboarding to use snippets instead of iframes (#70475)

Phoomparin Mano811e4466b2c2
diff --git a/e2e/test/scenarios/embedding/embedding-hub/embedding-hub.cy.spec.ts b/e2e/test/scenarios/embedding/embedding-hub/embedding-hub.cy.spec.ts
index e65a62fc625..ebba6aeb3ac 100644
--- a/e2e/test/scenarios/embedding/embedding-hub/embedding-hub.cy.spec.ts
+++ b/e2e/test/scenarios/embedding/embedding-hub/embedding-hub.cy.spec.ts
@@ -1723,7 +1723,18 @@ describe("scenarios - embedding hub", () => {
.findByRole("listitem", { name: "Set up JWT authentication" })
.should("have.attr", "data-completed", "true");
- H.main().findByRole("button", { name: "Next" }).click();
+ cy.log("valid signing key should be shown");
+ H.main().within(() => {
+ cy.findByText(
+ /This example code for Node.js sets up an endpoint using Express/,
+ ).should("be.visible");
+
+ cy.log("express.js code snippet should be shown inline");
+ cy.contains("METABASE_JWT_SHARED_SECRET").should("exist");
+ cy.contains("METABASE_INSTANCE_URL").should("exist");
+
+ cy.findByRole("button", { name: "Next" }).scrollIntoView().click();
+ });
cy.log("step 2 should be complete");
H.main()
diff --git a/eslint.config.mjs b/eslint.config.mjs
index 40baf6075e1..fe5cc1733ed 100644
--- a/eslint.config.mjs
+++ b/eslint.config.mjs
@@ -118,7 +118,7 @@ const configs = [
},
settings: {
"import-x/internal-regex":
- "^metabase($|/)|^metabase-lib($|/)|^metabase-types($|/)|^metabase-enterprise($|/)|^embedding-sdk-bundle($|/)|^embedding-sdk-shared($|/)|^embedding-sdk-package($|/)|^e2e($|/)|^__support__($|/)|^assets/|^cljs/|^ee-plugins($|/)|^sdk-ee-plugins($|/)|^build-configs/",
+ "^metabase($|/)|^metabase-lib($|/)|^metabase-types($|/)|^metabase-enterprise($|/)|^embedding-sdk-bundle($|/)|^embedding-sdk-shared($|/)|^embedding-sdk-package($|/)|^e2e($|/)|^__support__($|/)|^assets/|^cljs/|^ee-plugins($|/)|^sdk-ee-plugins($|/)|^build-configs/|^docs/",
"import-x/resolver": {
node: true,
webpack: {
diff --git a/frontend/src/metabase/embedding/embedding-hub/components/SetupSsoPage/AddEndpointStep.tsx b/frontend/src/metabase/embedding/embedding-hub/components/SetupSsoPage/AddEndpointStep.tsx
index fd8ff5d816d..c94c7313aba 100644
--- a/frontend/src/metabase/embedding/embedding-hub/components/SetupSsoPage/AddEndpointStep.tsx
+++ b/frontend/src/metabase/embedding/embedding-hub/components/SetupSsoPage/AddEndpointStep.tsx
@@ -1,30 +1,67 @@
-/* eslint-disable metabase/no-unconditional-metabase-links-render */
+/* eslint-disable metabase/no-unconditional-metabase-links-render, metabase/no-literal-metabase-strings, i18next/no-literal-string -- admin-only page */
-import { jt, t } from "ttag";
+import { c, t } from "ttag";
+import expressSnippet from "docs/embedding/sdk/snippets/authentication/express-server-interactive-and-sdk";
+import { CodeEditor } from "metabase/common/components/CodeEditor";
+import { CopyButton } from "metabase/common/components/CopyButton";
import { useDocsUrl } from "metabase/common/hooks";
-import { Anchor, Button, Group, Stack, Text } from "metabase/ui";
+import { Anchor, Box, Button, Code, Group, Stack, Text } from "metabase/ui";
import S from "./SetupSsoPage.module.css";
export const AddEndpointStep = ({ onDone }: { onDone: () => void }) => {
- // TODO(EMB-1337): replace this with standalone JWT backend docs page.
const { url: jwtDocsUrl } = useDocsUrl("embedding/authentication");
- const jwtDocsIframeUrl = `${jwtDocsUrl}?hide_nav=true&no_gdpr=true`;
-
return (
<Stack gap="lg">
- <iframe
- src={jwtDocsIframeUrl}
- title={t`JWT Authentication Documentation`}
- className={S.docsIframe}
- />
+ <Stack gap="sm">
+ <Text>{t`You'll need to add a library to your backend to sign your JSON Web Tokens.`}</Text>
+ <Text>{t`For Node.js, we recommend jsonwebtoken:`}</Text>
+
+ <Code className={S.codeSnippet} p="md" block>
+ npm install jsonwebtoken --save
+ </Code>
+
+ <Text>
+ {c("{0} is '/sso/metabase'")
+ .jt`Next, set up an endpoint on your backend (e.g., ${(
+ <Code key="endpoint">/sso/metabase</Code>
+ )}) that uses your Metabase JWT shared secret to generate a JWT for the authenticated user. `}
+ <strong>
+ {c("{0} is 'jwt'")
+ .jt`This endpoint must return a JSON object with a ${(
+ <Code key="jwt-prop">jwt</Code>
+ )} property containing the signed JWT.`}
+ </strong>
+ {c('{0} is \'{ "jwt": "your-signed-jwt" }\'').jt` For example: ${(
+ <Code key="example">{'{ "jwt": "your-signed-jwt" }'}</Code>
+ )}.`}
+ </Text>
+ <Text>{t`This example code for Node.js sets up an endpoint using Express:`}</Text>
+ </Stack>
+
+ <Box pos="relative">
+ <CopyButton
+ className={S.codeSnippetCopyButton}
+ value={expressSnippet}
+ />
+
+ <CodeEditor
+ className={S.codeSnippet}
+ language="typescript"
+ value={expressSnippet}
+ readOnly
+ lineNumbers={false}
+ />
+ </Box>
<Text size="sm" c="text-secondary">
- {jt`You can view more examples in the ${(
+ {c("{0} is a link labeled 'docs'")
+ .jt`You can view more examples in the ${(
<Anchor key="docs-link" href={jwtDocsUrl} target="_blank">
- {t`docs`}
+ {c("In the sentence 'You can view more examples in the docs'")
+ .t`docs`}
</Anchor>
)}.`}
</Text>
diff --git a/frontend/src/metabase/embedding/embedding-hub/components/SetupSsoPage/SetupSsoPage.module.css b/frontend/src/metabase/embedding/embedding-hub/components/SetupSsoPage/SetupSsoPage.module.css
index 38a101cd387..d3d928ca340 100644
--- a/frontend/src/metabase/embedding/embedding-hub/components/SetupSsoPage/SetupSsoPage.module.css
+++ b/frontend/src/metabase/embedding/embedding-hub/components/SetupSsoPage/SetupSsoPage.module.css
@@ -12,3 +12,22 @@
border: 1px solid var(--mb-color-border);
border-radius: 0.5rem;
}
+
+.codeSnippetCopyButton {
+ position: absolute;
+ top: var(--mantine-spacing-md);
+ right: var(--mantine-spacing-md);
+ z-index: 1;
+ cursor: pointer;
+}
+
+.codeSnippet {
+ background: var(--mb-color-background-secondary);
+ border-radius: 8px;
+ padding: var(--mantine-spacing-sm) var(--mantine-spacing-md);
+}
+
+/* remove CodeMirror line padding */
+.codeSnippet :global(.cm-line) {
+ padding: 0;
+}
diff --git a/frontend/src/types/docs-snippets.d.ts b/frontend/src/types/docs-snippets.d.ts
new file mode 100644
index 00000000000..61224582407
--- /dev/null
+++ b/frontend/src/types/docs-snippets.d.ts
@@ -0,0 +1,5 @@
+declare module "docs/embedding/sdk/snippets/*" {
+ const content: string;
+ // eslint-disable-next-line import/no-default-export
+ export default content;
+}
diff --git a/jest.config.js b/jest.config.js
index 8cc693cc3c4..c340a8ffd45 100644
--- a/jest.config.js
+++ b/jest.config.js
@@ -36,6 +36,12 @@ const baseConfig = {
* As we use SDK components in new iframe embedding, we need to import them here.
**/
"sdk-specific-imports": "<rootDir>/frontend/src/metabase/lib/noop.ts",
+ /**
+ * Docs snippets are loaded as raw text (asset/source) in rspack.
+ * In Jest, mock them as plain strings.
+ */
+ "^docs/embedding/sdk/snippets/(.*)$":
+ "<rootDir>/frontend/test/__mocks__/fileMock.js",
"docs/(.*)$": "<rootDir>/docs/$1",
},
transformIgnorePatterns: [
diff --git a/rspack.main.config.js b/rspack.main.config.js
index 145ee204b79..de52c4958b1 100644
--- a/rspack.main.config.js
+++ b/rspack.main.config.js
@@ -1,6 +1,6 @@
// @ts-check
/* eslint-env node */
-/* eslint-disable import/no-commonjs */
+
const fs = require("fs");
const rspack = require("@rspack/core");
@@ -29,6 +29,10 @@ const { SVGO_CONFIG } = require("./frontend/build/shared/rspack/svgo-config");
const SRC_PATH = __dirname + "/frontend/src/metabase";
const BUILD_PATH = __dirname + "/resources/frontend_client";
+// For sharing the embedding snippets in the docs with the embedding
+// onboarding flow in the app to keep the snippets always in sync.
+const SDK_DOCS_SNIPPETS_PATH = __dirname + "/docs/embedding/sdk/snippets";
+
const PORT = process.env.MB_FRONTEND_DEV_PORT || 8080;
const isDevMode = IS_DEV_MODE;
const shouldEnableHotRefresh = WEBPACK_BUNDLE === "hot";
@@ -132,9 +136,21 @@ const config = {
exclude: /node_modules|cljs/,
use: [BABEL_LOADER],
},
+ {
+ // Embedding onboarding flow requires sharing snippets from
+ // docs, so we treat TypeScript files inside docs/ as raw text
+ test: /\.tsx?$/,
+ include: [SDK_DOCS_SNIPPETS_PATH],
+ type: "asset/source",
+ },
{
test: /\.(tsx?|jsx?)$/,
- exclude: /node_modules|cljs|css\/core\/fonts\.styled\.ts/,
+ exclude: [
+ /node_modules/,
+ /cljs/,
+ /css\/core\/fonts\.styled\.ts/,
+ SDK_DOCS_SNIPPETS_PATH,
+ ],
use: [SWC_LOADER],
type: "javascript/auto",
},
@@ -334,6 +350,7 @@ if (shouldEnableHotRefresh) {
config.plugins.unshift(
new ReactRefreshPlugin({
overlay: false,
+ exclude: [SDK_DOCS_SNIPPETS_PATH],
}),
);
}
diff --git a/tsconfig.json b/tsconfig.json
index ca27e45ddef..ff4abbd2c3a 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -13,7 +13,6 @@
],
"build-configs/*": ["./frontend/build/*"],
"cljs/*": ["./target/cljs_dev/*"],
- "docs/*": ["./docs/*"],
"sdk-ee-plugins": ["./frontend/src/metabase/plugins/noop"]
},
"plugins": [