使用 Snowflake 对 Snowflake REST APIs 进行身份验证

本主题介绍在使用 Snowflake Snowflake REST APIs 时如何对服务器进行身份验证。

发送请求时，请求必须包含使用以下任一方式的身份验证信息：

使用密钥对身份验证

使用密钥对身份验证时，您需要完成以下任务：

  1. 设置密钥对身份验证

  2. 生成 JWT 令牌

设置密钥对身份验证

若要使用密钥对身份验证，请按照下列步骤操作：

  1. 设置密钥对身份验证。

    在此过程中，您必须执行以下操作：

    1. 生成公钥-私钥对。生成的私钥应位于文件中（例如，名为 rsa_key.p8）。

    2. 将公钥分配给 Snowflake 用户。将密钥分配给用户后，运行 DESCRIBE USER 命令。在输出中，RSA_PUBLIC_KEY_FP 属性应设置为分配给用户的公钥的指纹。

    有关如何生成密钥对并将密钥分配给用户的说明，请参阅 密钥对身份验证和密钥对轮换。

  2. 使用 SnowSQL 验证可以使用生成的私钥 连接到 Snowflake：

    $ snowsql -a <account_identifier> -u <user> --private-key-path <path>/rsa_key.p8
    Copy

    如果生成了加密的私钥，SnowSQL 会提示输入生成密钥时创建的密码。

生成 JWT 令牌

若要在应用程序代码中生成 JWT 令牌，请使用以下步骤：

  1. 为用户生成公钥的指纹（SHA-256 哈希值）。在指纹前加上 SHA256:。

    例如：

    SHA256:hash

    还可以执行 SQL DESCRIBE USER 命令从 RSA_PUBLIC_KEY_FP 属性中获取值。

  2. 生成 一个 JSON Web 令牌 (JWT) (link removed)，其有效负载中包含以下字段：

    字段

    描述

    示例

    iss

    JWT 的发放者。将其设置为以下值：

    account_identifier.user.SHA256:public_key_fingerprint

    其中：

    • account_identifier 是 Snowflake 账户标识符。

      如果使用的是 账户定位器，请从账户定位器中排除任何区域信息。

    • user 是 Snowflake 用户名。

    • SHA256:public_key_fingerprint 是在上一步中生成的指纹。

    备注

    account_identifier 和 user 值必须全部使用大写字符。

    MYORGANIZATION-MYACCOUNT.MYUSER.SHA256:public_key_fingerprint

    sub

    JWT 的主题。将其设置为以下值：

    account_identifier.user

    MYORGANIZATION-MYACCOUNT.MYUSER

    iat

    JWT 的发放时间（以 UTC 表示）。将该值设置为当前时间值，以秒或毫秒为单位。

    ``1615370644``（秒）:newline:. ``1615370644000``（毫秒）

    exp

    JWT 的过期时间（以 UTC 表示）。 可以将该值指定为秒或毫秒。

    备注

    即使指定了更长的过期时间，JWT 在令牌颁发后最多一个小时内有效。

    ``1615374184``（秒）:newline:. ``1615374184000``（毫秒）

  3. 在发送的每个 API 请求中，设置以下标头：

    • Authorization: Bearer JWT

      其中 JWT 是生成的令牌。

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

      如果您省略了 X-Snowflake-Authorization-Token-Type 标头，Snowflake 将通过检查令牌来确定令牌类型。

      即使此标头可选，您也可以选择指定此标头。您可以将标头设置为以下值之一：

      • ``KEYPAIR_JWT``（适用于密钥对身份验证）

      • ``OAUTH``（适用于 OAuth）

      • ``PROGRAMMATIC_ACCESS_TOKEN``（适用于 编程访问令牌）

使用 OAuth

若要使用 OAuth，请按照下列步骤操作：

  1. 设置 OAuth 进行身份验证。

    有关如何设置 OAuth 和获取 OAuth 令牌的详细信息，请参阅 OAuth 简介。

  2. 使用 SnowSQL 验证可以使用生成的 OAuth 令牌连接到 Snowflake：

    • 对于 Linux 和 MacOS 系统

    $ snowsql -a <account_identifier> -u <user> --authenticator=oauth --token=<oauth_token>
    Copy

    • 对于 Windows 系统

    $ snowsql -a <account_identifier> -u <user> --authenticator=oauth --token="<oauth_token>"
    Copy

  3. 在发送的每个 API 请求中，设置以下标头：

    • Authorization: Bearer oauth_token

      其中 oauth_token 是生成的 OAuth 令牌。

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

      如果您省略了 X-Snowflake-Authorization-Token-Type 标头，Snowflake 将通过检查令牌来确定令牌类型。

      即使此标头可选，您也可以选择指定此标头。您可以将标头设置为以下值之一：

      • ``KEYPAIR_JWT``（适用于密钥对身份验证）

      • ``OAUTH``（适用于 OAuth）

      • ``PROGRAMMATIC_ACCESS_TOKEN``（适用于 编程访问令牌）

使用编程访问令牌 (PAT)

要使用编程访问令牌进行身份验证，请在请求中设置以下 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

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

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

  • 验证失败。

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

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

有关更多信息，请参阅 使用编程访问令牌对端点进行身份验证。

语言: 中文