单点登录嵌入入门

单点登录 (SSO) 嵌入是一种向用户呈现安全的嵌入式 Looks、探索、信息中心或 LookML 信息中心的方式，用户无需拥有单独的 Looker 登录功能。相反，用户需要通过您自己的应用进行身份验证。

SSO 嵌入的工作原理是创建一个特殊的 Looker 网址，您将在 iframe 中使用该网址。该网址包含您想分享的信息、您系统中用户的 ID 以及您希望该用户拥有的权限。然后，您将使用 Looker 提供的密钥为该网址签名。

针对 SSO 嵌入的正确托管

在撰写本文时，某些浏览器（Internet Explorer 和 Safari）默认屏蔽阻止第三方 Cookie 的 Cookie 政策。由于 Looker 使用 Cookie 进行用户身份验证，因此无法在这些浏览器中尝试对嵌入式 iframe 进行身份验证（除非用户修改浏览器的 Cookie 隐私设置）。例如，如果您想在 https://mycompany.com 上嵌入信息，则需要确保 Looker 位于子网域（例如 https://analytics.mycompany.com）中。

如果 Looker 正在托管您的实例，请与 Looker 支持团队联系，以设置必要的 DNS 配置。点击 Contact Us（与我们联系），在 Looker 的帮助中心中打开支持请求。

如果您有客户托管的 Looker 实例，请确保将使用单点登录嵌入的应用与 Looker 实例位于同一基础网域上。

使用封闭式系统控制客户端可见性

在单点登录嵌入配置中，Looker 用户通常会向自己的客户显示数据，并且可以让来自不同公司或群组的客户互相了解。在这种情况下，为了保护客户的隐私信息，我们强烈建议您将 Looker 配置为封闭系统（也称为多租户安装）。在封闭的系统中，内容是相互孤立的，这使得不同群组中的用户无法相互了解。因此，我们建议您先启用封闭系统选项，然后再向任何外部用户授予对您的实例的访问权限。

有关详情，请参阅设计和配置访问权限级别系统和嵌入式分析的安全性最佳实践文档页面。

生成 Looker 的密钥

要验证单点登录嵌入请求是否合法且未被他人伪造，您首先需要生成“嵌入密钥”。为此，请执行以下操作：

  1. 转到 Looker 的管理部分中的嵌入页面。
  2. 从 Embed SSO Authentication（嵌入单点登录身份验证）下拉菜单中选择 Enabled（已启用），然后点击 Update（更新）。
  3. 点击重置 Secret 按钮以生成嵌入 Secret。务必将此 Secret 复制到安全位置，因为如果不重置，您将无法从 Looker 中检索到此 Secret。重置密钥会破坏使用旧密钥的所有嵌入。

有权访问该密钥的任何人都可以作为任何用户创建网址，以任何用户的身份访问 Looker 实例连接的任何模型。与管理嵌入式 Looker 实例的凭据一样，保护单点登录嵌入密钥，并在不使用单点登录时停用单点登录嵌入。

构建嵌入网址

构建正确的网址需要您编写代码，这样您就可以使用密钥对网址进行正确编码，并生成其他安全相关内容。您可以在我们的 SSO 示例 GitHub 代码库中找到多个示例脚本。下面几部分介绍了您将需要提供给这些脚本的信息。

收集必要的 Looker 信息

在构建网址时，您首先需要确定需要添加的所有信息。您需要有：

嵌入网址

检索要嵌入的样式、探索或信息中心的网址。然后移除域名，并将 /embed 添加到路径之前，如下所示：

项 普通网址格式 嵌入网址
Look https://instance_name.looker.com/
looks/4		 /embed/looks/4
探索 https://instance_name.looker.com/
explore/my_model/my_explore		 /embed/explore/my_model/my_explore
用户定义的信息中心 https://instance_name.looker.com/
dashboards-next/1		 /embed/dashboards-next/1
用户定义的旧版
信息中心		 https://instance_name.looker.com/
dashboards/1		 /embed/dashboards/1
LookML 信息中心 https://instance_name.looker.com/
dashboards-next/my_model::my_dashboard		 /embed/dashboards-next/my_model::my_dashboard
旧版 LookML
信息中心		 https://instance_name.looker.com/
dashboards/my_model::my_dashboard		 /embed/dashboards/my_model::my_dashboard

嵌入的内容始终反映的是内容的正式版。在开发模式期间所做的任何更改如果不会影响内容并且尚未部署到生产环境中，则不会显示在嵌入内容中。

权限

权限集定义了用户或群组可以执行的操作。权限可以通过以下两种方式之一应用：

  • 模型专用：此类权限仅适用于属于同一角色的模型集。
  • 实例级：此类权限适用于整个 Looker 实例。具有实例级权限的嵌入用户可以在整个 Looker 实例中执行特定功能，但无法根据角色模型中未包含的模型访问内容。

确定您希望用户拥有的权限。以下列表显示了单点登录嵌入的所有可用权限。SSO 嵌入不支持以下列表中的权限：

权限 取决于 类型 定义
access_data 无 型号专属 允许用户访问数据（查看 Looks、信息中心或探索所需的权限）
see_lookml_dashboards access_data 型号专属 允许用户查看 LookML 信息中心
see_looks access_data 型号专属 允许用户查看样式
see_user_dashboards see_looks 型号专属 允许用户查看用户定义的信息中心，以及从嵌入内容中浏览文件夹
explore see_looks 型号专属 允许用户查看“探索”页面
create_table_calculations explore 实例级 需要通过“探索”功能创建表格计算
save_content see_looks 实例级 允许用户更改和保存对外观和信息中心所做的更改
send_outgoing_webhook see_looks 型号专属 允许用户将信息中心和 Looks 安排到任意网络钩子
send_to_s3 see_looks 型号专属 允许用户将信息中心和 Looker 安排到 Amazon S3 存储桶
send_to_sftp see_looks 型号专属 允许用户将信息中心和 Looker 安排到 SFTP 服务器
schedule_look_emails see_looks 型号专属 通过此设置，用户可以安排将信息中心和 Looks 发送到自己的电子邮件地址（使用名为“email”的用户属性进行设置），或者发送到在电子邮件网域许可名单中设置的电子邮件地址。允许具有 create_alerts 权限的用户向电子邮件网域许可名单所设限制内的电子邮件地址发送提醒通知。
schedule_external_look_emails schedule_look_
emails		 型号专属 允许用户安排信息中心和 Look 以发送到任何电子邮件。允许拥有 create_alerts 权限的用户向任何电子邮件域名发送提醒通知。
send_to_
integration		 see_looks 型号专属 允许用户通过 Looker 操作中心向与 Looker 集成的第三方服务提供 Looker 内容。此权限与数据操作无关。
create_alerts see_looks 实例级 允许用户在信息中心图块上创建提醒，以便在达到或超过指定条件时收到通知。用户可以修改、复制和删除自己的提醒以及其他用户的公开提醒。如果用户的 Slack 工作区未连接到 Looker 实例，则将无法创建向 Slack 发送通知的提醒。
download_with_limit see_looks 实例级 允许用户下载设有限制的查询结果
download_without_limit see_looks 实例级 允许用户下载查询，但不应用任何限制
see_sql see_looks 型号专属 允许用户查看用于查询的 SQL 以及运行查询而导致的任何 SQL 错误
see_drill_overlay access_data 型号专属 允许用户无需转到整个“探索”页面即可进行深入分析。
embed_browse_spaces 无 实例级 启用内容浏览器，以便用户从嵌入内容中浏览文件夹。任何被授予嵌入权限的 embed_browse_spaces 用户都将有权访问个人嵌入文件夹以及贵组织的共享文件夹（如果有）。

建议建议拥有 save_content 权限的用户使用 embed_browse_spaces 权限，以便用户在选择保存内容的位置时能够浏览文件夹。

若要查看文件夹中的内容，用户还需要拥有 see_looks、see_user_dashboards 和 see_lookml_dashboards 权限。
embed_save_shared_space 无 实例级 允许拥有 save_content 权限的用户将内容保存到组织的共享文件夹（如有）。拥有 save_content 权限但没有 embed_save_shared_space 权限的用户将只能选择将内容保存到个人嵌入文件夹。

模型访问权限

确定用户有权访问哪些 LookML 模型。这只是模型名称列表。

用户属性

确定该用户应具有的用户属性（如果有）。您需要 Looker 中的用户属性的名称，以及用户应该具有的该属性的值。

群组

确定该用户应属于哪些群组（如果有）。您需要群组 ID 而不是群组名称。通过向 SSO 群组添加 SSO 嵌入用户，您可以管理该用户对 Looker 文件夹的访问权限。SSO 嵌入用户将有权访问与其 Looker 群组成员共享的任何文件夹。

您还可以使用 external_group_id 参数来创建位于常规 Looker 群组外部的群组。在这种情况下，拥有相同 external_group_id 的 SSO 嵌入用户将有权访问外部群组独有的名为“群组”的共享文件夹。

嵌入式角色

permissions 和 models 参数会为嵌入用户创建角色。此角色在 Looker 管理部分的用户页面中显示为“嵌入式角色”。如果嵌入网址中指定了 permissions、models 和 group_ids 参数，那么对于分配给 group_ids 参数中列出的群组的任何角色，嵌入的角色都是附加的。这与标准角色相同，因为 Looker 中的所有角色都是累加角色。

例如，假设您在 Looker 中有一个群组 ID 为 1 的群组，且该群组已对名为 model_one 的模型拥有 explore 权限，并且您创建了一个包含以下参数的嵌入网址：

  • group_ids = [1]
  • permissions = ["access_data","see_looks"]
  • models = ["model_two"]

在这种情况下，嵌入用户将继承在 model_one 上查看和探索数据的功能，而使用上述参数创建的嵌入角色也将获得在 model_two 中查看数据的权限。

创建嵌入网址

单点登录嵌入网址的格式如下：

https://Host/login/embed/沉浸式网址?参数&signature=签名

主机

主机是托管 Looker 实例的位置。例如 analytics.mycompany.com。请务必启用端口号（如果尚未启用端口转发），例如 analytics.mycompany.com:9999。

嵌入网址

嵌入网址之前已被确定。其格式如下所示：

  • /embed/looks/4
  • /embed/explore/my_model/my_explore
  • /embed/dashboards-next/1 或 /embed/dashboards/1
  • /embed/dashboards-next/my_model::my_dashboard 或 /embed/dashboards/my_model::my_dashboard

这确实意味着最终到达网址中会显示 /embed//embed/ 格式；这是正确的。

如果您使用的是嵌入式 JavaScript 事件，请务必在嵌入网址末尾添加一个 embed_domain（即使用 iframe 的网域），如下所示：

`/embed/looks/4`
⇨
`/embed/looks/4?embed_domain=https://mywebsite.com`

系统会在嵌入网址之后、所有参数前面添加 embed_domain。因此，如果您已有 nonce=62 等参数，添加 embed_domain 的方式将如下所示：

`/embed/looks/4?nonce=626`
⇨
`/embed/looks/4?embed_domain=https://mywebsite.com?nonce=626`

如果您使用的是嵌入 SDK，请务必添加 embed_domain 并在嵌入网址的末尾添加 sdk=2，如下所示：

`/embed/looks/4`
⇨
`/embed/looks/4?embed_domain=https://mywebsite.com&sdk=2`

通过 sdk=2 参数，Looker 可以确定 SDK 是否存在，并可以充分利用该 SDK 提供的其他功能。SDK 本身无法添加此参数，因为它是已签名的单点登录网址的一部分。

参数

以下网址参数用于指定 SSO 嵌入的必要信息：

参数 是否必须提供值？ 说明 数据类型 示例
nonce 是 您喜欢的任何随机字符串，但不能在一小时内重复，并且必须少于 255 个字符。

这可以防止攻击者重新提交合法用户的网址，以收集这些信息。		 JSON 字符串 "22b1ee700ef3dc2f500fb7"
time 是 当前时间（采用 UNIX 时间戳）。 整数 1407876784
session_length 是 用户应保持登录 Looker 的秒数，介于 0 到 2592000 秒（30 天）之间。 整数 86400
external_user_id 是 应用中嵌入 Looker 的用户的唯一标识符。Looker 使用该值来区分单点登录嵌入用户。

您可以创建此字符串，它可以是您喜欢的任何值。但是，对于一组指定的权限、用户属性和模型，此值必须是唯一的。例如，如果同一用户在两个不同的情境下将拥有不同的权限，则需要两个不同的外部用户 ID。

为安全起见，请确保对于不同的互动用户，不要在不同的嵌入会话中使用相同的external_user_id。		 JSON 字符串 "user-4"
permissions 是 用户应拥有的权限列表。

请参阅本页的权限部分，查看允许的权限列表。		 字符串数组 [
  "access_data",
  "see_looks"
]
models 是 用户应有权访问的模型的名称列表。 字符串数组 [
  "model_one",
  "model_two"
]
group_ids 否 用户应是的 Looker 群组列表（如果有）。请使用群组 ID 而不是群组名称。 整数数组 [4, 3]
external_group_id 否 如果需要，嵌入嵌入 Looker 的应用中用户所属的群组的唯一标识符。

有权保存内容并共享外部群组 ID 的用户将能够在名为“Group”的共享 Looker 文件夹中保存和编辑内容。		 JSON 字符串 "Accounting"
user_attributes 否 用户应具有的用户属性列表（如果有）。包含用户属性名称列表，后跟用户属性值。

如果您的 LookML 模型已本地化，您可以在嵌入网址中使用 locale 用户属性来指定嵌入语言。例如，包含参数 user_attributes { "locale" : "fr_FR" } 会导致嵌入加载法语语言。		 字符串哈希值 {
  "vendor_id" : "17",
  "company" : "xactness"
}
access_filters 是 在 Looker 3.10 中，此参数已被弃用，但仍在网址中是必需的。使用带有空占位符的 access_filters，例如 access_filters={}。 空白占位符 {}
first_name 否 用户的名字。如果留空，first_name 将保留上一个请求中的值；如果未设置任何名字，则为“Embed”。 JSON 字符串 "Alice"
last_name 否 用户的姓氏。如果留空，last_name 将保留上次请求中的值，如果未设置姓氏，则为“Embed”。 JSON 字符串 "Jones"
user_timezone 否 如果您启用了特定于用户的时区，请在嵌入式“查看”或信息中心的“时区”下拉菜单中设置“观看者时区”选项的值。此参数不会直接更改显示内容的时区，用户需要从下拉菜单中选择所需时区。

如需查看有效值，请参阅 SSO 嵌入时区参考文档页面。

聊天团队提示：如果您希望嵌入的内容默认采用观看者的时区，请使用下列方法之一：

  • 将参数 ?query_timezone=user_timezone 添加到嵌入网址。例如：

    /embed/dashboards/1?query_timezone=user_timezone
  • 保存嵌入式信息中心或将默认时区设为观看者时区后，默认情况下，嵌入用户和非嵌入式用户都会使用该时区。
    		•  JSON 字符串或 null "US/Pacific"

    或 -

    null
    force_logout_login 是 如果正常的 Looker 用户已经登录 Looker，并且他们查看了单点登录 (SSO) 项目，那么您可以选择：

    1) 他们应使用当前凭据查看该项目

    或

    2) 他们应该退出并重新登录单点登录凭据。    		 布尔值（true 或 false） true

    前面的所有参数都是必需的，但任何“‘必须’值”列中包含“否”的参数都可以使用空值。例如，您可以使用 group_ids [] 或 user_attributes {}。

    签名

    要生成签名，您需要按照以下步骤操作。

    1. 按以下顺序收集以下参数值：
      • 主机，后跟 login/embed/（例如 analytics.mycompany.com/login/embed/）
      • 嵌入网址
      • Nonce
      • 当前时间
      • 会话时长
      • 外部用户 ID
      • 权限
      • 模型
      • 群组 ID
      • 外部群组 ID
      • 用户属性
      • 访问过滤器（需要一个空的占位符）
    2. 将主机和嵌入网址以外的所有值的格式设置为 JSON
    3. 用换行符 (\n) 串联这些值
    4. HMAC 会使用 Looker 嵌入密钥对串联的字符串进行签名

    编码

    最后一步是对您的网址进行网址编码。

    在对网址进行编码之前，格式正确的嵌入网址使用所有可能的参数，如下所示：

    https://analytics.mycompany.com/login/embed//embed/dashboards-next/1?
nonce="22b1ee700ef3dc2f500fb7"&
time=1407876784&
session_length=86400&
external_user_id="user-4"&
permissions=["access_data","see_user_dashboards","see_looks"]&
models=["model_one","model_two"]&
group_ids=[4,3]&
external_group_id="Allegra K"&
user_attributes={"vendor_id":"17","company":"xactness"}&
access_filters={}&
first_name="Alice"&
last_name="Jones"&
user_timezone="US/Pacific"&
force_logout_login=true&
signature=123456789ABCDEFGHIJKL

    如前所述，/embed//embed/ 会显示在网址中。

    对网址进行编码后，网址将如下所示：

    https://analytics.mycompany.com/login/embed/%2embed%2Fdashboards-next%2F1?
nonce=%2222b1ee700ef3dc2f500fb7&%22&
time=1407876784&
session_length=86400&
external_user_id=%22user-4%22&
permissions=%5B%22access_data%22%2C%22see_user_dashboards%22%2C%22see_looks%22%5D&
models=%5B%22model_one%22%2C%22model_two%22%5D&
group_ids=%5B4%2C3%5D&
external_group_id=%22Allegra%20K%22&
user_attributes=%7B%22vendor_id%22%3A%2217%22%2C%22company%22%3A%22xactness%22%7D&
access_filters%7B%7D%26%0A
first_name=%22Alice%22&
last_name=%22Jones%22&
user_timezone=%22US%2FPacific%22&
force_logout_login=true&
signature=123456789ABCDEFGHIJKL

    使用 create_sso_embed_url API 端点

    Looker API 包含 create_sso_embed_url 端点，该端点接受一组 SSO 嵌入参数，这些参数包括要嵌入的内容的网址，并返回经过编码且经过签名的完整 SSO 网址。

    若要从 Web 服务器使用此 API 端点，该 Web 服务器必须能够以管理员权限向 Looker API 进行身份验证。嵌入网域许可名单中还必须列出该 Web 服务器网域。

    您还可以在 Looker 实例上使用 API Explorer 生成使用此端点的 SSO 网址。生成后，单点登录网址必须完全复制，且只能使用一次，否则会失败。交互式 API 文档也可用于生成 SSO 网址，并将其与手动创建的 SSO 网址进行比较，以用于问题排查。

    如需详细了解 Looker API，请参阅 Looker API 概览页面。

    测试嵌入网址

    要测试您的最终到达网址，请将其粘贴到 Looker 的管理部分的嵌入页面上的嵌入 URI 验证工具中。虽然使用以下选项无法判断您预想的数据和权限是否设置正确，但它可以验证您的身份验证是否正常运行。