在本地应用程序中使用 Snowflake OAuth¶

本主题介绍适用于本地应用程序（包括桌面应用程序和本地脚本）的推荐身份验证方法。

Snowflake OAuth is implemented by creating a security integration that defines an interface between Snowflake as the OAuth authorization server and the application that is authenticating on behalf of a user by using the OAuth authorization code flow. Snowflake OAuth is a strong authentication option because the application doesn’t have to store or manage secrets, and you don’t have to configure a third-party identity provider like External OAuth.

To simplify how a local application uses Snowflake OAuth to authenticate, your account has a built-in security integration called SNOWFLAKE$LOCAL_APPLICATION. Because the security integration already exists, if a local application uses a Snowflake client like the Python driver or Snowflake CLI, the application can authenticate to Snowflake by setting a property or parameter of the client. No further set up is required. The built-in integration also simplifies the setup for local applications that call the OAuth endpoints directly rather than use a Snowflake client.

An administrator can change the parameters of the SNOWFLAKE$LOCAL_APPLICATION integration to adjust its behavior, such as specifying how long OAuth access tokens and refresh tokens are valid.

用于本地应用程序的 Snowflake OAuth 具有以下额外优势：

• 与用户创建的 Snowflake OAuth 集成不同，它 支持 角色内会话切换。
• It is a straightforward replacement for applications that are currently using passwords only to authenticate users. Snowflake is deprecating single-factor passwords, so Snowflake OAuth for local applications provides a path to using a more secure form of authentication without requiring a lot of set up.

SHOW SECURITY INTEGRATIONS LIKE 'SNOWFLAKE$LOCAL_APPLICATION';

配置 Snowflake OAuth 集成¶

The built-in SNOWFLAKE$LOCAL_APPLICATION security integration is owned by the system but can be configured by security administrators (that is, users granted the SECURITYADMIN system role).

安全管理员可以配置该安全集成的以下参数：

例如，要修改内置安全集成，使授权服务器开始发放一次性刷新令牌，请运行以下命令：

USE ROLE SECURITYADMIN;

ALTER SECURITY INTEGRATION SNOWFLAKE$LOCAL_APPLICATION
  SET OAUTH_SINGLE_USE_REFRESH_TOKENS_REQUIRED = TRUE;

For more information about setting these parameters, see ALTER SECURITY INTEGRATION.

控制登录频率

When OAUTH_ISSUE_REFRESH_TOKENS = TRUE, applications can use refresh tokens to obtain new access tokens without prompting users to log in again. Users only need to re-authenticate when the refresh token expires after the duration that is specified by the OAUTH_REFRESH_TOKEN_VALIDITY parameter.

设置本地应用程序以使用 Snowflake OAuth¶

本部分提供开发者配置本地应用程序以使用 Snowflake OAuth 进行身份验证所需的详细信息。以下类型的本地应用程序可以使用内置集成进行身份验证：

• A local application that uses a Snowflake client like the Python driver or Snowflake CLI. See 使用 Snowflake 客户端的应用程序.
• A local application that makes REST requests to the OAuth authorization endpoint and token endpoint directly, without the use of a Snowflake client. See 直接调用 OAuth 端点的应用程序.

使用 Snowflake 客户端的应用程序¶

When a local application uses a Snowflake client like the Snowflake ODBC driver, it can authenticate with Snowflake OAuth by setting the authenticator connection option to oauth_authorization_code. Additional development work isn’t required.

先决条件

对于本地应用程序使用 Snowflake OAuth 的情况，Snowflake 客户端必须能够打开用户的 Web 浏览器。因此，Snowflake 客户端和使用该客户端的本地应用程序都必须安装在用户的计算机上。如果 Snowflake 客户端由运行在服务器上的代码使用，则本地应用程序的 Snowflake OAuth 功能将无法使用。

支持的客户端

您的本地应用程序可以使用以下 Snowflake 客户端，通过 Snowflake OAuth 对本地应用程序进行身份验证：

直接调用 OAuth 端点的应用程序¶

您的本地应用程序可以通过向 Snowflake（作为授权服务器）的授权端点和令牌端点发出请求来使用 Snowflake OAuth。您不需要使用 Snowflake 客户端。应用程序向 Snowflake 的授权端点发送请求，以对用户进行身份验证并接收授权代码，然后向令牌端点发送请求，将该代码交换为访问令牌。

For more information about making REST requests to Snowflake’s authorization and token endpoints, see Call the OAuth endpoints.

请求要求

您的应用程序向授权端点和令牌端点发出的 REST 请求必须符合以下要求：

• The redirect URL in the request to the authorization endpoint must be http://127.0.0.1[:port][/path]. That is, your local application must be listening on a loopback address for the authorization code that is returned by Snowflake as the authorization server.
• Requests to the authorization and token endpoints must implement Proof Key for Code Exchange (PKCE). For more information, see Proof key for code exchange.
• When calling the token endpoint to exchange an authorization code for an access token, the application must provide the proper client ID and client secret. This requirement varies slightly depending on how you choose to send these client credentials:
  • If you send client credentials in the request header, the client ID must be LOCAL_APPLICATION and the client secret must be LOCAL_APPLICATION.
  • If you send client credentials in the POST body, the client ID must be LOCAL_APPLICATION. The built-in integration configures the local application as a public client, so the client secret isn’t necessary if you provide the client ID as client_id=LOCAL_APPLICATION in the POST body.

Network policies for local applications¶

Network policy enforcement for the built-in SNOWFLAKE$LOCAL_APPLICATION integration differs from other Snowflake OAuth integrations. When a local application sends a token request, the user-level network policy is enforced with highest precedence, followed by the integration-level network policy, then the account-level network policy.

For general information about restricting network traffic for Snowflake OAuth, see Restricting network traffic for Snowflake OAuth.

使用说明

Every account has a SNOWFLAKE$LOCAL_APPLICATION integration, so this integration isn’t replicated. The configuration of the built-in integration is unique to each account.