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

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

Snowflake OAuth 通过创建 安全集成 实现 OAuth 授权码流程，该集成定义了 Snowflake 作为 OAuth 授权服务器与代表用户进行身份验证的应用程序之间的接口。Snowflake OAuth 是一种强身份验证选项，因为应用程序无需存储或管理密钥，同时也无需配置第三方身份提供商（如 External OAuth）。

为了简化本地应用程序使用 Snowflake OAuth 进行身份验证的流程，您的账户提供了一个名为 SNOWFLAKE$LOCAL_APPLICATION 的内置安全集成。由于该安全集成已存在，如果本地应用程序使用 Snowflake 客户端（如 Python 驱动程序或 Snowflake CLI），则可通过设置客户端的属性或参数来对 Snowflake 进行身份验证。无需进行其他设置。该内置集成还简化了直接调用 OAuth 端点（而非使用 Snowflake 客户端）的本地应用程序的配置流程。

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

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

与用户创建的 Snowflake OAuth 集成不同，它支持角色内会话切换。
它可以直接替代当前仅使用密码进行用户身份验证的应用程序。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`	控制授权服务器是否发放刷新令牌。
`OAUTH_REFRESH_TOKEN_VALIDITY`	设置刷新令牌的有效期。
`OAUTH_SINGLE_USE_REFRESH_TOKENS_REQUIRED`	控制授权服务器是否发放一次性刷新令牌。
`OAUTH_ACCESS_TOKEN_VALIDITY`	设置访问令牌的有效期。

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

USE ROLE SECURITYADMIN;

ALTER SECURITY INTEGRATION SNOWFLAKE$LOCAL_APPLICATION
  SET OAUTH_SINGLE_USE_REFRESH_TOKENS_REQUIRED = TRUE;

Copy

有关设置这些参数的更多信息，请参阅 ALTER SECURITY INTEGRATION。

控制登录频率¶

在 OAUTH_ISSUE_REFRESH_TOKENS = TRUE 时，应用程序可以使用刷新令牌来获取新的访问令牌，而无需提示用户再次登录。仅当刷新令牌在由 OAUTH_REFRESH_TOKEN_VALIDITY 参数指定的持续时间后过期时，用户才需要重新进行身份验证。

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

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

使用 Snowflake 客户端（如 Python 驱动程序或 Snowflake CLI）的本地应用程序。请参阅使用 Snowflake 客户端的应用程序。
无需使用 Snowflake 客户端，直接向 OAuth 授权端点和令牌端点发出 REST 请求的本地应用程序。请参阅直接调用 OAuth 端点的应用程序。

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

当本地应用程序使用 Snowflake 客户端（如 Snowflake ODBC 驱动程序）时，可以通过将 authenticator 连接选项设置为 oauth_authorization_code 来使用 Snowflake OAuth 进行身份验证。不需要额外的开发工作。

先决条件¶

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

支持的客户端¶

您的本地应用程序可以使用以下 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 端点的应用程序¶

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

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

请求要求¶

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

对授权端点的请求中的重定向 URL 必须为 http://127.0.0.1[:port][/path]。也就是说，您的本地应用程序必须在环回地址上监听 Snowflake（作为授权服务器）返回的授权代码。
对授权端点和令牌端点的请求必须实现代码交换验证 (PKCE)。有关更多信息，请参阅代码交换证明密钥。
调用令牌端点以使用授权代码交换访问令牌时，应用程序必须提供正确的客户端 ID 和客户端密钥。具体要求根据您选择发送这些客户端凭据的方式略有差异：
- 如果您在请求头中发送客户端凭据，则客户端 ID 必须是 LOCAL_APPLICATION，客户端密钥必须是 LOCAL_APPLICATION。
- 如果您在 POST 正文中发送客户端凭据，则客户端 ID 必须是 LOCAL_APPLICATION。内置集成会将本地应用程序配置为公共客户端，因此如果您在 POST 正文中将客户端 ID 设置为 client_id=LOCAL_APPLICATION，则无需提供客户端密钥。

使用说明¶

每个账户都有一个 SNOWFLAKE$LOCAL_APPLICATION 集成，因此不会复制此集成。内置集成的配置对每个账户都是唯一的。