交互式嵌入快速入门

您将在您的应用程序中嵌入完整的Metabase应用程序。一旦登录，人们可以在您的Web应用程序中查看Metabase仪表板，并能够使用完整的Metabase应用程序来探索他们的数据，以及只有他们的数据。

先决条件

• 您有一个可以嵌入Metabase的应用程序。
• 您有Metabase的Pro或企业订阅。如果您不确定从哪里开始，请注册Pro On-Prem的免费试用。如果您已安装Docker Desktop，只需搜索“metabase-enterprise”即可找到Docker镜像并运行。或者，您可以按照这些说明进行操作。

本指南中展示的代码可以在我们的示例存储库中找到。

在Metabase中设置SSO和交互式嵌入

在Metabase中创建仪表板

首先，您需要创建可以嵌入的内容。在左侧导航中，转到 浏览 > 数据库 > 示例数据库。将鼠标悬停在 发票 表上，然后单击闪电图标进行表格透视。Metabase 将创建一系列问题，您可以将其保存为仪表板。单击按钮将 保存此内容 为仪表板。Metabase 将此仪表板保存在名为“自动生成仪表板”的集合中。

访问“自动生成仪表板”集合中的该仪表板，并记录其 URL。如果这是您创建的第一个仪表板，它可能是 /dashboard/1 后跟描述，例如 /dashboard/1-a-look-at-your-invoices-table。您需要将此相对 URL 放入您的应用程序中，因为当登录用户访问您应用程序中的分析部分时，仪表板将是他们看到的第一个页面。只需包含 ID 即可，其余的 URL 可以省略，例如 /dashboard/1。

启用交互式嵌入

在 Metabase 中，单击右上角的 齿轮 图标，转到 管理设置 > 设置 > 嵌入，然后单击 启用 按钮。

单击 交互式嵌入 卡片。在 授权源 下，添加您希望嵌入 Metabase 的网站或 Web 应用的 URL。如果您在本地运行应用程序，可以添加 localhost 并指定端口号，例如 https://127.0.0.1:8080。

在您的 Metabase 中设置 JWT 中的 SSO

SameSite 配置

如果您在另一个域名中嵌入 Metabase，您可能需要 将会话 Cookie 的 SameSite 值设置为 none

启用 JWT 验证

仍然在管理面板的 设置 部分中，单击 身份验证。

在标有 JWT 的卡片上，单击 设置 按钮（您可能需要向下滚动才能查看 JWT 卡片）。

设置 JWT 身份提供者 URI

在您的应用程序中，您将在 /sso/metabase 创建 SSO 的路由。在 JWT 身份提供者 URI 字段中，输入您的 SSO 路由的 URL。例如，我们的示例应用程序在端口 8080 上运行，因此在这种情况下，JWT 身份提供者 URI 可以是 https://127.0.0.1:8080/sso/metabase。

生成 JWT 签名密钥

单击 生成密钥 按钮，生成签名密钥。请保密此密钥。您将在服务器上使用它。如果您生成另一个密钥，则将覆盖现有密钥，因此您还需要在应用程序中更新密钥。

复制此密钥，因为在下一节中需要它。

保存并启用 JWT 验证

我们将在稍后设置组同步，但在此期间，请确保单击 保存并启用 按钮，以激活 JWT 验证。

在您的应用程序服务器中设置 JWT 中的 SSO

将签名密钥和 Metabase 站点 URL 添加到您的应用程序中

在这里，您需要为 SSO 正常工作输入一些值。

您希望在自己的应用程序中声明两个常量

• METABASE_JWT_SHARED_SECRET，在此处粘贴您从 Metabase 获取的 JWT 签名密钥。
• METABASE_SITE_URL，指向您的 Metabase 根路径。

const METABASE_JWT_SHARED_SECRET = "YOURSIGNINGKEY";
const METABASE_SITE_URL = "https://your-domain.metabaseapp.com";

建议将签名密钥设置为环境变量，以避免意外将密钥提交到您的应用程序仓库。

将 JWT 库添加到您的应用程序服务器

将 JWT 库添加到您的应用程序中。例如，如果您使用的是 Node 后端和 JavaScript，我们建议使用 jsonwebtoken。

在终端中

npm install jsonwebtoken --save

在您的应用程序中引入库

const jwt = require("jsonwebtoken");

限制对某些路由的访问

假设您的应用程序已经有了确保某些路由在登录后才能访问的方法。我们的示例使用了一个名为 restrict 的简单辅助函数来保护这些路由

function restrict(req, res, next) {
  if (req.session.user) {
    next();
  } else {
    req.session.returnTo = req.originalUrl;
    req.session.error = "Access denied!";
    res.redirect("/login");
  }
}

添加一个签名用户的功能

我们需要编写一个函数来使用 JWT 库签名用户 JWT。

const signUserToken = user =>
  jwt.sign(
    {
      email: user.email,
      first_name: user.firstName,
      last_name: user.lastName,
      exp: Math.round(Date.now() / 1000) + 60 * 10, // 10 minute expiration
    },
    METABASE_JWT_SHARED_SECRET,
  );

添加一个 sso/metabase 路由

您需要添加一个路由，以便通过 JWT 使用 SSO 登录到您的 Metabase。如果此人尚未登录到您的应用程序，您的应用程序应通过您的登录流程将其重定向。在下面的代码中，此检查和重定向由我们之前引入的 restrict 函数处理。

app.get("/sso/metabase", restrict, (req, res) => {
  const ssoUrl = new URL("/auth/sso", METABASE_SITE_URL);
  ssoUrl.searchParams.set("jwt", signUserToken(req.session.user));
  ssoUrl.searchParams.set("return_to", req.query.return_to ?? "/");

  res.redirect(ssoUrl);
});

如果此人以前从未登录过 Metabase，Metabase 将为其创建一个账户。

检查点：使用 SSO 登录到您的 Metabase

请确保您已从 Metabase 登出。在 Metabase 登录页面，单击“使用 SSO 登录”。您应被重定向到您的应用程序。

登录您的应用程序。您的应用程序应将您重定向到 Metabase 欢迎页面。如果此人还没有 Metabase 账户，Metabase 应为其创建一个账户。

将 Metabase 嵌入您的应用程序

现在，将 Metabase 嵌入您的应用程序。您需要设置一个用于提供嵌入式分析的路径。让我们称它为 /analytics。请注意，我们正在使用上面定义的 restrict 辅助函数（因为此页面应在人们登录到您的应用程序后才能查看）。

在此路由中，我们需要渲染一个 iframe，该 iframe 将加载您的 Metabase。iframe 的 src 属性应指向应用程序 SSO 端点的相对路径。一旦此人登录到您的应用程序（因此也登录到您的 Metabase），我们添加查询字符串参数 return_to，以便 iframe 显示请求的仪表板。

METABASE_DASHBOARD_PATH 应指向本指南开头创建的仪表板的相对路径。

app.get("/analytics", restrict, function (req, res) {
  const METABASE_DASHBOARD_PATH = "/dashboard/1";
  var iframeUrl = `/sso/metabase?return_to=${METABASE_DASHBOARD_PATH}`;
  res.send(
    `<iframe src="${iframeUrl}" frameborder="0" width="1280" height="600" allowtransparency></iframe>`,
  );
});

METABASE_DASHBOARD_PATH 只是人们在登录时看到的第一件事，但您可以将该路径设置为任何 Metabase URL。由于您正在嵌入完整的 Metabase，人们将能够深入数据并查看其他问题、仪表板和集合。

检查点：在您的应用程序中查看 Metabase 仪表板

使用您应用程序的人们现在应该能够访问 /analytics 并查看您嵌入的 Metabase 仪表板。

如何测试：登录到您的应用程序并访问 /analytics 路由。您应该看到 Metabase 仪表板。

如果您使用的是Safari浏览器，并且您从不同的域提供服务Metabase和您的应用程序，您可能需要进入Safari的设置并关闭阻止跨站跟踪。

在Metabase中设置一个组

既然您已经设置了SSO和交互式嵌入，现在是时候设置组以便您可以应用权限到您的嵌入式Metabase实体（问题、仪表板、集合等）。

将groups键添加到您的令牌

回想一下用于创建JWT的signUserToken函数。将一个groups键添加到已签名的令牌，该键映射到一个数组。Metabase将查看该数组中的值，以查看是否其中任何一个值映射到Metabase中的一个组（我们将在稍后介绍如何映射组）。

const signUserToken = user =>
  jwt.sign(
    {
      email: user.email,
      first_name: user.firstName,
      last_name: user.lastName,
      groups: ["Customer-Acme"],
      exp: Math.round(Date.now() / 1000) + 60 * 10, // 10 minute expiration
    },
    METABASE_JWT_SHARED_SECRET,
  );

在Metabase中创建一个组

在Metabase中，点击齿轮图标，转到管理设置 > 人员 > 组。点击创建组按钮。添加与您的应用程序中的组相对应的组。如果您使用的是示例应用程序，请添加名为Customer Acme的组。

在Metabase和您的应用程序之间同步组

您将映射到groups键中的这个字符串，以便当人员通过SSO登录时，Metabase自动将他们分配到适当的Metabase组。

在Metabase的管理部分，转到设置 > 身份验证。滚动到JWT卡并点击编辑。

在组架构部分，打开同步组成员资格。对于您想要同步的每个组，添加一个组映射。当您点击新映射时，输入“Customer-Acme”，这是您在JWT有效负载中的groups数组中包含的字符串。然后，您可以将其与之前创建的Metabase组“Customer Acme”关联。

务必保存更改。

检查点：验证Metabase在人员登录时分配他们到组

首先，从Metabase登出并使用SSO登录。

然后登出，以管理员身份登录到您的Metabase并转到管理设置 > 人员部分，以验证Metabase是否已将人员添加到适当的组。

注意：只有Metabase管理员和组管理员知道组。基本用户没有组的概念，也无法知道他们属于哪些组。

设置权限

现在，为了将权限应用于该组，以便人们只能看到特定于他们账户的数据。

重置所有用户组的权限

Metabase附带两个初始组：“管理员”和“所有用户”。默认情况下，Metabase授予“所有用户”组访问连接数据源的权利。由于Metabase授予人们的权限是他们最宽容的组的权限，因此您在将他们添加到具有有限或无访问权限的数据源和集合的组之前，想限制“所有用户”组可以看到的内容。

要重置所有用户组的权限，请单击 齿轮 图标，然后转到 管理员设置 > 权限。在 数据 选项卡下，转到 组 并选择 所有用户。在 样本数据库 的 查看数据 列表中，选择“阻止”。单击 保存更改，将弹出一个模态窗口总结您所做的更改。单击 是。

允许访问自动生成的仪表板集合

仍然在 权限 选项卡中，单击 集合 子选项卡，然后单击 自动生成的仪表板 集合，将 所有用户 组的 集合访问 权限设置为 查看。

单击 保存更改，然后 是。

将用户属性添加到令牌中

您可以在 JSON Web 令牌中包含用户属性。Metabase 将自动从 JWT 负载中获取任何键并将其存储为用户属性。在许多用例中，您可以使用这些用户属性在表中设置行级权限，这样人们就只能看到与他们账户相关的结果。

如果您正在使用我们的示例应用程序，请编辑用于创建 JWT 的 signUserToken 函数，通过添加键 account_id 并将其值设置为 28 来实现这一点。

const signUserToken = user =>
  jwt.sign(
    {
      email: user.email,
      first_name: user.firstName,
      last_name: user.lastName,
      // hard-coded account ID added to this object
      // just to test sandboxing with Metabase's Sample Database: Invoices table
      account_id: 28,
      groups: ["Customer-Acme"],
      exp: Math.round(Date.now() / 1000) + 60 * 10, // 10 minute expiration
    },
    METABASE_JWT_SHARED_SECRET,
  );

该用户 ID 将对应于样本数据库发票表中的 Account ID 列。我们将使用此 account_id 用户属性来隔离发票表，这样人们就只能看到包含他们账户 ID 的表中的行。

注意，为了在 Metabase 中持久化用户属性，您需要登录。以非管理员身份登录您的应用程序，并访问您的嵌入式 Metabase 页面。

使用数据沙盒设置行级权限

在 Metabase 中，转到 管理员设置 > 权限。在左侧的 数据 选项卡下，单击一个组。对于“样本数据库”，将其 数据访问 列表更改为 粒度。

Metabase 将显示数据库中的表列表。接下来，将“发票”表的数据访问更改为 沙盒。

接下来，Metabase 将提示您通过模态窗口将表中的一个列与用户属性相关联。

保留 通过表中的列筛选 选项，并将发票表中的“Account ID”列与用户属性 account_id 相关联。（请注意，如果用户之前通过 SSO 登录，Metabase 才会显示用户属性。）

单击 保存 以确认您的选择。然后单击右上角的 保存更改 按钮。

Metabase 将询问您是否确定要执行此操作。您确定。

检查点：查看沙盒仪表板

请确保您已注销之前的会话。

登录您的应用程序，导航到 /analytics。仪表板现在将呈现不同的信息，因为只有该人员可以看到数据的一个子集。在左侧导航的底部单击 浏览数据。查看您的沙盒 发票 表，您应该只看到与人员账户相关的行。

隐藏元数据元素

您可以决定显示或隐藏各种元数据元素，例如是否显示导航栏、搜索或新建按钮等。

例如，要隐藏您嵌入的元数据中的标志和顶部导航栏，请在SSO重定向中包含的return_to URL后附加查询字符串参数?logo=false&top_nav=false。

在您的/sso/metabase路径的处理程序中，添加查询参数

ssoUrl.searchParams.set(
  "return_to",
  `${req.query.return_to ?? "/"}?logo=false&top_nav=false`,
);

检查点：验证隐藏的UI元素

注销并重新登录您的应用程序，然后导航到/analytics。您的嵌入式元数据不应包含标志或顶部导航。

下一步

您可以在您的应用程序中自定义元数据的显示方式：字体、颜色和标志。