用于身份验证的编程访问令牌

您可以使用编程访问令牌对以下 Snowflake 端点进行身份验证：

备注

尚不支持使用编程访问令牌对 Snowpark Container Services 端点进行身份验证。

您也可以在以下情况下使用 编程访问令牌 来代替密码：

您可以为人类用户（TYPE=PERSON 用户）和服务用户（TYPE=SERVICE 用户）生成编程访问令牌。

先决条件

您必须满足以下先决条件才能生成和使用编程访问令牌：

网络策略要求

默认情况下，用户必须遵守具有一个或多个 网络规则 的 网络策略 才能生成或使用编程访问令牌：

  • 对于服务用户（其中用户 TYPE=SERVICE），只有当用户受网络策略的约束时，您才能生成或使用令牌。

    此先决条件将令牌的使用限制为来自一组特定地址或网络标识符的请求。

  • 对于人类用户（其中用户 TYPE=PERSON），即使用户不受网络策略的约束，您也可以生成令牌，但是用户必须遵守网络策略才能使用此令牌进行身份验证。

    如果不受网络策略约束的人类用户需要使用编程访问令牌进行身份验证，您可以暂时绕过网络策略要求，但我们不建议这样做。请参阅 生成编程访问令牌。

    备注

    用户无法绕过网络策略本身。

可以为 账户中的所有用户 或 特定用户 激活网络策略。

要更改此要求，请创建或修改指定编程访问令牌策略的 身份验证策略。

执行 CREATE AUTHENTICATION POLICY 或 ALTER AUTHENTICATION POLICY 命令。在 PAT_POLICY 子句中，将 NETWORK_POLICY_EVALUATION 设为以下值之一：

:code:`ENFORCED_REQUIRED`（默认行为）

用户必须遵守网络策略才能生成和使用编程访问令牌。

如果用户受网络策略的约束，则网络策略将在身份验证期间强制执行。

ENFORCED_NOT_REQUIRED

用户 无需 受网络策略的约束即可生成和使用编程访问令牌。

如果用户受网络策略的约束，则网络策略将在身份验证期间强制执行。

NOT_ENFORCED

用户 无需 受网络策略的约束即可生成和使用编程访问令牌。

如果用户受网络策略的约束，则在身份验证期间 不会 强制执行网络策略。

例如，创建身份验证策略以移除网络策略要求，但强制执行用户必须遵守的任何网络策略：

CREATE AUTHENTICATION POLICY my_authentication_policy
  PAT_POLICY=(
    NETWORK_POLICY_EVALUATION = ENFORCED_NOT_REQUIRED
  );
Copy

然后，将身份验证策略应用于账户或用户。

再举一个例子，修改现有身份验证策略以移除网络策略要求，并防止强制执行用户必须遵守的任何网络策略：

ALTER AUTHENTICATION POLICY my_authentication_policy
  SET PAT_POLICY = (
    NETWORK_POLICY_EVALUATION = NOT_ENFORCED
  );
Copy

身份验证策略要求

如果存在限制用户身份验证方法的 身份验证策略，则除非该策略中的 AUTHENTICATION_METHODS 列表包括 'PROGRAMMATIC_ACCESS_TOKEN'，否则用户无法生成和使用编程访问令牌。

例如，假设身份验证策略限制用户使用 OAuth 和密码方法进行身份验证：

CREATE AUTHENTICATION POLICY my_auth_policy
  ...
  AUTHENTICATION_METHODS = ('OAUTH', 'PASSWORD')
  ...
Copy

除非您将 'PROGRAMMATIC_ACCESS_TOKEN' 添加至 AUTHENTICATION_METHODS 列表中，否则用户无法生成和使用编程访问令牌。您可以使用 ALTER AUTHENTICATION POLICY 命令来更新此列表。

例如：

ALTER AUTHENTICATION POLICY my_auth_policy
  SET AUTHENTICATION_METHODS = ('OAUTH', 'PASSWORD', 'PROGRAMMATIC_ACCESS_TOKEN');
Copy

配置默认和最长到期时间

管理员（拥有 ACCOUNTADMIN 角色的用户）可以配置以下影响编程访问令牌到期时间的设置：

设置最长到期时间

默认情况下，您可以为令牌指定最多 365 天的到期时间。如果您想将其缩短到更短的时间，请创建或修改 身份验证策略，以指定具有最长到期时间的编程访问令牌策略。

执行 CREATE AUTHENTICATION POLICY 或 ALTER AUTHENTICATION POLICY 命令。在PAT_POLICY 子句中，将 MAX_EXPIRY_IN_DAYS 设置为介于 1 到 365 之间的值。

例如，要创建将最大天数设置为 100 天的身份验证策略，请执行以下操作：

CREATE AUTHENTICATION POLICY my_authentication_policy
  PAT_POLICY=(
    MAX_EXPIRY_IN_DAYS=100
  );
Copy

然后，将身份验证策略应用于账户或用户。

再举一个例子，要修改现有的身份验证策略以将最长时间设置为 90 天，请执行以下操作：

ALTER AUTHENTICATION POLICY my_authentication_policy
  SET PAT_POLICY = (
    MAX_EXPIRY_IN_DAYS=90
  );
Copy

备注

如果现有编程访问令牌的到期时间超过了新的最长到期时间，则尝试使用这些令牌进行身份验证将失败。

例如，假设您生成了一个名为 my_token 且到期时间为 7 天的编程访问令牌。如果您稍后将所有令牌的最长到期时间更改为 2 天，则使用 my_token 身份验证将失败，因为令牌的到期时间超过了新的最长到期时间。

设置默认到期时间

默认情况下，编程访问令牌在 15 天后过期。如果要更改此设置，请创建或修改 身份验证策略，指定具有默认到期时间的编程访问令牌策略。

执行 CREATE AUTHENTICATION POLICY 或 ALTER AUTHENTICATION POLICY 命令。在 PAT_POLICY 子句中，将 DEFAULT_EXPIRY_IN_DAYS 设置为介于 1 到 最长到期时间 之间的值。

例如，要创建将默认值设置为 5 天的身份验证策略，请执行以下操作：

CREATE AUTHENTICATION POLICY my_authentication_policy
  PAT_POLICY=(
    DEFAULT_EXPIRY_IN_DAYS=5
  );
Copy

然后，将身份验证策略应用于账户或用户。

再举一个例子，要更改现有的身份验证策略以将默认值设置为 30 天，请执行以下操作：

ALTER AUTHENTICATION POLICY my_authentication_policy
  SET PAT_POLICY = (
    DEFAULT_EXPIRY_IN_DAYS=30
  );
Copy

编程访问令牌所需的权限

要创建和管理编程访问令牌，您需要使用已被授予以下权限的角色：

  • 对于人类用户（TYPE =PERSON），您无需任何特殊权限即可 为自己 生成、修改、删除或显示编程访问令牌。

  • 如果您要为其他用户或服务用户生成、修改、删除或显示编程访问令牌（TYPE =SERVICE），则必须使用对该用户具有 OWNERSHIP 或 MODIFY PROGRAMMATIC AUTHENTICATION METHODS 权限的角色。

    例如，假设您要向具有 my_service_owner_role 自定义角色的用户授予为服务用户 my_service_user 生成和管理编程访问令牌的能力。您可以将 my_service_user 用户的 MODIFY PROGRAMMATIC AUTHENTICATION METHODS 权限授予角色 my_service_owner_role：

    GRANT MODIFY PROGRAMMATIC AUTHENTICATION METHODS ON USER my_service_user
  TO ROLE my_service_owner_role;
    Copy

生成编程访问令牌

您可以在 Snowsight 中或通过执行 SQL 命令来生成编程访问令牌。

  1. 登录 Snowsight。

  2. 选择 Admin » Users & Roles。

  3. 选择要为其生成编程访问令牌的用户。

  4. 在 Programmatic access tokens 下，选择 Generate new token。

  5. 在 New programmatic access token 对话中，输入以下信息：

    1. 在 Name 字段中，输入令牌的名称。

      名称只能使用字母、数字和下划线。名称必须以字母或下划线开头。名称中的字母以大写字符形式存储和解析。

    2. 在 Comment 字段中，输入有关令牌的描述性注释。

      创建令牌后，此注释将显示在 Programmatic access tokens 部分的令牌下方。

    3. 从 Expires in 中选择令牌的过期天数。

    4. 如果您代表用户为服务生成令牌（如果 USER 对象 TYPE=SERVICE），或者要限制可以执行的操作范围，请选择 One specific role (recommended) 并选择应用于权限评估和对象创建的角色。

      当您使用此令牌进行身份验证时，您创建的任何对象均归该角色所有，且此角色用于权限评估。

      备注

      即使用户将 DEFAULT_SECONDARY_ROLES 设置为（“ALL”），也不会使用次要角色。

      若您改为选择 Any of my roles，则将根据您的 活动角色 评估您创建的任何对象和权限。

    5. 选择 Generate。

  6. 复制或下载生成的编程访问令牌，以便您可以使用该令牌进行身份验证。

    备注

    关闭此消息框后，您将无法复制或下载此令牌。

Programmatic access tokens 部分列出了新令牌。

如前所述，要使用编程访问令牌，与该令牌关联的用户 必须遵守网络策略，除非您设置了身份验证策略来更改此要求。

如果不受网络策略约束的人类用户需要使用编程访问令牌进行身份验证，您可以通过选择 |ellipsis-explorer||ra|Bypass requirement for network policy 来暂时绕过对网络策略的要求。

备注

Bypass requirement for network policy 不允许用户绕过网络策略本身。

创建编程访问令牌后，您无法更改到期日期。您必须撤消该令牌并生成具有新到期时间的新令牌。

如果您为编程访问令牌指定了角色且该角色已从用户手中撤销，则编程访问令牌使用系统 PUBLIC 角色。

使用编程访问令牌

以下各节说明如何使用编程访问令牌作为密码以及如何对 Snowflake 端点进行身份验证：

使用编程访问令牌作为密码

要使用编程访问令牌作为密码进行身份验证，可以在驱动程序设置或连接 Snowflake 的调用中为密码值指定令牌。

例如，如果您使用 Snowflake Connector for Python，则可以在调用 snowflake.connector.connect 方法时将编程访问令牌指定为 password 实参。

conn = snowflake.connector.connect(
    user=USER,
    password=<programmatic_access_token>,
    account=ACCOUNT,
    warehouse=WAREHOUSE,
    database=DATABASE,
    schema=SCHEMA
)
Copy

同样，您可以在第三方应用程序（例如 Tableau 或 PowerBI）中使用编程访问令牌代替密码。将编程访问令牌粘贴到密码字段中。

备注

默认情况下，使用编程访问令牌 需要为用户或账户中的所有用户激活网络策略。要在第三方应用程序中使用编程访问令牌，必须创建允许来自第三方应用程序 IP 地址范围的请求的网络策略。

使用编程访问令牌对端点进行身份验证

要使用编程访问令牌进行身份验证，请在请求中设置以下 HTTP 标头：

  • Authorization: Bearer token_secret

  • :code:`X-Snowflake-Authorization-Token-Type: PROGRAMMATIC_ACCESS_TOKEN`（可选）

例如，如果您使用 cURL 向 Snowflake REST API 端点发送请求：

curl --location 'https://myorganization-myaccount.snowflakecomputing.cn/api/v2/databases' \
  --header "Authorization: Bearer <token_secret>"
Copy

再举一个例子，如果您使用 cURL 向 Snowflake SQL API 端点发送请求：

curl -si -X POST https://myorganization-myaccount.snowflakecomputing.cn/api/v2/statements \
  --header "Content-Type: application/json" \
  --header "Accept: application/json" \
  --header "Authorization: Bearer <token_secret>" \
  --data '{"statement": "select 1"}'
Copy

如果请求因 PAT_INVALID 错误而失败，可能是由于以下原因之一：

  • 未找到与编程访问令牌关联的用户。

  • 验证失败。

  • 未找到与编程访问令牌关联的角色。

  • 该用户与指定的编程访问令牌无关联。

管理编程访问令牌

以下部分说明如何使用、修改、列出、轮换和撤消编程访问令牌：

备注

在使用编程访问令牌进行身份验证的会话中，您无法修改、重命名、轮换或撤消编程访问令牌。

列出编程访问令牌

您可以在 Snowsight 中或通过执行 SQL 命令列出用户的编程访问令牌。

  1. 登录 Snowsight。

  2. 选择 Admin » Users & Roles。

  3. 选择拥有编程访问令牌的用户。

    用户的编程访问令牌列在 Programmatic access tokens 下。

备注

七天后，过期的编程访问令牌将被删除，且不再出现在 Snowsight 或 SHOW USER PROGRAMMATIC ACCESS TOKENS 命令的输出中。

重命名编程访问令牌

您可以在 Snowsight 中或通过执行 SQL 命令来更改编程访问令牌的名称。

  1. 登录 Snowsight。

  2. 选择 Admin » Users & Roles。

  3. 选择与编程访问令牌关联的用户。

  4. 在 Programmatic access tokens 下方，找到编程访问令牌并选择 更多选项 » Edit。

  5. 在 Name 字段中，更改令牌的名称，然后选择 Save。

轮换编程访问令牌

您可以在 Snowsight 中或通过执行 SQL 命令来轮换编程访问令牌。

轮换令牌会返回一个名称相同且到期时间更长的新令牌密钥。轮换令牌也会使现有令牌密钥过期。使用新令牌向 Snowflake 进行身份验证。

  1. 登录 Snowsight。

  2. 选择 Admin » Users & Roles。

  3. 选择与编程访问令牌关联的用户。

  4. 在 Programmatic access tokens 下方，找到编程访问令牌并选择 更多选项 » Rotate。

  5. 如果您希望先前的令牌密钥立即过期，请选择 Expire current secret immediately。

  6. 选择 Rotate token。

  7. 复制或下载生成的编程访问令牌，以便您可以使用该令牌进行身份验证。

    备注

    关闭此消息框后，您将无法复制或下载此令牌。

撤消编程访问令牌

您可以在 Snowsight 中或通过执行 SQL 命令来撤销编程访问令牌。

  1. 登录 Snowsight。

  2. 选择 Admin » Users & Roles。

  3. 选择与编程访问令牌关联的用户。

  4. 在 Programmatic access tokens 下方，找到编程访问令牌并选择 更多选项 » Delete。

重新启用已禁用的编程访问令牌

当您 禁用用户的登录访问权限 或 Snowflake 锁定用户登录时，该用户的编程访问令牌将自动禁用。

备注

当用户 暂时被锁定时 <label-user_management_unlock>`（例如，由于五次或更多次尝试身份验证失败），编程访问令牌 :emph:`不会 被禁用。

如果您运行 SHOW USER PROGRAMMATIC ACCESS TOKENS 命令，则该用户关联令牌的 status 列值已 DISABLED。

SHOW USER PROGRAMMATIC ACCESS TOKENS FOR USER example_user;
Copy
+---------------+--------------+------------------+-------------------------------+----------+---------+-------------------------------+--------------+-------------------------------------------+------------+
| name          | user_name    | role_restriction | expires_at                    | status   | comment | created_on                    | created_by   | mins_to_bypass_network_policy_requirement | rotated_to |
|---------------+--------------+------------------+-------------------------------+----------+---------+-------------------------------+--------------+-------------------------------------------+------------|
| EXAMPLE_TOKEN | EXAMPLE_USER | MY_ROLE          | 2025-04-28 12:13:46.431 -0700 | DISABLED | NULL    | 2025-04-13 12:13:46.431 -0700 | EXAMPLE_USER | NULL                                      | NULL       |
+---------------+--------------+------------------+-------------------------------+----------+---------+-------------------------------+--------------+-------------------------------------------+------------+

如果您稍后为该用户启用登录访问权限或 Snowflake 解锁该用户的登录访问权限，则该用户的编程访问令牌将保持禁用状态。要再次启用令牌，请执行 ALTER USER ... MODIFY PROGRAMMATIC ACCESS TOKEN (PAT) 命令并将 DISABLED 设置为 FALSE。例如：

ALTER USER example_user MODIFY PROGRAMMATIC ACCESS TOKEN example_token SET DISABLED = FALSE;
Copy

从密钥中获取有关编程访问令牌的信息

如果您需要有关编程访问令牌的信息，根据该令牌的密钥，请调用 SYSTEM$DECODE_PAT 函数。如果密钥已被泄露并且您想知道与令牌关联的用户、令牌的名称和令牌的状态，则可以使用此函数。

例如：

SELECT SYSTEM$DECODE_PAT('abC...Y5Z');
Copy
+------------------------------------------------------------------------+
| SYSTEM$DECODE_PAT('☺☺☺...☺☺☺')                                         |
|------------------------------------------------------------------------|
| {"STATE":"ACTIVE","PAT_NAME":"MY_EXAMPLE_TOKEN","USER_NAME":"MY_USER"} |
+------------------------------------------------------------------------+

最佳实践

  • 如果您需要存储编程访问令牌，请安全地进行存储（例如，使用密码或密钥管理器）。

  • 避免在代码中暴露编程访问令牌。

  • 生成令牌时，将令牌的使用限制为特定角色。

  • 定期审查和轮换编程访问令牌。用户可以在 生成令牌时 设置到期时间，管理员可以 缩短所有令牌的最长到期时间，以鼓励令牌轮换。

限制

  • 在生成令牌时，您只能将编程访问令牌限制为某个角色。生成令牌后，无法更改或移除其绑定的角色。

  • 您只能在生成编程访问令牌时设置该令牌的到期时间。生成令牌后，您无法更改到期时间。您可以 撤消编程访问令牌 并生成具有不同到期时间的新令牌。

  • 您只能在创建编程访问令牌时查看其密钥。创建编程访问令牌后，您只能查看有关令牌的信息，而不能查看令牌的密钥。

  • 管理员可以列出给定用户的所有编程访问令牌，但不能列出账户的所有编程访问令牌。

  • 撤销程序访问令牌后无法恢复。

语言: 中文