签名嵌入

已签名嵌入是一种向用户呈现私密嵌入的 Look、可视化图表、探索、信息中心或 LookML 信息中心的方式,用户无需登录单独的 Looker。而是通过您自己的应用对用户进行身份验证。

签名嵌入通过创建一个特殊 Looker 网址来实现,您将在 iframe 中使用该网址。该网址包含您要共享的信息、系统中用户的 ID 以及您希望用户拥有的权限。然后,您将使用 Looker 提供的密钥对该网址进行签名。

如需了解公开嵌入,请参阅公开分享、导入和嵌入外观文档页面的使用 iframe 标记进行公开嵌入部分。

您必须先让 Looker 管理员在 Looker 管理控制台中启用已签名嵌入,并创建嵌入密钥,然后才能在 Looker 实例中使用已签名嵌入。有关说明,请参阅嵌入使用入门 - 启用签名嵌入文档页面。

为签名嵌入提供适当的托管

有些浏览器(例如 Safari)或安装了屏蔽广告或跟踪 Cookie 的扩展程序的浏览器,默认采用的 Cookie 政策会屏蔽第三方 Cookie。无 Cookie 嵌入功能启用后,屏蔽第三方 Cookie 的浏览器便可在嵌入式 iframe 中跨不同网域对用户进行身份验证。无 Cookie 嵌入身份验证需要进行服务器端配置。如需查看设置示例,请参阅无 Cookie 嵌入文档页面。

如果未启用不使用 Cookie 的嵌入式功能,Looker 会使用 Cookie 进行用户身份验证。在这种情况下,如果浏览器阻止第三方 Cookie,则无法尝试跨网域对嵌入的 iframe 进行身份验证(除非用户修改浏览器的 Cookie 隐私设置)。例如,如果您想在 https://mycompany.com 上嵌入信息,则需要确保 Looker 与 https://analytics.mycompany.com 等共用同一网域。在这种情况下,如果您的实例是由 Looker 托管,请与 Looker 支持团队联系,以设置必要的 DNS 配置以启用自定义网域使用。这样,Looker 就可以与嵌入应用共享同一网域,并使用第一方 Cookie(所有浏览器都会默认接受第一方 Cookie)。

如果您使用的是客户托管的 Looker 实例,请确保将使用已签名嵌入的应用使用与您的 Looker 实例相同的网域。

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

在已签名嵌入配置中,Looker 用户通常会向自己的客户呈现数据,同时客户来自不同的公司或群组,彼此之间不应互相知晓。在这种情况下,为了保护客户私密信息,我们强烈建议您将 Looker 配置为封闭式系统,也称为多租户安装。在封闭系统中,内容是孤岛化的,以防止不同群组的用户互相了解。因此,我们建议您先启用封闭式系统选项,然后再向任何外部用户授予对您的实例的访问权限。

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

生成已签名的嵌入网址

您可以通过多种方式生成带签名的嵌入网址。您可以使用以下任一方法:

手动编码签名嵌入网址

如需对已签名的嵌入网址进行编码,请先收集必要的 Looker 信息,然后创建已签名的嵌入网址

收集必要的 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/explore/my_model/my_explore?qid=1234567890abcdefghij12

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

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

您可以使用 Looker 探索界面构建包含受支持的可视化图表的查询,然后从 qid= 参数复制 Query.client_id 值;或者,您也可以使用 Looker API 检索 Query.client_id,例如使用 Get Query 方法。
/embed/query-visualization/Query.client_id
用户定义的信息中心 https://instance_name.looker.com/dashboards/1

添加所有信息中心过滤条件值;如果隐藏过滤条件值,请在信息中心网址中添加 hide_filter 参数。
用户定义的旧版信息中心 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 实例中执行某些功能,但无法访问基于其角色模型集未涵盖的模型的内容。

确定您希望用户拥有的权限。下表列出了已签名嵌入的所有可用权限。签名嵌入不支持下列列表中未列出的权限:

权限 依赖项 类型 定义
access_data 特定于模型 允许用户访问数据(查看数据洞见、信息中心或探索时必需)
see_lookml_dashboards access_data 特定于模型 允许用户查看 LookML 信息中心
see_looks access_data 特定于模型 允许用户查看 Look
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 特定于模型 允许用户安排将 Looker 内容传送至任意网络钩子
send_to_s3 see_looks 特定于模型 允许用户安排将 Looker 内容传送至 Amazon S3 存储桶
send_to_sftp see_looks 特定于模型 允许用户安排将 Looker 内容传送至 SFTP 服务器
schedule_look_emails see_looks 特定于模型 允许用户将 Looker 内容提交到自己的电子邮件地址(如果使用名为“email”的用户属性进行设置),或提交到符合电子邮件网域许可名单限制的电子邮件地址。允许具有 create_alerts 权限的用户向 电子邮件网域许可名单设置的限制范围内的电子邮件地址发送提醒通知。
schedule_external_look_emails schedule_look_emails 特定于模型 允许用户安排将 Looker 内容递送到任何电子邮件网域。允许拥有 create_alerts 权限的用户向任何电子邮件网域发送提醒通知。
send_to_integration see_looks 特定于模型 允许用户通过 Looker Action Hub 将 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_lookssee_user_dashboardssee_lookml_dashboards 权限。
embed_save_shared_space 实例级 已添加 21.4 允许同时拥有 save_content 权限的用户在保存对话框中导航到组织的 Shared 文件夹(如果有)。如果用户拥有 save_content 权限但没有 embed_save_shared_space 权限,则只能选择将内容保存到自己的个人嵌入文件夹中。

embed_save_shared_space 权限不会替换内容访问权限。例如,为了让用户能够保存到共享文件夹,他们仍然需要对共享文件夹拥有管理访问权限、修改权限。此外,如果用户拥有 save_content 权限以及对 Shared 文件夹的管理、修改权限,但可以通过其他方式导航到 Shared 文件夹(例如使用嵌入式信息中心内的从此处探索选项),那么即使没有 embed_save_shared_space 权限,系统也无法阻止该用户在此文件夹中保存内容。

模型访问权限

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

用户属性

确定用户应具备哪些用户属性(如果有)。您需要来自 Looker 的用户属性名称,以及用户应为该属性设置的值。

群组

确定用户应属于哪些群组(如果有)。您需要提供群组 ID,而不是群组名称。将已签名的嵌入用户添加到 Looker 群组后,您可以管理该用户对 Looker 文件夹的访问权限。已登录的嵌入用户将有权访问与其 Looker 群组成员共享的所有文件夹。

您还可以使用 external_group_id 参数创建常规 Looker 群组外部的群组。在这种情况下,具有相同 external_group_id 的已登录嵌入用户将有权访问名为“Group”且仅供外部群组使用的共享文件夹。

嵌入式角色

permissionsmodels 参数会为嵌入用户创建角色。此角色会显示为 Looker 管理部分的用户页面中的“嵌入式角色”。如果嵌入网址中的 permissionsmodelsgroup_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/嵌入式网址?PARAMETERS&signature=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 无法自行添加此参数,因为它是签名网址的一部分。

参数

以下网址参数用于指定带签名的嵌入的必要信息:

参数 默认值 说明 数据类型 示例
nonce 值必填 您喜欢的任何随机字符串,但不能在一小时内重复使用,且长度不得超过 255 个字符。

这样可以防止攻击者重新提交合法用户的网址,以收集他们本不应该拥有的信息。
JSON 字符串 "22b1ee700ef3dc2f500fb7"
time 值必填 当前时间(以 UNIX 时间戳表示)。 整数 1407876784
session_length 必须提供值 用户应在 Looker 中保持登录状态的秒数,介于 0 到 2,592,000 秒(30 天)之间。 整数 86400
external_user_id 值必填 嵌入 Looker 的应用中的每位用户的标识符。Looker 使用 external_user_id 来区分已登录的嵌入用户,因此必须为每位用户分配唯一 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 的用户将能够在名为“Group”(群组)的共享 Looker 文件夹中保存和修改内容。external_group_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 "" 如果您已启用用户专用时区,请在嵌入式数据分析中或信息中心的时区下拉菜单中设置观看者时区选项的值。此参数不会直接更改内容显示的时区;用户需要从下拉菜单中选择时区。

请参阅签名嵌入时区参考文档文档页面中的有效值。

聊天团队提示:如果您希望将嵌入的内容默认使用观看者的时区,请使用以下方法之一:

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

    /embed/dashboards/1?query_timezone=user_timezone
  • 保存嵌入式信息中心或 Look,并将默认时区设置为查看者时区,系统将默认针对嵌入用户和非嵌入用户使用用户的时区。
  • JSON 字符串或 null "US/Pacific"

    - 或 -

    null
    force_logout_login 值必填 如果普通 Looker 用户已登录 Looker,并且查看已签名的嵌入内容,您可以选择:

    1) 他们应使用当前凭据查看商品

    2) 他们应退出登录,然后使用已签名的嵌入凭据重新登录。
    布尔值(true 或 false) true

    签名

    Looker 使用该签名来验证在嵌入网址中生成签名时使用的嵌入密钥是否正确,以及嵌入网址中的参数是否未更改。如果嵌入密钥或网址参数不同或已更改,签名将不匹配,并且系统会拒绝身份验证。

    因此,嵌入网址中的签名可提供强大的加密证明,证明嵌入网址在传输过程中未被修改,并且嵌入网址是由拥有嵌入密钥的可信方创建的。

    如需生成签名,您需要按以下步骤操作。

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

    编码

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

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

    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 Signed Embed Url API 端点

    Looker API 包含创建已签名的嵌入网址端点,该端点接受一组已签名的嵌入参数(包括要嵌入的内容的网址),并返回经过编码且经过加密签名的完整网址。

    如需从网络服务器使用此 API 端点,该网络服务器必须能够使用管理员权限对 Looker API 进行身份验证。Web 服务器网域还必须列在嵌入网域许可名单中。

    您还可以使用 API Explorer 生成使用此端点的签名网址。您可以通过 Looker Marketplace 在 Looker 实例上安装 API Explorer。生成后,必须完全复制签名网址,并且只能使用一次,否则签名网址将失败。API Explorer 还非常适合用于生成签名网址,并将其与手动创建的签名网址进行比较,以便进行问题排查。

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

    测试嵌入网址

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