为 External OAuth 配置 Microsoft Azure AD¶

确定 Azure AD 中的 OAuth 流¶

Azure AD 支持两种不同的 OAuth 流，在其中 OAuth 客户端可以获得访问令牌。

1. 授权服务器可以代表用户为 OAuth 客户端授予访问令牌。

2. 授权服务器可以为 OAuth 客户端授予 OAuth 客户端本身的访问令牌。

在第一个流中，访问令牌中的标识引用用户。在第二个流中，访问令牌中的标识引用 OAuth 客户端。

Microsoft Azure AD 不允许两种 OAuth 流具有相同的角色格式。使用的角色格式取决于使用中的 OAuth 流。确定要使用的 OAuth 流之后，请执行以下操作：

• 完成 在 Azure AD 中配置 OAuth 资源 中的第 10 个或第 11 个子步骤。

• 完成 在 Azure AD 中创建 OAuth 客户端 中的第 13 个或第 14 个子步骤。

在 Azure AD 中配置 OAuth 资源¶

1. 导航至 Microsoft Azure Portal (https://portal.azure.com) 并进行身份验证。

2. 导航至 Azure AD。

3. 点击 App Registrations。

4. 点击 New Registration。

5. 输入 Snowflake OAuth Resource 或类似值作为 Name。

6. 确认 Supported account types 已设置为 Single Tenant。

7. 点击 Register。

8. 点击 Expose an API。

9. 点击 Application ID URI 旁边的 Set 链接，以设置 Application ID URI。

   重要

   Application ID URI 在组织的目录中必须唯一，例如 https://your.company.com/4d2a8c2b-a5f4-4b86-93ca-294185f45f2e。此值将在后续配置步骤中作为 <SNOWFLAKE_APPLICATION_ID_URI> 引用。

   如需关于获取 Application ID URI 的帮助，请联系您的内部 Microsoft Azure AD 管理员。

   如果 Application ID URI 未使用，则必须使用 Snowflake Account URL（即 <account_identifier>.snowflakecomputing.cn）创建与受众的安全集成。有关更多信息，请参阅：

   • 在 Snowflake 中创建安全集成 中的受众集成。

   • 账户标识符。

10. 要将 Snowflake 角色添加为 OAuth 流（程序化客户端在其中代表用户操作）的 OAuth 作用域，请点击 Add a scope，添加代表 Snowflake 角色的作用域。

    • 按照带 session:scope: 前缀的 Snowflake 角色名称的方式输入作用域。例如，对于 Snowflake 分析师角色，请输入 session:scope:analyst。

    • 选择同意者。

    • 输入作用域的 display name （例如：账户管理员）。

    • 输入作用域的 description （例如：可以管理 Snowflake 账户）。

    • 点击 Add Scope。

11. 要将 Snowflake 角色添加为 OAuth 流（程序化客户端在其中为自身请求访问令牌）的角色：

    • 点击 Manifest。

    • 找到 appRoles 元素。

    • 输入 App Role 并进行以下设置。

      设置	描述
      allowedMemberTypes	应用程序。
      描述	角色描述。
      displayName	便于用户查看的友好型名称。
      id	唯一 ID。您可以从 PowerShell 中使用 [System.Guid]::NewGuid() 函数，生成唯一 ID（如果需要）。
      isEnabled	设置为 true。
      lang	语言。设置为 null。
      origin	设置为 Application。
      value	设置为带 session:role: 前缀的 Snowflake 角色名称。. 对于分析师角色，请输入 session:role:analyst。

      App Role 显示如下。

      "appRoles":[
          {
              "allowedMemberTypes": [ "Application" ],
              "description": "Account Administrator.",
              "displayName": "Account Admin",
              "id": "3ea51f40-2ad7-4e79-aa18-12c45156dc6a",
              "isEnabled": true,
              "lang": null,
              "origin": "Application",
              "value": "session:role:analyst"
          }
      ]
      

      Copy

12. 点击 Save。

在 Azure AD 中创建 OAuth 客户端¶

1. 导航至 Microsoft Azure Portal (https://portal.azure.com) 并进行身份验证。

2. 导航至 Azure AD。

3. 点击 App Registrations。

4. 点击 New Registration。

5. 输入客户端的名称，例如 Snowflake OAuth Client。

6. 确认支持的账户类型已设置为 Single Tenant。

7. 点击 Register。

8. 在 Overview 部分中，从 Application (client) ID 字段中复制 ClientID。这将在以下步骤中称为 <OAUTH_CLIENT_ID>。

9. 点击 Certificates & secrets，然后点击 New client secret。

10. 添加密钥的描述。

11. 选择 never expire。出于测试目的，请选择永不过期的密钥。

12. 点击 Add。复制密钥。这将在以下步骤中称为 :code:` <OAUTH_CLIENT_SECRET>`。

13. 对于代表用户请求访问令牌的程序化客户端，请按如下方式配置应用程序的委派权限。

    • 点击 API Permissions。

    • 点击 Add Permission。

    • 点击 My APIs。

    • 点击您在 在 Azure AD 中配置 OAuth 资源 中创建的 Snowflake OAuth Resource。

    • 点击 Delegated Permissions 框。

    • 检查与您希望授予该客户端的应用程序中定义的作用域相关的权限。

    • 点击 Add Permissions。

    • 点击 Grant Admin Consent 按钮，为客户端授予权限。请注意，出于测试目的，权限会这样配置。但在生产环境中，不建议以这种方式授予权限。

    • 点击 Yes。

14. 对于将为自己请求访问令牌的程序化客户端，请如下配置 API permissions for Applications。

    • 点击 API Permissions。

    • 点击 Add Permission。

    • 点击 My APIs。

    • 点击您在 在 Azure AD 中配置 OAuth 资源 中创建的 Snowflake OAuth Resource。

    • 点击 Application Permissions。

    • 检查与您希望授予此客户端的应用程序 Manifest 中手动定义的角色相关的 Permission。

    • 点击 Add Permissions。

    • 点击 Grant Admin Consent 按钮，为客户端授予权限。请注意，出于测试目的，权限会这样配置。但在生产环境中，不建议以这种方式授予权限。

    • 点击 Yes。

收集 Snowflake 的 Azure AD 信息¶

1. 导航至 Microsoft Azure Portal (https://portal.azure.com) 并进行身份验证。

2. 导航至 Azure AD。

3. 点击 App Registrations。

4. 点击您在 在 Azure AD 中配置 OAuth 资源 中创建的 Snowflake OAuth Resource。

5. 在 Overview 界面中点击 Endpoints。

6. 在右侧，复制 OAuth 2.0 token endpoint (v2) 并记录 OpenID Connect metadata 和 Federation Connect metadata 的 URLs。

   • OAuth 2.0 token endpoint (v2) 将在以下配置步骤中称为 <AZURE_AD_OAUTH_TOKEN_ENDPOINT>。端点应该类似于 https://login.microsoftonline.com/90288a9b-97df-4c6d-b025-95713f21cef9/oauth2/v2.0/token。

   • 对于 OpenID Connect metadata，请在新的浏览器窗口中打开。

     • 找到 "jwks_uri" 参数并复制其值。

     • 该参数值将在以下配置步骤中称为 <AZURE_AD_JWS_KEY_ENDPOINT>。端点应该类似于 https://login.microsoftonline.com/90288a9b-97df-4c6d-b025-95713f21cef9/discovery/v2.0/keys。

   • 对于 Federation metadata document，请在新的浏览器窗口中打开 URL。

     • 在 XML Root Element 中找到 "entityID" 参数并复制其值。

     • 该参数值将在以下配置步骤中称为 <AZURE_AD_ISSUER>。entityID 值应该类似于 https://sts.windows.net/90288a9b-97df-4c6d-b025-95713f21cef9/。

在 Snowflake 中创建安全集成¶

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

选择最能满足您的用例和配置需求的安全集成。如果您的集成仅基于上述配置，请使用第一个安全集成。有关更多信息，请参阅 CREATE SECURITY INTEGRATION。

为 Azure AD 创建安全集成

create security integration external_oauth_azure_1
    type = external_oauth
    enabled = true
    external_oauth_type = azure
    external_oauth_issuer = '<AZURE_AD_ISSUER>'
    external_oauth_jws_keys_url = '<AZURE_AD_JWS_KEY_ENDPOINT>'
    external_oauth_token_user_mapping_claim = 'upn'
    external_oauth_snowflake_user_mapping_attribute = 'login_name';

Copy

与受众创建安全集成

安全集成的 external_oauth_audience_list 参数必须与您在配置 Azure AD 时指定的 Application ID URI 匹配。

create security integration external_oauth_azure_2
    type = external_oauth
    enabled = true
    external_oauth_type = azure
    external_oauth_issuer = '<AZURE_AD_ISSUER>'
    external_oauth_jws_keys_url = '<AZURE_AD_JWS_KEY_ENDPOINT>'
    external_oauth_audience_list = ('<SNOWFLAKE_APPLICATION_ID_URI>')
    external_oauth_token_user_mapping_claim = 'upn'
    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'
    ...

将次要角色与 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 安全集成从源账户到目标账户的复制和故障切换/故障回复。

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