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

先决条件¶

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

• 网络策略要求

• 身份验证策略要求

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

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

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

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

配置默认和最长到期时间¶

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

• 设置最长到期时间

• 设置默认到期时间

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

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

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

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

编程访问令牌所需的权限¶

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

• 对于人类用户（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 命令来生成编程访问令牌。

+---------------+-----------------+
| token_name    | token_secret    |
|---------------+-----------------|
| EXAMPLE_TOKEN | ... (token) ... |
+---------------+-----------------+

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

对于限制为特定角色的编程访问令牌，若该角色被用户撤销或删除，用户将无法再使用该编程访问令牌进行身份验证。

使用编程访问令牌¶

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

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

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

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

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

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"}'

管理编程访问令牌¶

The following sections explain how to use, modify, list, rotate, revoke, and re-enable programmatic access tokens:

• 列出编程访问令牌

• 重命名编程访问令牌

• 轮换编程访问令牌

• 撤消编程访问令牌

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

SHOW USER PROGRAMMATIC ACCESS TOKENS FOR USER example_user;

SELECT * FROM SNOWFLAKE.ACCOUNT_USAGE.CREDENTIALS WHERE type = 'PAT';

ALTER USER IF EXISTS example_user ROTATE PROGRAMMATIC ACCESS TOKEN example_token;

ALTER USER IF EXISTS example_user
  ROTATE PROGRAMMATIC ACCESS TOKEN example_token
  EXPIRE_ROTATED_TOKEN_AFTER_HOURS = 0;

+---------------+-----------------+-------------------------------------+
| token_name    | token_secret    | rotated_token_name                  |
|---------------+-----------------+-------------------------------------|
| EXAMPLE_TOKEN | ... (token) ... | EXAMPLE_TOKEN_ROTATED_1744239049066 |
+---------------+-----------------+-------------------------------------+

ALTER USER IF EXISTS example_user REMOVE PROGRAMMATIC ACCESS TOKEN example_token;

SHOW USER PROGRAMMATIC ACCESS TOKENS FOR USER example_user;

+---------------+--------------+------------------+-------------------------------+----------+---------+-------------------------------+--------------+-------------------------------------------+------------+
| 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       |
+---------------+--------------+------------------+-------------------------------+----------+---------+-------------------------------+--------------+-------------------------------------------+------------+

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

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

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

例如：

SELECT SYSTEM$DECODE_PAT('abC...Y5Z');

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

Handling a leaked programmatic access token¶

Snowflake is part of the GitHub secret scanning partner program (https://docs.github.com/en/code-security/secret-scanning/secret-scanning-partnership-program/secret-scanning-partner-program). If the secret for a programmatic access token has been checked in to a public GitHub repository, Snowflake is notified and disables the programmatic access token automatically. Snowflake sends an email notification about the leaked token to your account administrator and to the user who is associated with the token.

The notification includes:

• The name of the Snowflake account

• The name of the Snowflake user

• The name, ID, and status of the programmatic access token

• The URL of the GitHub repository

If you own a GitHub repository, you can allow Snowflake to disable leaked tokens by enabling secret scanning (https://docs.github.com/en/code-security/secret-scanning/enabling-secret-scanning-features/enabling-secret-scanning-for-your-repository). You can also enable push protection (https://docs.github.com/en/code-security/secret-scanning/enabling-secret-scanning-features/enabling-push-protection-for-your-repository) to prevent Snowflake programmatic access tokens from being committed to your GitHub repository.

If a programmatic access token is leaked, you should examine the queries executed during the sessions that used the programmatic access token for authentication. To identify these queries, you can use the following SQL statement:

WITH session_ids_with_leaked_pats AS (
  SELECT DISTINCT s.session_id
    FROM SNOWFLAKE.ACCOUNT_USAGE.SESSIONS s JOIN SNOWFLAKE.ACCOUNT_USAGE.LOGIN_HISTORY lh
      ON s.login_event_id= lh.event_id
    WHERE
      lh.first_authentication_factor_id = '<pat_id>'
)
SELECT qh.*
  FROM SNOWFLAKE.ACCOUNT_USAGE.QUERY_HISTORY qh JOIN session_ids_with_leaked_pats slp
    ON qh.session_id = slp.session_id;

In addition, if the programmatic access token has been replicated to another account, you must disable the token in that account. To determine which accounts might contain the replicated token, run the SHOW REPLICATION GROUPS command.

识别使用编程访问令牌的登录会话¶

要确定编程访问令牌何时被用于身份验证，可以在包含凭据 ID 的列上，在 ACCOUNT_USAGE 架构中加入 LOGIN_HISTORY 和 CREDENTIALS 视图。

• 如果 first_authentication_factor 列包含 PROGRAMMATIC_ACCESS_TOKEN，LOGIN_HISTORY 视图的 first_authentication_factor_id 列将包含凭据 ID。

• CREDENTIALS 视图在 credential_id 列中包含凭据 ID。

例如：

SELECT
    login.event_timestamp,
    login.user_name,
    cred.name
  FROM SNOWFLAKE.ACCOUNT_USAGE.LOGIN_HISTORY login
    JOIN SNOWFLAKE.ACCOUNT_USAGE.CREDENTIALS cred
    ON login.first_authentication_factor_id = cred.credential_id
  WHERE login.first_authentication_factor = 'PROGRAMMATIC_ACCESS_TOKEN';

+-------------------------------+-----------+-----------+
| EVENT_TIMESTAMP               | USER_NAME | NAME      |
|-------------------------------+-----------+-----------|
| 2025-08-01 09:01:06.098 -0700 | USER_A    | PAT_FOR_A |
| 2025-07-08 13:33:07.687 -0700 | USER_B    | MY_PAT    |
| 2025-07-08 14:15:26.234 -0700 | USER_C    | MY_TOKEN  |
+-------------------------------+-----------+-----------+

要获取有关在此登录会话期间运行的查询的信息，您可以将 LOGIN_HISTORY 视图与 login_event_id 列中的 SESSIONS 视图一起加入以获取会话 ID，然后使用该 ID 加入 QUERY_HISTORY 视图。

最佳实践¶

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

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

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

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

限制¶

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

• You cannot change some of the properties of a programmatic access token after generating the token:

  • After you generate the token, you cannot change or remove the role that the token is restricted to.

  • After you generate the token, you cannot change the expiration time of the token. You can revoke a programmatic access token and generate a new token with a different expiration time.

• Although there is a command that administrators can run to list all programmatic access tokens for a given user (SHOW USER PROGRAMMATIC ACCESS TOKENS), there is no command for listing all programmatic access tokens in the account.

  Administrators can, however, query the CREDENTIALS 视图 view to list the programmatic access tokens in account.

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

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