为 Snowflake 配置外部 OAuth：客户端凭据流程

适用于： Tableau Cloud, Tableau Desktop, Tableau Server

OAuth 客户端凭据身份验证支持与 Snowflake 的计算机对计算机连接

无需用户交互。此方法非常适合于：

用于自动数据刷新的服务帐户
计划的数据提取作业
CI/CD 管道
需要嵌入式凭据的已发布数据源

与标准 OAuth（使用授权代码流程）不同，客户端凭据流程不会

提示用户登录。相反，Tableau 使用客户端 ID 和密文直接向身份提供程序

进行身份验证。

注意：客户端凭据流程需要 Snowflake 的外部 OAuth 功能以及受支持的身份提供程序。这与 Snowflake 的本机 OAuth 不同。

开始之前

若要将 OAuth 客户端凭据与 Snowflake 结合使用，您需要：

要求	描述
身份提供程序	针对客户端凭据授予配置的 Okta、Azure AD 或 Ping Federate
Snowflake 帐户	具有 ACCOUNTADMIN 访问权限的 Enterprise Edition 或更高版本
OAuth 应用程序	API 服务 (Okta)、应用程序注册 (Azure AD) 或同等服务
自定义范围	Snowflake 角色分配的范围（例如“session:role:SYSADMIN”）

配置您的身份提供程序

以下步骤使用 Okta 作为示例。对于其他提供程序，请查阅其文档以了解客户端凭据配置。

步骤 1：创建 API 服务应用程序

登录到 Okta 管理员控制台。
转到 **“Applications”（应用程序）>“Applications”（应用程序）。
选择 **“Create App Integration”（创建应用程序集成）。
选择 **“API Services”（API 服务）**，并选择 **“Next”（下一步）。
输入应用程序名称（例如，snowflake-tableau-service）。
选择“Save”（保存）。
复制“Client ID”（客户端 ID）和“Client Secret”（客户端密文）。稍后您将需要这些值。

步骤 2：禁用 DPoP（如果已启用）

必须为客户端凭据流程禁用所有权证明演示 (DPoP)。

在您的应用程序设置中，转到“General”（常规）>“Client Credentials”（客户端凭据）。
清除“Require Demonstrating Proof of Possession (DPoP) header in token requests”（在令牌请求中需要所有权证明演示 (DPoP) 标头）复选框。
选择“Save”（保存）。

步骤 3：添加自定义范围

Snowflake 需要自定义范围以将角色分配给经过身份验证的会话。

转到“Security”（安全性）>“API”>“Authorization Servers”（授权服务器）。
选择默认授权服务器（或您的自定义服务器）。
选择“Scopes”（范围）选项卡，然后选择“Add Scope”（添加范围）。
添加以下范围：
范围名称描述
snowflake Snowflake 的一般访问范围
session:role:SYSADMIN 分配 SYSADMIN 角色（根据您的角色进行调整）
注意：为服务帐户需要的任何其他角色创建其他范围。

范围名称	描述
snowflake	Snowflake 的一般访问范围
session:role:SYSADMIN	分配 SYSADMIN 角色（根据您的角色进行调整）

步骤 4：配置访问策略

选择“Access Policies”（访问策略）选项卡。
选择现有策略或创建新策略。
添加具有以下设置的规则：
- “Grant type”（授予类型）：客户端凭据
- “Scopes”（范围）：任何范围（或选择特定范围）
选择“Create Rule”（创建规则）或“Save”（保存）。

配置 Snowflake

在 Snowflake 中以 ACCOUNTADMIN 身份运行以下 SQL 语句。将占位符值替换为您的配置。

步骤 1：创建外部 OAuth 集成

USE ROLE ACCOUNTADMIN;

CREATE OR REPLACE SECURITY INTEGRATION okta_oauth_integration
  TYPE = EXTERNAL_OAUTH
  ENABLED = TRUE
  EXTERNAL_OAUTH_TYPE = OKTA
  EXTERNAL_OAUTH_ISSUER = 'https://<your-okta-domain>.okta.com/oauth2/default'
  EXTERNAL_OAUTH_JWS_KEYS_URL = 'https://<your-okta-domain>.okta.com/oauth2/
default/v1/keys'
  EXTERNAL_OAUTH_TOKEN_USER_MAPPING_CLAIM = 'sub'
  EXTERNAL_OAUTH_SNOWFLAKE_USER_MAPPING_ATTRIBUTE = 'login_name'
  EXTERNAL_OAUTH_AUDIENCE_LIST = ('api://default', 'snowflake')
EXTERNAL_OAUTH_ANY_ROLE_MODE = 'ENABLE';

参数	描述
`EXTERNAL_OAUTH_TYPE`	您的身份提供程序：`OKTA`、`AZURE` 或 `PING_FEDERATE`
`EXTERNAL_OAUTH_ISSUER`	授权服务器中的颁发者 URL
`EXTERNAL_OAUTH_JWS_KEYS_URL`	用于令牌验证的 JWKS 端点
`EXTERNAL_OAUTH_TOKEN_USER_MAPPING_CLA IM`	标识用户的 JWT 声明。对于 Okta，使用 `sub`。
`EXTERNAL_OAUTH_ANY_ROLE_MODE`	设置为 `ENABLE` 以允许通过范围进行角色分配

步骤 2：创建服务用户

创建一个 Snowflake 用户，其 LOGIN_NAME 与 OAuth 客户端 ID 匹配。

CREATE USER IF NOT EXISTS service_account_user
  LOGIN_NAME = '<your-okta-client-id>'
  DISPLAY_NAME = 'OAuth Service Account'
  MUST_CHANGE_PASSWORD = FALSE
  DISABLED = FALSE;

-- Grant role to the service user
GRANT ROLE SYSADMIN TO USER service_account_user;

-- Set the default role
ALTER USER service_account_user SET DEFAULT_ROLE = 'SYSADMIN';

-- Grant warehouse access
GRANT USAGE ON WAREHOUSE <your-warehouse> TO USER service_account_user;

-- Grant database and schema access
GRANT USAGE ON DATABASE <your-database> TO USER service_account_user;
GRANT USAGE ON SCHEMA <your-database>.<your-schema> TO USER
service_account_user;
GRANT SELECT ON ALL TABLES IN SCHEMA <your-database>.<your-schema> TO USER
service_account_user;

重要信息：LOGIN_NAME 必须完全匹配 OAuth 令牌中的 sub 声明。对于 Okta API 服务应用程序，这是客户端 ID。

通过 Tableau Desktop 连接

在 Tableau Desktop 中，选择“连接”>“Snowflake”。
输入您的连接详细信息：
字段值
服务器您的 Snowflake 帐户 URL（例如 account.snowflakecomputing.com）
角色要使用的角色（例如，SYSADMIN）
仓库您的 Snowflake 仓库
身份验证 OAuth 客户端凭据

字段	值
服务器	您的 Snowflake 帐户 URL（例如 `account.snowflakecomputing.com`）
角色	要使用的角色（例如，`SYSADMIN`）
仓库	您的 Snowflake 仓库
身份验证	OAuth 客户端凭据

输入 OAuth 配置：

字段	值
OAuth 令牌请求 URL	`https://<your-okta-domain>.okta.com/oauth2/default/ v1/token`
用户名	您的 OAuth 客户端 ID
密码	您的 OAuth 客户端密文
OAuth 范围	`snowflake session:role:SYSADMIN`

注意：OAuth 范围必须包括您为角色分配配置的任何自定义范围。

选择“登录”。

发布到 Tableau Cloud 或 Tableau Server

发布使用 OAuth 客户端凭据的工作簿或数据源时：

在“发布”对话框中，选择“数据源”旁边的“编辑”。
对于“身份验证”，选择“嵌入式密码”。
客户端凭据嵌入在已发布的内容中。

重要信息：与标准 OAuth 不同，客户端凭据被视为嵌入式密码。访问已发布内容的用户使用服务帐户凭据，而不是他们自己的身份。

凭据轮换

当您的 OAuth 客户端密文轮换时，请在 Tableau Cloud 上更新嵌入式凭据：

登录 Tableau Cloud。
导航到已发布数据源。
选择“连接”。
使用新的客户端密文更新连接。

对于自动轮换，请使用 Tableau REST API 以编程方式更新连接凭据。

常见问题

何时应使用 OAuth 客户端凭据，而不是标准 OAuth？

当您需要无人值守的计算机对计算机身份验证时，请使用客户端凭据。标准

OAuth 需要用户交互来进行初始登录和定期重新身份验证。客户端凭据

使用服务帐户身份，并且不需要用户交互。

我可以将客户端凭据与 Snowflake 的本机 OAuth 一起使用吗？

不可以。Snowflake 的本机 OAuth 仅支持授权代码流程。客户端凭据需要具有受支持的身份提供程序（Okta、Azure AD 或 Ping Federate）的外部 OAuth。

如何处理已发布内容的密文轮换？

当您的 OAuth 客户端密文轮换时，您必须更新 Tableau Cloud 中的嵌入式凭据。您可以通过 Tableau Cloud UI 手动执行此操作，也可以使用 Tableau REST API 以编程方式执行此操作。考虑在密文轮换工作流中自动执行此过程。

为什么即使启用了 EXTERNAL_OAUTH_ANY_ROLE_MODE，我的连接也会失败并出现角色错误？

Snowflake 需要 OAuth 令牌中的角色信息。将自定义范围（例如 session:role:SYSADMIN）添加到您的授权服务器，并在从 Tableau 连接时将其包括在“OAuth 范围”字段中。

疑难解答

错误消息	原因	解决方案
“用户不存在或未授权”	Snowflake 用户 `LOGIN_NAME` 与 OAuth 客户端 ID 不匹配	设置用户的 `LOGIN_NAME` 以匹配 `sub` 声明（Okta 的客户端 ID）
“访问令牌中未列出请求的角色”	令牌中缺少角色范围	将 `session:role:<ROLE>` 范围添加到您的授权服务器，并将其包含在 OAuth 范围中
“无效的 DPoP 证明”	在 Okta 中启用了 DPoP	在 Okta 应用中禁用“Require Demonstrating Proof of Possession (DPoP)”（需要所有权证明演示 (DPoP)）
“范围无效”	未配置自定义范围	将所需的范围添加到您的授权服务器；不包括 `openid`
令牌验证失败	JWKS URL 或颁发者不正确	验证 `EXTERNAL_OAUTH_JWS_KEYS _URL` 和 `EXTERNAL_OAUTH_ISSUER` 是否与您的授权服务器匹配

另请参见

在 Tableau Server 上为 Snowflake 连接配置 OAuth(链接在新窗口中打开) - 了解 Snowflake 的标准 OAuth 身份验证。
外部 OAuth 安全集成(链接在新窗口中打开) - 用于配置外部 OAuth 提供程序的 Snowflake 文档。
Okta 客户端凭据流程(链接在新窗口中打开) - 用于实现客户端凭据的 Okta 文档。
更新数据源连接(链接在新窗口中打开) - 有关凭据更新的 Tableau REST API 参考。

回到顶部

感谢您的反馈!

您的反馈已成功提交。谢谢!

Tableau Desktop 和 Web 制作帮助