在 Snowflake 上运行联合查询 （Okta）

本页介绍如何设置 Lakehouse 联邦查询系统，以对未由 Azure Databricks 管理的 Snowflake 数据运行联邦查询。 若要了解有关 Lakehouse 联合的更多信息，请参阅 什么是 Lakehouse 联合？

若要使用 Lakehouse Federation 连接到 Snowflake 数据库，必须在 Azure Databricks Unity Catalog 元存储中创建以下内容：

• 与 Snowflake 数据库的连接。
• 一个外部目录，它镜像 Unity Catalog 中的 Snowflake 数据库，以便你可使用 Unity Catalog 查询语法和数据治理工具来管理 Azure Databricks 用户对数据库的访问。

了解如何使用 Okta 作为外部 OAuth 提供程序对 Snowflake 数据运行联合查询。 此页面涵盖用户到计算机（U2M）和计算机到计算机（M2M）流。

有关其他身份验证方法，请参阅以下页面：

• Snowflake 内置 OAuth
• 具有 Microsoft Entra ID 的 OAuth
• OAuth 访问令牌
• PEM 私钥
• 基本身份验证（用户名/密码）

可以使用查询联合或目录联合在 Snowflake 上运行联合查询。

在查询联合中，JDBC 将 Unity 目录查询向下推送到外部数据库。 这非常适合在您的 ETL 管道上进行按需生成报告或概念验证工作。

在目录联合中，Unity 目录查询直接针对文件存储运行。 这种方法对于没有代码调整的增量迁移很有帮助，或者对于那些必须在 Unity Catalog 中注册数据的同时在 Snowflake 中维护一些数据的组织来说，这是一个长期的混合模型。 请参阅 启用 Snowflake 数据目录联邦。

在您开始之前

工作区要求：

• 已为 Unity Catalog 启用工作区。

计算要求：

• 计算资源与目标数据库系统之间的网络连接。 请参阅 Lakehouse Federation 网络建议。
• Azure Databricks 计算必须使用 Databricks Runtime 13.3 LTS 或更高版本以及 标准 或 专用 访问模式。
• SQL 仓库必须是专业或无服务器，并且必须使用 2023.40 或更高版本。

所需的权限：

• 若要创建连接，你必须是元存储管理员或对附加到工作区的 Unity Catalog 元存储具有 CREATE CONNECTION 权限的用户。
• 若要创建外部目录，你必须对元存储具有 CREATE CATALOG 权限，并且是连接的所有者或对连接具有 CREATE FOREIGN CATALOG 特权。

后面的每个基于任务的部分中都指定了其他权限要求。

Snowflake 中的外部 OAuth 是什么？

外部 OAuth 是一种身份验证方法，可用于使用 OAuth 2.0 访问 Snowflake 的外部服务器。 用户或应用程序无需直接登录到 Snowflake，而是通过 OAuth 提供程序（例如 Okta、Microsoft Entra ID 或 PingFederate）来进行身份验证。

然后，OAuth 提供程序会颁发访问令牌，Databricks 向 Snowflake 提供该令牌。 然后，Snowflake 使用配置的安全集成验证令牌的签名和声明，并授予访问权限。

确定 OAuth 流程

若要为 Snowflake 连接器选择正确的 OAuth 流，需要了解两种主要类型：U2M（用户到计算机）和 M2M（计算机到计算机）。

U2M 是一种授权流程，其中应用程序（Azure Databricks）获得代表用户进行操作的权限。 此流是交互式的，这意味着在创建外部连接时，系统会提示用户登录，并且应用程序会收到限定于 用户权限的访问令牌。

M2M 是一种非交互式流，当应用程序需要直接访问资源时，无需用户参与。 在此流中，应用程序必须在 OAuth 提供程序中注册一组权限，独立于任何特定用户。

在 Azure Databricks 工作区中，OAuth 是指 U2M 身份验证，OAuth 机器对机器 是指 M2M 身份验证。

配置 Okta

确切的 Okta 配置取决于公司的需求和策略。 本部分和以下部分中的步骤可指导你完成功能 OAuth 设置，并表示简单的工作示例，而不是详尽的 Okta 资源。 有关其平台和功能的深入报道，请参阅 Okta 文档。

创建 OAuth 客户端

Okta 中的 OAuth 兼容客户端表示需要与 Okta 的授权服务器交互才能获取令牌的应用程序。 在本例中，客户端表示 Azure Databricks。

1. 在 Okta 管理控制台中，导航到 “应用程序”，然后单击“ 创建应用集成”。

2. 选择 OIDC （OpenID Connect） 登录方法。

3. 选择应用程序类型：

   • （仅限 U2M）选择 本机应用程序。
   • （仅限 M2M）选择 “Web 应用程序”。

4. 单击 “下一步” 。

5. 输入应用程序的名称。

6. 选择授予类型：

   • （仅限 U2M）选择 授权代码 并 刷新令牌。
   • （仅限 M2M）选择 客户端凭据。

7. （仅限 U2M）添加 https://<WORKSPACE>/login/oauth/snowflake.html 为 登录重定向 URI。

8. 为受控访问选择所需的值。 出于测试目的， 允许组织中的每个人访问 就足够了。

9. 启用 联合代理模式后，保持即时访问 。

10. 单击“ 保存”。

    你将被重定向到新创建的应用程序页。

11. 在 “客户端凭据 ”部分中，记下 客户端 ID 值。

12. 单击 “编辑 ”并选择“ 客户端密码”，然后单击“ 保存”。

13. 复制机密并存储此值以供以后使用。

如果选择使用联合代理模式禁用即时访问，则必须在分配选项卡中分配用户。有关详细信息，请参阅 Okta 文档。

创建授权服务器

1. 在 Okta 管理控制台中，展开 “安全 ”部分并单击 “API”。

2. 单击“ 添加授权服务器”。

3. 输入名称。

4. 请使用您的 Snowflake JDBC URL 和主机，确保保持 URL 模式（https 前缀）不变，以供受众使用。

5. 单击“ 保存”。 将重定向到新创建的授权服务器。

6. 在“ 作用域 ”选项卡中，单击“ 添加作用域”。 将名称设置为所需的 Snowflake 范围（例如 session:role:PUBLIC）。 单击 “创建” 。

7. 单击 “访问策略”，然后单击“ 添加新访问策略”。

8. 输入策略的名称和说明。

9. 将策略分配给创建的客户端，然后单击“ 创建”。

10. 在访问策略中，单击“ 添加规则”。

11. 输入规则名称。

12. 选择授权的授予类型：

    • （仅限 U2M）选择 授权代码。
    • （仅限 M2M）选择 客户端凭据。

13. 对于范围，可以选择 “任何范围 ”或选择之前创建的所需范围。

14. （仅限 U2M）如果要接收刷新令牌，请将 offline_access 包含在作用域列表中。

15. 根据需要配置任何其他设置。

16. 最后，单击“ 创建规则”。

检索 Okta 信息

记下以下信息：

• 客户端 ID 和客户端密码：从创建的客户端应用程序中检索这些密码。

• OIDC （OpenID Connect） 元数据：

  1. 在授权服务器页上，单击“设置”选项卡中的“元数据 URI”链接。
  2. （仅限 U2M）按以下格式复制 authorization_endpoint 值： https://<OKTA_ENV_ID>.okta.com/oauth2/<AUTH_SERVER_ID>/v1/authorize
  3. （仅限 M2M）复制 元数据 URI 链接。 Databricks 中的 Snowflake M2M 连接直接读取此元数据，并自动检索所有必要的信息。
  4. 复制 颁发者 值 - 在 Snowflake 设置期间需要此值。

创建安全集成

此步骤在 Snowflake 中配置安全集成，以便 Snowflake 可以安全地与 Okta 通信、验证令牌，并根据与 OAuth 访问令牌关联的角色提供适当的数据访问。

U2M 流动

1. 以具有角色的用户 ACCOUNTADMIN 身份连接到 Snowflake 帐户。

2. 运行 CREATE SECURITY INTEGRATION 命令。 例如：

   CREATE SECURITY INTEGRATION <OKTA_U2M_SECURITY_INTEGRATION_NAME>
   TYPE = EXTERNAL_OAUTH
   ENABLED = TRUE
   EXTERNAL_OAUTH_TYPE = OKTA
   EXTERNAL_OAUTH_ISSUER = '<OKTA_OAUTH_ISSUER_URL>'
   EXTERNAL_OAUTH_JWS_KEYS_URL = '<OKTA_OAUTH_ISSUER_URL>/v1/keys'
   EXTERNAL_OAUTH_AUDIENCE_LIST = ('<SNOWFLAKE_APPLICATION_ID_URI>')
   EXTERNAL_OAUTH_TOKEN_USER_MAPPING_CLAIM = 'sub'
   EXTERNAL_OAUTH_SNOWFLAKE_USER_MAPPING_ATTRIBUTE = 'EMAIL_ADDRESS';
   

   该示例使用了电子邮件映射声明和属性。 这要求 Snowflake 用户电子邮件与 Okta 用户的电子邮件匹配。

   ALTER USER <SNOWFLAKE_USER> SET EMAIL = '<YOUR_EMAIL>';
   

   可以根据要求使用不同的声明。

M2M 流

1. 以具有角色的用户 ACCOUNTADMIN 身份连接到 Snowflake 帐户。

2. 运行 CREATE SECURITY INTEGRATION 命令。 例如：

   CREATE OR REPLACE SECURITY INTEGRATION <OKTA_M2M_SECURITY_INTEGRATION_NAME>
   TYPE = EXTERNAL_OAUTH
   ENABLED = TRUE
   EXTERNAL_OAUTH_TYPE = OKTA
   EXTERNAL_OAUTH_ISSUER = '<OKTA_OAUTH_ISSUER_URL>'
   EXTERNAL_OAUTH_JWS_KEYS_URL = '<OKTA_OAUTH_ISSUER_URL>/v1/keys'
   EXTERNAL_OAUTH_AUDIENCE_LIST = ('<SNOWFLAKE_APPLICATION_ID_URI>')
   EXTERNAL_OAUTH_TOKEN_USER_MAPPING_CLAIM = 'sub'
   EXTERNAL_OAUTH_SNOWFLAKE_USER_MAPPING_ATTRIBUTE = 'login_name';
   

   必须在 Snowflake 中创建新的非人类用户来表示连接到数据库的客户端。 将登录名设置为 OAuth 客户端的客户端 ID。

   CREATE OR REPLACE USER <OKTA_M2M_CLIENT_USER>
   LOGIN_NAME = '<CLIENT_ID>'
   DEFAULT_ROLE = 'PUBLIC';
   

创建连接

连接指定用于访问外部数据库系统的路径和凭据。 若要创建连接，可以使用目录资源管理器，或者使用 Azure Databricks 笔记本或 Databricks SQL 查询编辑器中的 CREATE CONNECTION SQL 命令。

所需的权限：具有 CREATE CONNECTION 特权的元存储管理员或用户。

U2M 流

1. 在 Azure Databricks 工作区中，单击 目录。

2. 在目录窗格顶部，单击“添加”或“加号”图标，然后从菜单中选择“添加连接”。

   或者，在“快速访问”页中，单击“外部数据 >”按钮，转到“连接”选项卡，然后单击“创建连接。

3. 在“设置连接”向导的“连接基本信息”页上，输入一个用户友好的“连接名称”。

4. 选择“Snowflake”的连接类型。

5. 对于 身份验证类型， OAuth 请从下拉菜单中进行选择。

6. （可选）添加注释。

7. 单击 “下一步” 。

8. 输入 Snowflake 仓库的以下身份验证和连接详细信息：

   • 主机：例如 snowflake-demo.east-us-2.azure.snowflakecomputing.com
   • 端口：例如 443
   • 用户：例如 snowflake-user
   • 授权终结点： https://<OKTA_ENV_ID>.okta.com/oauth2/<AUTH_SERVER_ID>/v1/authorize
   • 客户端密码：创建安全集成时保存的客户端密码。
   • 客户端 ID：创建安全集成时保存的客户端 ID。
   • OAuth 作用域：session:role:PUBLIC offline_access
   • OAuth 提供程序：
   • 使用 Okta 登录：单击并使用您的 Okta 凭据登录到 Snowflake。

9. 单击 “下一步” 。

10. 输入以下 连接详细信息 ：

    • Snowflake 仓库：要使用的仓库的名称。
    • （可选）使用代理：是否使用代理服务器连接到 Snowflake。
    • （可选）代理主机：用于连接到 Snowflake 的代理的主机。 还必须选择 使用代理 并指定 代理端口。
    • （可选）代理端口：用于连接到 Snowflake 的代理的端口。 还必须选择 使用代理 并指定 代理主机。
    • （可选） Snowflake 角色：连接后用于会话的默认安全角色。

11. 单击“ 创建连接”。

12. 在 “目录基本信息 ”页上，输入外国目录的名称。

13. （可选）单击“测试连接”以确认它是否正常工作。

14. 单击“创建目录”。

15. 在 “访问 ”页上，选择用户可以在其中访问所创建的目录的工作区。 可以选择 “所有工作区”具有访问权限 ，或单击“ 分配给工作区”，选择工作区，然后单击“ 分配”。

16. 更改可管理对目录中所有对象的访问权限的 所有者 。 开始在文本框中键入主体，然后单击返回的结果中的主体。

17. 授予对目录的“特权”。 单击“授权”：

    1. 指定可以访问目录中对象的 主体 。 开始在文本框中键入主体，然后单击返回的结果中的主体。
    2. 选择要授予每个主体的“特权预设”。 默认情况下，向所有帐户用户授予 BROWSE。
       • 从下拉菜单中选择 “数据读取者 ”，以授予 read 对目录中对象的权限。
       • 从下拉菜单中选择 “数据编辑器”，以向 read 和 modify 授予目录中对象的权限。
       • 手动选择要授予的权限。
    3. 单击授权。

18. 单击 “下一步” 。

19. 在“元数据”页上，指定标记键值对。 有关详细信息，请参阅 将标记应用于 Unity 目录安全对象。

20. （可选）添加注释。

21. 单击“ 保存”。

M2M 流：目录浏览器

1. 在 Azure Databricks 工作区中，单击 目录。

2. 在目录窗格顶部，单击“添加”或“加号”图标，然后从菜单中选择“添加连接”。

   或者，在“快速访问”页中，单击“外部数据 >”按钮，转到“连接”选项卡，然后单击“创建连接。

3. 在“设置连接”向导的“连接基本信息”页上，输入一个用户友好的“连接名称”。

4. 选择“Snowflake”的连接类型。

5. 对于 身份验证类型， OAuth Machine to Machine 请从下拉菜单中进行选择。

6. （可选）添加注释。

7. 单击 “下一步” 。

8. 输入连接的以下身份验证详细信息：

   • 主机：例如 snowflake-demo.east-us-2.azure.snowflakecomputing.com
   • 端口：例如 443
   • Openid 元数据终结点： https://<OKTA_ENV_ID>.okta.com/oauth2/<AUTH_SERVER_ID>/.well-known/oauth-authorization-server
   • 客户端密码：创建安全集成时保存的客户端密码。
   • 客户端 ID：创建安全集成时保存的客户端 ID。
   • OAuth 作用域：session:role:PUBLIC

9. 单击 “下一步” 。

10. 输入以下连接的详细信息：

    • Snowflake 仓库：要使用的仓库的名称。
    • （可选）代理主机：用于连接到 Snowflake 的代理的主机。 还必须选择 使用代理 并指定 代理端口。
    • （可选）使用代理：是否使用代理服务器连接到 Snowflake。
    • （可选）代理端口：用于连接到 Snowflake 的代理的端口。 还必须选择 使用代理 并指定 代理主机。
    • （可选） Snowflake 角色：连接后用于会话的默认安全角色。

11. 单击“ 创建连接”。

12. 在 “目录基本信息 ”页上，输入外国目录的名称。

13. （可选）单击“测试连接”以确认它是否正常工作。

14. 单击“创建目录”。

15. 在 “访问 ”页上，选择用户可以在其中访问所创建的目录的工作区。 可以选择 “所有工作区”具有访问权限 ，或单击“ 分配给工作区”，选择工作区，然后单击“ 分配”。

16. 更改可管理对目录中所有对象的访问权限的 所有者 。 开始在文本框中键入主体，然后单击返回的结果中的主体。

17. 授予对目录的“特权”。 单击“授权”：

    1. 指定可以访问目录中对象的 主体 。 开始在文本框中键入主体，然后单击返回的结果中的主体。
    2. 选择要授予每个主体的“特权预设”。 默认情况下，向所有帐户用户授予 BROWSE。
       • 从下拉菜单中选择 “数据读取者 ”，以授予 read 对目录中对象的权限。
       • 从下拉菜单中选择 “数据编辑器”，以向 read 和 modify 授予目录中对象的权限。
       • 手动选择要授予的权限。
    3. 单击授权。

18. 单击 “下一步” 。

19. 在“元数据”页上，指定标记键值对。 有关详细信息，请参阅 将标记应用于 Unity 目录安全对象。

20. （可选）添加注释。

21. 单击“ 保存”。

M2M 流：SQL

在笔记本或 Databricks SQL 查询编辑器中运行以下命令。

CREATE CONNECTION <connection-name>
TYPE SNOWFLAKE
OPTIONS (
  host '<hostname>',
  port '443',
  sfWarehouse '<warehouse-name>',
  client_id '<client-id>',
  client_secret '<client-secret>',
  openid_metadata_endpoint '<oidc-metadata-endpoint>',
  oauth_scope 'session:role:PUBLIC'
);

然后，可以通过运行以下命令，使用新连接创建外部目录：

CREATE FOREIGN CATALOG <catalog-name>
USING CONNECTION <connection-name>
OPTIONS (database = '<database>');

区分大小写的数据库标识符

外部目录的 database 字段映射到 Snowflake 数据库标识符。 如果 Snowflake 数据库标识符不区分大小写，则会保留在外部目录 <database-name> 中使用的大小写。 但是，如果 Snowflake 数据库标识符区分大小写，则必须用双引号将外部目录 <database-name> 括起来以保留大小写。

例如：

• database 转换为 DATABASE

• "database" 转换为 database

• "database""" 转换为 database"

  若要转义双引号，请使用另一个双引号。

• "database"" 会导致出错，因为双引号未正确进行转义。

有关详细信息，请参阅 Snowflake 文档中的标识符要求。

支持的下推

支持以下下推：

• 过滤 器
• 预测
• 限度
• 联接
• 聚合（Average、Corr、CovPopulation、CovSample、Count、Max、Min、StddevPop、StddevSamp、Sum、VariancePop、VarianceSamp）
• 函数（字符串函数、数学函数、数据、时间和时间戳函数以及其他杂项函数，例如 Alias、Cast、SortOrder）
• Windows 函数（DenseRank、Rank、RowNumber）
• 排序

数据类型映射

从 Snowflake 读取到 Spark 时，数据类型映射如下所示：

局限性

• 必须可从 Azure Databricks 控制平面 IP 访问 Snowflake OAuth 终结点。 请参阅 Azure Databricks 控制平面中的出站 IP。 Snowflake 支持在安全集成级别配置网络策略，该策略允许使用单独的网络策略，以便从 Azure Databricks 控制平面直接连接到 OAuth 终结点进行授权。