在本地应用程序中使用 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.

管理员可以修改 SNOWFLAKE$LOCAL_APPLICATION 安全集成的参数以调整其行为，例如指定 OAuth 访问令牌和刷新令牌的有效期。

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

  • Unlike user-created Snowflake OAuth integrations, in-role session switching is supported.

  • 它可以直接替代当前仅使用密码进行用户身份验证的应用程序。Snowflake 正在 :doc:` 弃用单因素密码 </user-guide/security-mfa-rollout>`，因此用于本地应用程序的 Snowflake OAuth 提供了一种无需大量设置即可使用更安全身份验证方式的方案。

备注

SNOWFLAKE$LOCAL_APPLICATION 安全集成正在逐步推广到所有账户。要确认您的账户中是否存在此内置集成，请运行以下命令：

SHOW SECURITY INTEGRATIONS LIKE 'SNOWFLAKE$LOCAL_APPLICATION';
Copy

配置 Snowflake OAuth 集成

内置 SNOWFLAKE$LOCAL_APPLICATION 安全集成归系统所有，但安全管理员（即被授予 SECURITYADMIN 系统角色的用户）可以进行配置。

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

参数

描述

ENABLED

控制是否启用该集成。如果禁用该集成，本地应用程序必须使用其他身份验证方法。

OAUTH_ISSUE_REFRESH_TOKENS

Controls whether the authorization server issues refresh tokens.

OAUTH_REFRESH_TOKEN_VALIDITY

设置刷新令牌的有效期。

OAUTH_SINGLE_USE_REFRESH_TOKENS_REQUIRED

Controls whether the authorization server issues single-use refresh tokens.

OAUTH_ACCESS_TOKEN_VALIDITY

设置访问令牌的有效期。

For example, to modify the built-in security integration so that the authorization server starts issuing single-use refresh tokens, run the following commands:

USE ROLE SECURITYADMIN;

ALTER SECURITY INTEGRATION SNOWFLAKE$LOCAL_APPLICATION
  SET OAUTH_SINGLE_USE_REFRESH_TOKENS_REQUIRED = TRUE;
Copy

有关设置这些参数的更多信息，请参阅 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

This section provides the details a developer needs to configure a local application to authenticate with Snowflake OAuth. The following types of local applications can authenticate by using the built-in integration:

使用 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.

先决条件

With Snowflake OAuth for local applications, the Snowflake client must be able to open the user's web browser. For this reason, both the Snowflake client and the local application that uses it must be installed on the user's computer. Snowflake OAuth for local applications doesn't work if the Snowflake client is used by code that runs on a server.

支持的客户端

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

客户端

所需的最低版本

所需配置

.NET

v4.8.0

在连接字符串中设置 authenticator=oauth_authorization_code。

Go

v1.14.1

在连接配置中设置 authenticator=oauth_authorization_code。

JDBC

v3.24.1

在驱动程序的连接字符串中设置 authenticator=oauth_authorization_code。

Node.js

v2.1.0

在连接选项中设置 authenticator: 'oauth_authorization_code'。

ODBC

v3.9.0

  • 对于 Linux 和 macOS，在 odbc.ini 文件中设置 authenticator=oauth_authorization_code。

  • 对于 Windows，请在 ODBC Data Source Administrator 工具中编辑 Snowflake 的 DSN，并将身份验证器设置为 oauth_authorization_code。

Python

v3.16.0

将 AUTHENTICATOR=OAUTH_AUTHORIZATION_CODE 传递给 snowflake.connector.connect() 函数。

Snowflake CLI

v3.8.1

在连接定义中添加 authenticator = "OAUTH_AUTHORIZATION_CODE" 选项。

SnowSQL

v1.4.0

在配置文件中添加 authenticator = "OAUTH_AUTHORIZATION_CODE" 参数。

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

Your local application can use Snowflake OAuth by making requests to the authorization endpoint and token endpoint of Snowflake as the authorization server. You don't need to use a Snowflake client. The application sends a request to Snowflake's authorization endpoint to authenticate the user and receive an authorization code, and then sends a request to the token endpoint to exchange that code for an access token.

有关向 Snowflake 的授权端点和令牌端点发出 REST 请求的更多信息，请参阅 调用 OAuth 端点。

请求要求

您的应用程序向授权端点和令牌端点发出的 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.

  • 对授权端点和令牌端点的请求必须实现代码交换验证 (PKCE)。有关更多信息，请参阅 代码交换证明密钥。

  • 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:

    • 如果您在请求头中发送客户端凭据，则客户端 ID 必须是 LOCAL_APPLICATION，客户端密钥必须是 LOCAL_APPLICATION。

    • 如果您在 POST 正文中发送客户端凭据，则客户端 ID 必须是 LOCAL_APPLICATION。内置集成会将本地应用程序配置为公共客户端，因此如果您在 POST 正文中将客户端 ID 设置为 client_id=LOCAL_APPLICATION，则无需提供客户端密钥。

使用说明

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.

语言: 中文