External OAuth 概览

本主题教您如何配置使用 OAuth 2.0 访问 Snowflake 的 External OAuth 服务器。

External OAuth 集成了客户的 OAuth 2.0 服务器，提供无缝 SSO 体验，使外部客户端能够访问 Snowflake。

Snowflake 支持以下外部授权服务器、自定义客户端和合作伙伴应用程序：

After configuring your organization’s External OAuth server, which includes any necessary OAuth 2.0 Scopes (https://oauth.net/2/scope/) mapping to Snowflake roles, the user can connect to Snowflake securely and programmatically without having to enter any additional authentication or authorization factors or methods. The user’s access to Snowflake data is dependent on both their role and the role being integrated into the access token for the session. For more information, refer to Scopes (in this topic).

使用案例和优势

  1. Snowflake delegates the token issuance to a dedicated authorization server to ensure that the OAuth Client and user properly authenticate. The result is centralized management of tokens issued to Snowflake.
  2. Customers can integrate their policies for authentication (e.g. multi-factor, subnet, biometric) and authorization (e.g. no approval, manager approval required) into the authorization server. The result is greater security leading to more robust data protection by issuing challenges to the user. If the user doesn’t pass the policy challenge(s), the Snowflake session is not instantiated, and access to Snowflake data does not occur.
  3. For programmatic clients that can access Snowflake and users that only initiate their Snowflake sessions through External OAuth, no additional authentication configuration (i.e. set a password) is necessary in Snowflake. The result is that service accounts or users used exclusively for programmatic access will only ever be able to use Snowflake data when going through the External OAuth configured service.
  4. 客户端无需访问浏览器即可对 Snowflake 进行身份验证，便于与External OAuth 服务器集成。
  5. Snowflake 与 External OAuth 服务器的集成与云无关。
    • It does not matter whether the authorization server exists in a cloud provider’s cloud or if the authorization server is on-premises. The result is that customers have many options in terms of configuring the authorization server to interact with Snowflake.

常规工作流程

对于每个受支持的身份提供商，与 External OAuth 授权服务器相关的 OAuth 工作流程可总结如下。请注意，第一步仅发生一次，其余步骤在每次尝试访问 Snowflake 数据时发生。

workflow overview
  1. 在您的环境中配置 External OAuth 授权服务器，并在 Snowflake 中配置安全集成以建立信任。
  2. A user attempts to access Snowflake data through their business intelligence application, and the application attempts to verify the user.
  3. 通过验证后，授权服务器会向客户端应用程序发送一个 JSON Web 令牌（即 OAuth 令牌）。
  4. Snowflake 驱动程序将连接字符串与 OAuth 令牌一起传递给 Snowflake。
  5. Snowflake 对 OAuth 令牌进行验证。
  6. Snowflake 执行用户查找。
  7. 通过验证后，Snowflake 会根据用户的角色为其实例化一个会话，以便其访问 Snowflake 中的数据。

范围

授权服务器中的范围参数限制了访问令牌允许的操作和角色，以及用户在实例化 Snowflake 会话后可以访问的内容。

The ACCOUNTADMIN, GLOBALORGADMIN, ORGADMIN, and SECURITYADMIN roles are blocked by default. If it is necessary to use one or more of these roles, use the ALTER ACCOUNT command to set the EXTERNAL_OAUTH_ADD_PRIVILEGED_ROLES_TO_BLOCKED_LIST account parameter to FALSE.

  • 对于 Okta、PingFederate 和 Custom，请使用下表中的角色范围模式。
  • For Microsoft Entra ID, refer to Determine the OAuth flow in Microsoft Entra ID
  • If you do not want to manage Snowflake roles in your External OAuth server, pass the static value of SESSION:ROLE-ANY in the scope attribute of the token.

The following table summarizes External OAuth scopes. Note that if you do not define a scope, the connection attempt to Snowflake will fail.

Scope/Role Connection ParameterDescription
session:role-any

映射到 Snowflake 中的 ANY 角色。

如果用户在 Snowflake 中的默认角色是必需的，请使用此范围。

The external_oauth_any_role_mode security integration parameter must be configured in order to enable ANY role for a given External OAuth Provider. For configuration details, refer to the ANY role section in Okta, Microsoft Entra ID, PingFederate, or Custom.

Note that with a Power BI to Snowflake integration, a PowerBI user cannot switch roles using this scope.

session:role:custom_roleMaps to a custom Snowflake role. For example, if your custom role is ANALYST, your scope is session:role:analyst.
session:role:publicMaps to the PUBLIC Snowflake role.

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

Snowflake supports using secondary roles with External OAuth.

Snowflake OAuth 不支持在会话中将角色切换为辅助角色。

有关更多信息，请参阅：

配置 External OAuth 支持

Snowflake 支持使用支持 External OAuth 的合作伙伴应用程序和自定义客户端。

如果需要配置合作伙伴应用程序或自定义客户端，请参阅以下列表：

限制 External OAuth 的网络流量

You can associate a network policy with the External OAuth security integration to restrict network traffic from the client to Snowflake as the resource server. This network policy governs login requests and queries against Snowflake.

When you associate a network policy with the security integration, it overrides network policies associated with the user or the account. For more information, see Network policy precedence.

要将网络策略与 External OAuth 安全集成相关联，请在创建或更新集成时设置 NETWORK_POLICY 参数。例如：

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'
  NETWORK_POLICY = 'allow_private_ip_only';

错误代码

有关与 External OAuth 相关的错误代码的说明，请参阅下表：

错误代码错误描述
390318OAUTH_ACCESS_TOKEN_EXPIREDOAuth access token expired. {0}
390144JWT_TOKEN_INVALIDJWT 令牌无效。

故障排除

  • Use the SYSTEM$VERIFY_EXTERNAL_OAUTH_TOKEN function to determine whether your External OAuth access token is valid or needs to be regenerated.
  • If you encounter an error message associated with a failed External OAuth login attempt, and the error message has a UUID, you can ask an administrator that has a MONITOR privilege assigned to their role to use the UUID from the error message to get a more detailed description of the error using the SYSTEM$GET_LOGIN_FAILURE_DETAILS function.