单点登录 (SSO) 嵌入

如果您想使用这些功能，请与您的 Looker 客户经理联系。

单点登录 (SSO) 嵌入是一种向用户提供嵌入式嵌入式 Looks、可视化图表、探索、信息中心或 LookML 信息中心的方式，而无需用户使用单独的 Looker 登录信息。相反，用户将通过您自己的应用进行身份验证。

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

如需查看公开嵌入，请参阅公开共享、导入和嵌入 Looks 文档页面的 iframe 标记公开嵌入部分。

SSO 嵌入的正确托管

有些浏览器（例如 Safari 或安装了广告或跟踪拦截扩展程序的浏览器）默认采用会屏蔽第三方 Cookie 的 Cookie 政策。由于 Looker 使用 Cookie 来进行用户身份验证，因此在这些浏览器中无法尝试对各个网域进行嵌入式 iframe 身份验证（除非用户修改了浏览器的 Cookie 隐私设置）。例如，如果您要将信息嵌入 https://mycompany.com 中，则需要确保 Looker 共享同一个网域，例如 https://analytics.mycompany.com。

如果 Looker 托管了您的实例，请与 Looker 支持团队联系，设置必要的 DNS 配置以启用自定义网域。这将允许 Looker 与嵌入式应用共享同一个网域，并利用第一方 Cookie（默认接受所有浏览器）。只需点击与我们联系，即可在 Looker 的帮助中心打开支持请求。

如果您有客户托管的 Looker 实例，请确保将使用 SSO 嵌入的应用与您的 Looker 实例使用同一网域。

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

在 SSO 嵌入配置中，通常会出现 Looker 用户向其客户显示数据，同时让不同公司或群组的客户彼此不认识的情况。在此场景中，为了保护客户的隐私信息，我们强烈建议您将 Looker 配置为封闭系统（也称为多租户安装）。在封闭系统中，内容会相互孤立，以防止不同群组的彼此了解。因此，我们建议您启用封闭系统选项，然后再向任何外部用户授予对您的实例的访问权限。

如需了解详情，请参阅设计和配置访问权限级别系统和嵌入式分析的安全最佳做法文档页面。

正在生成 Looker 的密钥

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

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

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

构建嵌入网址

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

收集必要的 Looker 信息

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

嵌入网址

检索要嵌入的 Look（探索）、Discover（探索）、Query Visualization 或信息中心的网址。然后移除域名，并在路径前放置 /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/
explore/my_model/my_explore?qid=1234567890abcdefghij12

“探索”网址中的 qid= 参数后面的 22 个字母数字字符构成了 Query.client_id。Query.client_id 值是一个代表查询和可视化设置的唯一字符串。

如需嵌入查询的可视化图表，请检索查询可视化图表的 Query.client_id 值，并将 Query.client_id 复制到您的嵌入网址。

您可以使用 Looker 探索界面构建具有受支持的可视化图表的查询，并从 qid= 参数复制 Query.client_id 值，例如，您可以使用 Get Query 方法检索 Query.client_id。		 /embed/query-visualization/Query.client_id
用户定义的信息中心 https://instance_name.looker.com/
dashboards/1		 /embed/dashboards/1
用户定义的旧版
信息中心		 https://instance_name.looker.com/
dashboards-legacy/1		 /embed/dashboards-legacy/1
LookML 信息中心 https://instance_name.looker.com/
dashboards/my_model::my_dashboard		 /embed/dashboards/my_model::my_dashboard
旧版 LookML
信息中心		 https://instance_name.looker.com/
dashboards-legacy/my_model::my_dashboard		 /embed/dashboards-legacy/my_model::my_dashboard

嵌入的内容始终反映内容的正式版本。在开发模式下所做的更改会对相关内容产生影响，但这些更改尚未部署到生产环境中。

权限

权限集定义了用户或群组可以执行哪些操作。权限可以通过以下两种方法应用：

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

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

权限 取决于 类型 定义
access_data 无 特定型号 允许用户访问数据（查看“景观”、“信息中心”或“探索”时需要）
see_lookml_dashboards access_data 特定型号 允许用户查看 LookML 信息中心
see_looks access_data 特定型号 允许用户查看样式
see_user_dashboards see_looks 特定型号 允许用户查看用户定义的信息中心以及通过嵌入内容浏览文件夹
explore see_looks 特定型号 允许用户查看“探索”页面
create_table_calculations explore 实例范围 需要在“探索”中创建表格计算
create_custom_fields explore 实例范围 已添加 22.4 需要在“探索”部分创建自定义字段
can_create_forecast explore 实例范围 添加 22.12 允许用户在可视化图表中创建或修改预测。
save_content see_looks 实例范围 允许用户更改和更改外观和信息中心
send_outgoing_webhook see_looks 特定型号 允许用户安排信息中心和查找任意网络钩子
send_to_s3 see_looks 特定型号 允许用户安排信息中心和查看 Amazon S3 存储桶
send_to_sftp see_looks 特定型号 允许用户安排信息中心和查找 SFTP 服务器
schedule_look_emails see_looks 特定型号 允许用户将信息中心和外观信息发送到自己的电子邮件地址（使用名为“email”的用户属性设置），或者发送到电子邮件域名许可名单所设限制内的电子邮件地址。允许拥有 create_alerts 权限的用户向电子邮件网域许可名单所设限制内的电子邮件地址发送提醒通知。
schedule_external_look_emails schedule_look_
emails		 特定型号 允许用户将信息中心和外观设置为发送到任何电子邮件。允许拥有 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 错误
clear_cache_refresh access_data 特定型号 已添加 21.14 用户可以清除缓存和刷新嵌入式信息中心、旧版信息中心、信息中心图块、外观和探索。
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 无 实例范围 ADDED 21.4 让同样拥有 save_content 权限的用户从保存对话框中导航到组织的共享文件夹（如果有）。拥有 save_content 权限但没有 embed_save_shared_space 权限的用户只能选择将内容保存到个人嵌入文件夹中。

embed_save_shared_space 权限不会覆盖内容访问权限。例如，要让用户能够将内容保存到共享文件夹，他们仍然需要对共享文件夹拥有管理访问权限、修改权限。此外，如果没有 embed_save_shared_space 权限，拥有 save_content 权限且对共享文件夹拥有管理访问权限、修改权限的用户可以通过某种方式导航到共享文件夹（例如，使用嵌入信息中心内的从此处探索选项），因而不会阻止用户将内容保存到该共享文件夹。

模型访问权限

确定用户应该有权访问的 LookML 模型。这只是模型名称列表。

用户属性

确定用户应具备哪些用户属性（如果有）。您需要来自 Looker 的用户属性以及用户应该拥有的属性值。

网上论坛

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

您还可以使用 external_group_id 参数在常规 Looker 群组之外创建一个群组。在这种情况下，具有相同 external_group_id 的 SSO 嵌入用户将有权访问名为“Group”的共享文件夹，该文件夹对外部群组具有唯一性。

嵌入式角色

permissions 和 models 参数会为嵌入用户创建角色。此角色在 Lookers 管理部分的用户页面中显示为“嵌入式角色”。如果嵌入网址中指定了 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/EMBED 网址？参数&signature=签名

主机

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

嵌入网址

嵌入网址之前已确定。其格式为：

  • /embed/looks/4
  • /embed/explore/my_model/my_explore
  • /embed/query-visualization/Query.client_id
  • /embed/dashboards/1 或 /embed/dashboards-legacy/1
  • /embed/dashboards/my_model::my_dashboard 或 /embed/dashboards-legacy/my_model::my_dashboard

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

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

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

embed_domain 是在嵌入网址之后以及所有参数之前添加的。因此，如果您有现有的参数（例如 nonce=626），则添加 embed_domain 的方式如下所示：

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

如果您使用的是 Embed 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 网址的一部分。

参数

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

参数 是否需要值？ 说明 数据类型 示例
nonce 是 您可以随意选择字符串，但不能在一小时内重复，并且长度必须少于 255 个字符。

这样可以防止攻击者重新提交合法用户的网址，以收集用户不应该拥有的信息。		 JSON 字符串 "22b1ee700ef3dc2f500fb7"
time 是 当前时间（采用 UNIX 时间戳）。 整数 1407876784
session_length 是 用户应保持登录到 Looker 的秒数，介于 0 到 2592000 秒（30 天）之间。 整数 86400
external_user_id 是 应用中嵌入 Looker 的每个用户的标识符。Looker 使用 external_user_id 区分 SSO 嵌入用户，因此必须为每个用户分配一个唯一 ID。

您可以使用自己喜欢的任何字符串为用户创建 external_user_id，只要它与该用户不同即可。每个 ID 都与一组权限、用户属性和模型相关联。一个浏览器一次只能支持一个 external_user_id（即用户会话）。在会话期间，不得更改用户的权限或用户属性。

为安全起见，请确保不要为不同互动用户的不同嵌入会话使用相同的 external_user_id，并确保对拥有不同权限、用户属性值或模型访问权限的单个用户使用相同的 external_user_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 的用户能够在名为“群组”的共享 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) 他们应该退出，并使用 SSO 凭据重新登录。    		 布尔值（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/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%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 网址。

    要通过网络服务器使用此 API 端点，网络服务器必须能够以管理员权限向 Looker API 进行身份验证。此网络服务器网域也必须列在嵌入网域许可名单中。

    您还可以使用 API Explorer 生成使用此端点的 SSO 网址。您可以从 Looker Marketplace 将 Looker 安装到 Looker 实例上，也可以在 Looker' 开发者门户中查看公开版本。生成后，单点登录网址必须完全复制且只能使用一次，否则将会失败。此外，API Explorer 也可用于生成 SSO 网址并将其与手动创建的 SSO 网址进行比较，以用于问题排查。

    如需详细了解 Looker API，请参阅 Looker API 使用入门文档页面。

    测试嵌入网址

    如需测试最终到达网址，请将其粘贴到 Looker 的管理部分的嵌入页面上的嵌入 URI 验证器中。此选项无法告知您所设数据和权限是否设置正确，但可以验证您的身份验证是否正常。