签名嵌入是一种向用户呈现不公开的嵌入式 Look、可视化图表、探索、信息中心或 LookML 信息中心的方法,用户无需拥有单独的 Looker 登录信息。而是通过您自己的应用对用户进行身份验证。
签名嵌入的工作原理是创建一个将在 iframe 中使用的特殊 Looker 网址。该网址包含您想要共享的信息、您系统中用户的 ID 以及您希望用户拥有的权限。然后,您将使用 Looker 提供的密钥对该网址进行签名。
如需了解公开嵌入,请参阅公开共享、导入和嵌入 Look 文档页面的使用 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 配置为封闭式系统(也称为“多租户安装”)。在封闭系统中,内容是孤立的,可防止不同群组的用户相互了解。因此,我们建议您先启用封闭式系统选项,然后再向任何外部用户授予对您实例的访问权限。
如需了解详情,请参阅设计和配置访问权限级别系统以及嵌入式分析的安全最佳实践文档页面。
生成已签名的嵌入网址
您可以通过多种方式生成已签名的嵌入网址。您可以使用以下方法之一:
您可以使用信息中心的三点状信息中心菜单上的获取嵌入网址选项,或者在 Look 或探索的“探索操作”齿轮菜单上生成已签名的嵌入网址。
使用 Looker Embed SDK。
对已签名的嵌入网址进行编码。若要构建正确的 网址,您需要编写代码,以便能够使用密钥正确对 网址 进行编码并生成其他与安全相关的项。您可以在 Looker 嵌入示例 GitHub 代码库中找到多个示例脚本。下文介绍了您需要向这些脚本提供的信息,以及如何在不使用脚本的情况下构建签名嵌入网址。
手动对已签名的嵌入网址进行编码
如需对已签名的嵌入网址进行编码,请先收集必要的 Looker 信息,然后创建已签名的嵌入网址。
收集必要的 Looker 信息
构建网址时,您首先需要确定需要包含的所有信息。您需要有:
嵌入网址
检索要嵌入的 Look、探索、查询可视化图表或信息中心的网址。然后移除域名并将 /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 值,或者您也可以使用 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 |
无 | 特定于模型 | 允许用户访问数据(查看 Look、信息中心或探索时必须授予) |
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 |
实例级 | ADD 22.4 在探索中创建自定义字段时需要使用 |
can_create_forecast |
explore |
实例级 | 增加 22.12 允许用户在可视化图表中创建或修改预测。 |
save_content |
see_looks |
实例级 | 允许用户更改和保存对 Look 和信息中心的更改 |
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 用户可以清除缓存和刷新嵌入式信息中心、旧版信息中心、信息中心图块、Look 和探索。 |
see_drill_overlay |
access_data |
特定于模型 | 让用户无需转到整个“探索”页面即可深入分析。 |
embed_browse_spaces |
无 | 实例级 | 启用内容浏览器,以便用户浏览嵌入内容中的文件夹。任何被授予 embed_browse_spaces 权限的嵌入用户都将获得个人嵌入文件夹和贵组织的 Shared 文件夹(如果有)的访问权限。建议为拥有 save_content 权限的用户授予 embed_browse_spaces 权限,以便用户在选择将内容保存到何处时可以浏览文件夹。如要查看文件夹中的内容,用户还需要拥有 see_looks 、see_user_dashboards 和 see_lookml_dashboards 权限。 |
embed_save_shared_space |
无 | 实例级 |
已添加 21.4
让同时拥有 save_content 权限的用户在保存对话框中导航到组织的 Shared 文件夹(如果有)。拥有 save_content 权限但没有 embed_save_shared_space 权限的用户只能选择将内容保存到其个人嵌入文件夹。embed_save_shared_space 权限不会替换内容访问权限。例如,要让用户能够将文件保存到共享文件夹,用户仍然需要对共享文件夹拥有管理访问权限、修改权限。此外,即使用户没有 embed_save_shared_space 权限,如果拥有 Shared 文件夹的 save_content 权限和 Manage Access, Edit 访问权限,但可以通过其他方式导航到 Shared 文件夹(例如使用嵌入式信息中心内的从此处探索选项),也无法阻止用户将内容保存在该文件夹中。 |
模型访问权限
确定用户应有权访问哪些 LookML 模型。这只是模型名称列表。
用户属性
确定用户应具备哪些用户属性(如果有)。您需要 Looker 中的用户属性的名称,以及用户应该具有的该属性值。
群组
确定用户应属于哪些群组(如果有)。您需要的是群组 ID,而不是群组名称。通过将已签名的嵌入用户添加到 Looker 群组,您可以管理该用户对 Looker 文件夹的访问权限。签名的嵌入用户将有权访问与其 Looker 群组的成员共享的任何文件夹。
您还可以使用 external_group_id
参数创建常规 Looker 群组以外的群组。在这种情况下,具有相同 external_group_id
的已签名嵌入用户将有权访问外部群组专属的名为“群组”的共享文件夹。
嵌入式角色
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 网址?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 的用户将能够在名为“群组”的共享 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 将保留最后一个请求的值,如果未设置名字,则为“嵌入”。 |
JSON 字符串 | "Alice" |
last_name |
"" | 用户的姓氏。如果留空,last_name 将保留最后一个请求中的值,如果未设置姓氏,则设为“Embed”。 |
JSON 字符串 | "Jones" |
user_timezone |
"" | 如果您启用了用户专属时区,请在嵌入式 Look 或信息中心的时区下拉菜单中设置观看者时区选项的值。此参数不会直接更改显示内容的时区;用户需要从下拉列表中选择一个时区。请参阅签名嵌入时区参考文档页面中的有效值。Chat 团队提示:如果您希望嵌入的内容默认采用观看者所在的时区,请使用以下任一方法:?query_timezone=user_timezone 添加到嵌入网址。例如:/embed/dashboards/1?query_timezone=user_timezone |
JSON 字符串或 null | "US/Pacific" - 或 -null |
force_logout_login |
必须提供值 | 如果普通 Looker 用户已登录 Looker,并且他们查看了已签名的嵌入内容,那么您可以在以下情况下选择:1) 用户应通过当前凭据查看相应内容或2) 应退出登录,然后使用已签名的嵌入凭据重新登录。 | Boolean(true 或 false) | true |
签名
若要生成签名,您需要按以下步骤操作。
- 按以下顺序收集以下参数值:
- 主机,后跟
login/embed/
(例如analytics.mycompany.com/login/embed/
) - 嵌入网址
- Nonce
- 当前时间
- 会话时长
- 外部用户 ID
- 权限
- 模型
- 群组 ID
- 外部群组 ID
- 用户属性
- 访问权限过滤条件(需要空占位符)
- 主机,后跟
- 除“主机”和“嵌入网址”之外的所有值均采用 JSON 格式
- 使用换行符 (
\n
) 将值串联起来 - 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 Signed Embed Url API 端点
Looker API 包含创建签名嵌入网址端点,该端点接受一组已签名的嵌入参数(其中包含您要嵌入的内容的网址),并返回经过编码且经过加密签名的完整网址。
如需从 Web 服务器使用此 API 端点,Web 服务器必须能够以管理员权限向 Looker API 进行身份验证。Web 服务器网域也必须列入嵌入网域许可名单。
您也可以通过 API Explorer 生成使用此端点的签名网址。您可以通过 Looker Marketplace 在 Looker 实例上安装 API Explorer。生成后,必须准确复制签名网址,并且只能使用一次,否则将会失败。API Explorer 还有助于生成签名网址并将其与手动创建的签名网址进行比较,以便排查问题。
如需详细了解 Looker API,请参阅 Looker API 使用入门文档页面。
测试嵌入网址
如需测试最终到达网址,请将其粘贴到 Looker 管理部分的嵌入页面上的嵌入 URI 验证器中。虽然此选项无法告知您预想的数据和权限是否已正确设置,但可以验证您的身份验证是否正常运行。