为 External OAuth 配置 Okta

本主题介绍如何将 Snowflake 配置为 OAuth 资源，并将 Okta 配置为 External OAuth 授权服务器，以促进对 Snowflake 数据的安全、编程访问。

配置过程

以下五个步骤假设您的环境没有配置与 Okta OAuth 授权服务器、OAuth 客户端、范围和必要元数据相关的任何内容。

第 1-3 步中的信息将用于在 Snowflake 中创建安全集成。

如果您已配置 Okta 授权服务器和客户端，则无需完成以下所有步骤。相反，请浏览以下四个步骤，并验证您可以获得所需的信息、创建范围、将范围分配给一个或多个策略以及访问元数据。

如果您尚未配置 Okta OAuth 授权服务器和客户端，请完成以下所有五个步骤。

重要

本主题中的步骤是有关如何为 External OAuth 配置 Okta 的 代表性示例。

您可以将 Okta 配置为任何所需的状态，并使用任何所需的 OAuth 流程，前提是您可以获得 安全集成 所需的信息（本主题内容）。

请注意，以下步骤可作为获取在 Snowflake 中创建安全集成所需信息的指南。

请务必咨询有关配置授权服务器的内部安全策略，以确保您的组织满足所有必要的法规和合规性要求。

步骤 1-3 源自授权服务器上的 Okta 文档。有关 Okta 如何定义其术语、用户界面以及与授权服务器相关的选项的更多信息，请参阅以下 Okta 指南：

  • 创建授权服务器 (https://developer.okta.com/docs/guides/customize-authz-server/overview/)

  • 实施授权代码流程 (https://developer.okta.com/docs/guides/implement-auth-code/overview/)

  • 使用 PKCE 实施授权代码流程 (https://developer.okta.com/docs/guides/implement-auth-code-pkce/overview/)

  • 实施客户端凭证流程 (https://developer.okta.com/docs/guides/implement-client-creds/overview/)

  • 实施资源所有者密码流程 (https://developer.okta.com/docs/guides/implement-password/overview/)

  • 刷新访问令牌 (https://developer.okta.com/docs/guides/refresh-tokens/overview/)

创建与 Snowflake 结合使用的 OAuth 兼容客户端

  1. 导航到 Okta 管理控制台。

  2. 点击 Applications。

  3. 点击 Add Application。

  4. 点击 Create New App。

    • 对于 Platform，选择 Native App。

  5. 点击 Create。

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

  7. 在 Login redirect URIs 框中，添加完整的 Snowflake 账户 URL（即 https://<account_identifier>.snowflakecomputing.cn）。有关可能的 URL 格式的列表，请参阅 与 URL 连接。

  8. 点击 Save。

  9. 从 General 的 New Applications 中，点击 Edit。

  10. 查看 Refresh Token 和 Resource Owner Password。

  11. 点击 Save。

  12. 点击 Client Credentials 旁边的 Edit 按钮。

  13. 选择 Use Client Authentication 选项。

  14. 点击 Save。

  15. 在 Client Credentials 容器中，保存 ClientID 和 Secret。在以下步骤中，这两个值将分别称为 <OAUTH_CLIENT_ID> 和 <OAUTH_CLIENT_SECRET>。

创建 OAuth 授权服务器

  1. 导航到 Okta 管理控制台。

  2. 在 Security 菜单中，点击 API。

  3. 点击 Authorization Servers。

  4. 点击 Add Authorization Server。

  5. 输入名称。

  6. 输入 Snowflake 账户 URL 作为 Audience 值。有关可能的 URL 格式的列表，请参阅 与 URL 连接。

  7. 点击 Save。

为新添加的授权服务器完成以下步骤。

  1. 复制 Issuer 值。它的格式应该类似于 https://dev-390798.oktapreview.com/oauth2/auslh9j9vf9ej7NfT0h7。以下步骤中，该值将称为 <OKTA_ISSUER>。

  2. 点击 Scopes。

  3. 点击 Add Scope。

  4. 要将 Snowflake 角色添加为范围，请使用带有 session:role: 前缀的 Snowflake 角色名称来输入范围（例如：对于 Snowflake Analyst 角色，输入 session:role:analyst）。

  5. 点击 Create。

  6. 点击 Access Policies。

  7. 点击 Add Policy。

  8. 输入策略的名称和描述。将其分配给之前创建的客户端并点击 Create。

  9. 在新添加的访问策略中，点击 Add Rule。

  10. 输入规则名称。

  11. 选择已授权的 Grant Types。您应该选择 Resource Owner Password 和 Client Credentials 以及符合您组织策略的任何其他内容。

  12. 对于范围，您可以选择任何范围或选择之前创建的、分配给此策略的客户端将能够请求的所需范围（如果需要，包括用于刷新令牌的离线访问）。根据需要配置任何其他设置。

  13. 点击 Create Rule。

收集 Okta 信息

  1. 转至 Okta 管理控制台。

  2. 在 Security 菜单中，点击 API。

  3. 点击 Authorization Servers。

  4. 点击 Snowflake 资源的授权服务器。

  5. 在 Settings 选项卡中，复制 Issuer 值。以下步骤中，该值将称为 <OKTA_ISSUER>。它的格式应该类似于 https://dev-111111.oktapreview.com/oauth2/auslh9j9vf9ej7NfT0h7。

在 Metadata 文档中：

  1. 复制 Metadata URI 值，打开浏览器选项卡，然后在地址栏中粘贴 URL。

  2. 您应该在浏览器中看到 JSON 文本。您可以在文本编辑器或浏览器中处理此文本。

  3. 找到 "jwks_uri" 参数并复制其值。它的格式应该类似于 https://dev-111111.oktapreview.com/oauth2/auslh9j9vf9ej7NfT0h7/v1/keys。以下步骤中，此端点将称为 <OKTA_JWS_KEY_ENDPOINT>。

  4. 找到 "token_endpoint" 参数并复制其值。它的格式应该类似于 https://dev-111111.oktapreview.com/oauth2/auslh9j9vf9ej7NfT0h7/v1/token。以下步骤中，此端点将称为 <OKTA_OAUTH_TOKEN_ENDPOINT>。

为 Okta 创建安全集成

此步骤在 Snowflake 中创建安全集成。安全集成确保 Snowflake 可以与 Okta 安全地通信，验证来自 Okta 的令牌，并根据与 OAuth 令牌关联的用户角色向用户提供适当的 Snowflake 数据访问权限。

有关更多信息，请参阅 CREATE SECURITY INTEGRATION。

重要

只有账户管理员（即具有 ACCOUNTADMIN 角色的用户）或具有全局 CREATE INTEGRATION 权限的角色才能执行此 SQL 命令。

安全集成参数值区分大小写，您输入到安全集成中的值必须与您的环境中的值相匹配。如果大小写不匹配，则可能无法验证访问令牌，从而导致身份验证尝试失败。

与受众创建安全集成

安全集成的 external_oauth_audience_list 参数必须与您在配置 Okta 时指定的 Audience 匹配。

create security integration external_oauth_okta_2
    type = external_oauth
    enabled = true
    external_oauth_type = okta
    external_oauth_issuer = '<OKTA_ISSUER>'
    external_oauth_jws_keys_url = '<OKTA_JWS_KEY_ENDPOINT>'
    external_oauth_audience_list = ('<snowflake_account_url')
    external_oauth_token_user_mapping_claim = 'sub'
    external_oauth_snowflake_user_mapping_attribute = 'login_name';
Copy

修改 External OAuth 安全集成

您可以通过对安全集成执行 ALTER 语句来更新 External OAuth 安全集成。

有关更多信息，请参阅 ALTER SECURITY INTEGRATION (External OAuth)。

将 ANY 角色与 External OAuth 结合使用

在 Snowflake 中创建安全集成的配置步骤中，OAuth 访问令牌包括范围定义。因此，在运行时，使用 External OAuth 安全集成既不允许 OAuth 客户端，也不允许用户在 OAuth 访问令牌中使用未定义角色。

在验证访问令牌并创建会话之后，ANY 角色可以允许 OAuth 客户端和用户决定其角色。如有必要，客户端或用户可以切换到与 OAuth 访问令牌中定义的角色不同的角色。

要配置 ANY 角色，将范围定义为 SESSION:ROLE-ANY 并使用 external_oauth_any_role_mode 参数配置安全集成。此参数可以有三个可能的字符串值：

  • DISABLE 不允许 OAuth 客户端或用户切换角色（即 use role <role>;）。默认。

  • ENABLE 允许 OAuth 客户端或用户切换角色。

  • ENABLE_FOR_PRIVILEGE 允许 OAuth 客户端或用户仅为具有 USE_ANY_ROLE 权限的客户端或用户切换角色。可以将此权限授予用户可以使用的一个或多个角色，也可以撤消。例如：

    grant USE_ANY_ROLE on integration external_oauth_1 to role1;
    Copy
    revoke USE_ANY_ROLE on integration external_oauth_1 from role1;
    Copy

定义安全集成如下：

create security integration external_oauth_1
    type = external_oauth
    enabled = true
    external_oauth_any_role_mode = 'ENABLE'
    ...
Copy

将次要角色与 External OAuth 结合使用

主要角色所需的范围在外部令牌中传递：用户的默认角色 (session:role-any) 或授予用户的特定角色 (session:role:<role_name>)。

默认情况下，Snowflake 不会 激活会话中用户（即 DEFAULT_SECONDARY_ROLES）的默认 次要角色。

要激活会话中用户的默认次要角色，并允许在使用 External OAuth 时执行 USE SECONDARY ROLES 命令，请完成以下步骤：

  1. 配置连接的安全集成。在创建安全集成（使用 CREATE SECURITY INTEGRATION）或更高版本（使用 ALTER SECURITY INTEGRATION）时，将 EXTERNAL_OAUTH_ANY_ROLE_MODE 参数值设置为 ENABLE 或 ENABLE_FOR_PRIVILEGE。

  2. 配置授权服务器以在令牌的范围属性中传递 session:role-any 的静态值。有关范围参数的更多信息，请参阅 External OAuth 概览。

将 Client Redirect与 External OAuth 结合使用

Snowflake 支持将 Client Redirect 与 External OAuth 结合使用，包括将 Client Redirect 和 OAuth 与支持的 Snowflake 客户端结合使用。

有关更多信息，请参阅 重定向客户端连接。

将网络策略与 External OAuth 结合使用

目前，网络策略无法添加到您的 External OAuth 安全集成。但是，您仍然可以实施广泛应用于整个 Snowflake 账户的网络策略。

如果您的用例需要特定于 OAuth 安全集成的网络策略，请使用 Snowflake OAuth。这种方法允许 Snowflake OAuth 网络策略与可能适用于 Snowflake 账户的其他网络策略不同。

有关更多信息，请参阅 网络策略。

将副本与 External OAuth 结合使用

功能支持的区域

此功能在中华人民共和国不可用。

Snowflake 支持 External OAuth 安全集成从源账户到目标账户的复制和故障切换/故障回复。

有关详细信息，请参阅 跨多个账户复制安全集成和网络策略。

测试过程

在使用 Okta 作为授权服务器测试 OAuth 的情况下，您必须：

  1. 验证测试用户是否存在于 Okta 并有一个密码。

  2. 验证 Snowflake 中是否存在测试用户，且其 login_name 属性值设置为 <OKTA_USER_USERNAME>

  3. 注册 OAuth 客户端。

  4. 允许 OAuth 客户端向 Okta 令牌端点发出 POST 请求，如下所示：

    • 授予类型设置为资源所有者

    • HTTP 基本授权标头包含 clientID 和密钥

    • FORM 数据包含用户的用户名和密码

    • 包括范围

示例命令请求 Analyst，并假定已在 Okta > OAuth App Resource 中定义了 session:role:analyst。

以下是使用 cURL 获取访问令牌的示例。

curl -X POST -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" \
  --user <OAUTH_CLIENT_ID>:<OAUTH_CLIENT_SECRET> \
  --data-urlencode "username=<OKTA_USER_USERNAME>" \
  --data-urlencode "password=<OKTA_USER_PASSWORD>" \
  --data-urlencode "grant_type=password" \
  --data-urlencode "scope=session:role:analyst" \
  <OKTA_OAUTH_TOKEN_ENDPOINT>
Copy

通过 External OAuth 连接到 Snowflake

配置安全集成并获取访问令牌后，您可以使用以下方法之一连接到 Snowflake：

请注意以下事项：

  • 必须将 authenticator 参数设置为 oauth，将 token 参数设置为 external_oauth_access_token。

  • 将 token 值作为 URL 查询参数传递时，必须对 token 值进行 URL 编码。

  • 将 token 值传递给属性对象（例如 JDBC 驱动程序）时，无需进行任何修改。

例如，如果使用 Python Connector，请设置连接字符串，如下所示。

ctx = snowflake.connector.connect(
   user="<username>",
   host="<hostname>",
   account="<account_identifier>",
   authenticator="oauth",
   token="<external_oauth_access_token>",
   warehouse="test_warehouse",
   database="test_db",
   schema="test_schema"
)
Copy

您现在可以使用 External OAuth 安全连接到 Snowflake。

语言: 中文