为自定义客户端配置 Snowflake OAuth¶

工作流程¶

需要执行以下高级步骤才能为自定义客户端配置 OAuth ：

1. 向 Snowflake 注册您的客户端。要注册您的客户端，请创建一个集成。集成是一个 Snowflake 对象，它在 Snowflake 和第三方服务（例如支持 OAuth 的客户端）之间提供接口。

   注册过程定义了客户端 ID 和客户端密钥。

2. 配置对 Snowflake OAuth 端点的调用，以便从 Snowflake 授权服务器请求授权代码，以及请求和刷新访问令牌。

   初始授权请求中的可选“scope”参数限制访问令牌允许的角色，并且还可用于配置刷新令牌行为。

创建 Snowflake OAuth 集成¶

使用 CREATE SECURITY INTEGRATION 命令创建 Snowflake OAuth 集成。请务必在创建集成时指定 OAUTH_CLIENT = CUSTOM。

CREATE SECURITY INTEGRATION oauth_kp_int
  TYPE = OAUTH
  ENABLED = TRUE
  OAUTH_CLIENT = CUSTOM
  OAUTH_CLIENT_TYPE = 'CONFIDENTIAL'
  OAUTH_REDIRECT_URI = 'https://localhost.com'
  OAUTH_ISSUE_REFRESH_TOKENS = TRUE
  OAUTH_REFRESH_TOKEN_VALIDITY = 86400
  BLOCKED_ROLES_LIST = ('SYSADMIN')
  OAUTH_CLIENT_RSA_PUBLIC_KEY ='
  MIIBI
  ...
  ';

调用 OAuth 端点¶

OAuth 端点是客户端为请求授权代码以及请求和刷新访问令牌而调用的 URLs。这些端点是指在调用端点时执行的特定 OAuth 2.0 策略。

Snowflake 提供了以下 OAuth 端点：

授权:

<snowflake_account_url>/oauth/authorize

令牌请求:

<snowflake_account_url>/oauth/token-request

其中， <snowflake_account_url> 是有效的 Snowflake 账户 URL。例如，您可以使用端点 https://myorg-account_xyz.snowflakecomputing.cn/oauth/authorize 和 https://myorg-account_xyz.snowflakecomputing.cn/oauth/token-request。有关 Snowflake 账户 URL 支持的格式的列表，请参阅 与 URL 连接。

要查看安全集成的有效 OAuth 端点列表，请执行 DESCRIBE INTEGRATION，然后查看 OAUTH_ALLOWED_AUTHORIZATION_ENDPOINTS 和 OAUTH_ALLOWED_TOKEN_ENDPOINTS 属性中的值。

<snowflake_account_url>/oauth/authorize

<snowflake_account_url>/oauth/token-request

Content-type: application/x-www-form-urlencoded

{
  "access_token":  "ACCESS_TOKEN",
  "expires_in": 600,
  "refresh_token": "REFRESH_TOKEN",
  "token_type": "Bearer",
  "username": "user1",
}

{
  "data" : null,
  "message" : "This is an invalid client.",
  "code" : null,
  "success" : false,
  "error" : "invalid_client"
}

代码交换证明密钥¶

Snowflake 支持使用代码交换证明密钥 (PKCE) 通过 authorization_code 授予类型获取访问令牌，如 RFC 7636 (https://tools.ietf.org/html/rfc7636) 中所述。PKCE 可用于减少授权代码拦截攻击的可能性，并且适用于可能无法完全保护客户端密钥安全的客户端。

默认情况下，PKCE 是可选的，并且仅当 code_challenge 和 code_challenge_method 参数都包含在授权端点 URL 中时才强制执行。但是，Snowflake 强烈 建议客户端要求所有授权都使用 PKCE，以使 OAuth 流程更加安全。

下面介绍了 Snowflake 的 PKCE 的工作原理：

1. 客户端创建一个名为 代码验证器 的密钥，并对其执行转换以生成 代码质询。客户保留该密钥。

   重要

   根据 ` RFC 7636 的第 4.1 节 <https://tools.ietf.org/html/rfc7636#section-4.1 (https://tools.ietf.org/html/rfc7636#section-4.1)> `_，从允许的 ASCII 字符生成*code verifier*。

2. 将用户定向到授权 URL 的客户端附加以下两个查询参数：

   code_challenge

   指定在第 1 步中生成的代码质询。

   code_challenge_method

   指定在第 1 步中用于生成代码质询的代码验证器上的转换。目前，Snowflake 仅支持 SHA256，因此此值必须设置为 S256。SHA256 的转换算法是 BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))。

3. 在用户同意所请求的范围或 Snowflake 确定该用户同意后，将发出授权代码。

4. 客户端从 Snowflake 授权服务器接收授权代码，然后将其与请求中的 code_verifier 一起提交到令牌端点。

5. Snowflake 转换 code_verifier 值并验证转换后的值是否与生成授权时使用的 code_challenge 值匹配。如果这些值匹配，则授权服务器发出访问令牌和刷新令牌。

使用密钥对身份验证¶

Snowflake 支持在调用 OAuth 令牌端点时使用密钥对身份验证，而不使用典型的用户名/密码身份验证。此身份验证方法需要 2048 位（最低）RSA 密钥对。使用 OpenSSL 生成 PEM（隐私增强邮件）公私密钥对。公钥分配给使用 Snowflake 客户端的 Snowflake 用户。

要配置公钥/私钥对，请执行以下操作：

1. 在终端窗口的命令行中，生成加密的私钥：

   $ openssl genrsa 2048 | openssl pkcs8 -topk8 -v2 des3 -inform PEM -out rsa_key.p8
   

   Copy

   OpenSSL 提示输入用于加密私钥文件的密码。Snowflake 建议使用强密码来保护私钥。记录此密码。您必须在连接到 Snowflake 时输入此密码。请注意，密码仅用于保护私钥，永远不会发送到 Snowflake。

   示例 PEM 私钥

   -----BEGIN ENCRYPTED PRIVATE KEY-----
   MIIE6TAbBgkqhkiG9w0BBQMwDgQILYPyCppzOwECAggABIIEyLiGSpeeGSe3xHP1
   wHLjfCYycUPennlX2bd8yX8xOxGSGfvB+99+PmSlex0FmY9ov1J8H1H9Y3lMWXbL
   ...
   -----END ENCRYPTED PRIVATE KEY-----
   

   Copy

2. 从命令行中，通过引用私钥生成公钥：

   $ openssl rsa -in rsa_key.p8 -pubout -out rsa_key.pub
   

   Copy

   示例 PEM 公钥

   -----BEGIN PUBLIC KEY-----
   MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAy+Fw2qv4Roud3l6tjPH4
   zxybHjmZ5rhtCz9jppCV8UTWvEXxa88IGRIHbJ/PwKW/mR8LXdfI7l/9vCMXX4mk
   ...
   -----END PUBLIC KEY-----
   

   Copy

3. 将公钥和私钥文件复制到本地目录进行存储。记录文件的路径。

   请注意，私钥使用 PKCS#8（公钥加密标准）格式存储，并使用您在上一步中指定的加密短语进行加密；但仍应使用操作系统提供的文件权限机制保护文件，防止未经授权的访问。您有责任在不使用文件时保护该文件。

4. 使用 ALTER SECURITY INTEGRATION 将公钥分配给集成对象。例如：

   ALTER SECURITY INTEGRATION myint SET OAUTH_CLIENT_RSA_PUBLIC_KEY='MIIBIjANBgkqh...';
   

   Copy

   备注

   • 只有账户管理员才能执行 ALTER SECURITY INTEGRATION 命令。

   • 排除该命令中的公钥标头和页脚。

   使用 DESCRIBE INTEGRATION 验证公钥指纹：

   DESC SECURITY INTEGRATION myint;
   
   +----------------------------------+---------------+----------------------------------------------------------------------+------------------+
   | property                         | property_type | property_value                                                       | property_default |
   |----------------------------------+---------------+----------------------------------------------------------------------+------------------|
   ...
   | OAUTH_CLIENT_RSA_PUBLIC_KEY_FP   | String        | SHA256:MRItnbO/123abc/abcdefghijklmn12345678901234=                  |                  |
   | OAUTH_CLIENT_RSA_PUBLIC_KEY_2_FP | String        |                                                                      |                  |
   ...
   +----------------------------------+---------------+----------------------------------------------------------------------+------------------+
   

   Copy

   备注

   密钥轮换 （本主题内容）中介绍了 OAUTH_CLIENT_RSA_PUBLIC_KEY_2_FP 属性。

5. 修改并执行下面的示例代码。该代码使用私钥对 JWT 进行编码，然后将该令牌传递给 Snowflake 授权服务器：

   • 更新安全参数：

     • <private_key>：在文本编辑器中打开 rsa_key.p8 文件，然后复制 BEGIN 页眉和 END 页脚之间的行。

   • 更新会话参数：

     • <account_identifier>：指定账户的全名（由 Snowflake 提供）。

   • 更新 JSON Web 令牌 (JWT) 字段：

     post body

     具有以下标准字段（“claims”）的 JSON 对象：

     属性	数据类型	必填	描述
     iss	字符串	是	指定以 client_id.public_key_fp 格式发出 JWT 主体，其中 client_id 是 OAuth 客户端集成的客户端 ID，public_key_fp 是验证期间使用的公钥的指纹。
     sub	字符串	是	JWT 的主题采用 account_identifier.client_id 格式，其中 account_identifier 是 Snowflake 账户的全名， client_id 是 OAuth 客户端集成的客户端 ID。根据托管账户的云平台（AWS 或 Azure）和区域，完整账户名称可能需要 其他 段。有关更多信息，请参阅 令牌端点 下的 account 变量说明。
     iat	时间戳	否	令牌的发放时间。
     exp	时间戳	是	令牌的到期时间。这段时间应该相对较短（例如几分钟）。

   示例代码

   请注意， private_key 值包括 -----BEGIN 页眉和 -----END 页脚。

   import datetime
   import json
   import urllib
   
   import jwt
   import requests
   
   private_key = """
   <private_key>
   """
   
   public_key_fp = "SHA256:MR..."
   
   
   def _make_request(payload, encoded_jwt_token):
       token_url = "https://<account_identifier>.snowflakecomputing.cn/oauth/token-request"
       headers = {
               u'Authorization': "Bearer %s" % (encoded_jwt_token),
               u'content-type': u'application/x-www-form-urlencoded'
       }
       r = requests.post(
               token_url,
               headers=headers,
               data=urllib.urlencode(payload))
       return r.json()
   
   
   def make_request_for_access_token(oauth_az_code, encoded_jwt_token):
       """ Given an Authorization Code, make a request for an Access Token
       and a Refresh Token."""
       payload = {
           'grant_type': 'authorization_code',
           'code': oauth_az_code
       }
       return _make_request(payload, encoded_jwt_token)
   
   
   def make_request_for_refresh_token(refresh_token, encoded_jwt_token):
       """ Given a Refresh Token, make a request for another Access Token."""
       payload = {
           'grant_type': 'refresh_token',
           'refresh_token': refresh_token
       }
       return _make_request(payload, encoded_jwt_token)
   
   
   def main():
       account_identifier = "<account_identifier>"
       client_id = "1234"  # found by running DESC SECURITY INTEGRATION
       issuer = "{}.{}".format(client_id, public_key_fp)
       subject = "{}.{}".format(account_identifier, client_id)
       payload = {
           'iss': issuer,
           'sub': subject,
           'iat': datetime.datetime.utcnow(),
           'exp': datetime.datetime.utcnow() + datetime.timedelta(seconds=30)
       }
       encoded_jwt_token = jwt.encode(
               payload,
               private_key,
               algorithm='RS256')
   
       data = make_request_for_access_token(oauth_az_code, encoded_jwt_token)
       refresh_token = data['refresh_token']
       data = make_request_for_refresh_token(refresh_token, encoded_jwt_token)
       access_token = data['access_token']
   
   
   if __name__ == '__main__':
       main()
   

   Copy

   创建令牌后，在请求中将令牌提交到令牌端点。请求需要持有者授权格式作为授权标头，而不是通常用于客户端 ID 和客户端密钥的基本授权格式，如下所示：

   "Authorization: Bearer JWT_TOKEN"
   

   Copy

错误代码¶

请参阅 错误代码，以查看与 OAuth 关联的错误代码列表，以及在授权流程、令牌请求或交换期间或在完成 OAuth 流程后创建 Snowflake 会话时，在 JSON Blob 中返回的错误。

预先授权用户对角色的同意¶

安全管理员（即具有 SECURITYADMIN 角色的用户）或更高级别的用户可以预先授权客户端同意使用指定角色和集成为用户启动会话。此同意是通过具有 ADD DELEGATED AUTHORIZATION 关键字的 ALTER USER 授予的。如果没有委派授权，则用户必须在身份验证后授予对角色的同意。也可以撤消此委派授权。

有关更多信息，请参阅 管理针对 OAuth 的用户同意。