CREATE SECURITY INTEGRATION (Snowflake OAuth)¶

语法¶

**用于合作伙伴应用程序的 Snowflake OAuth **

CREATE [ OR REPLACE ] SECURITY INTEGRATION [IF NOT EXISTS]
  <name>
  TYPE = OAUTH
  OAUTH_CLIENT = <partner_application>
  OAUTH_REDIRECT_URI = '<uri>'  -- Required when OAUTH_CLIENT=LOOKER
  [ ENABLED = { TRUE | FALSE } ]
  [ OAUTH_ISSUE_REFRESH_TOKENS = TRUE | FALSE ]
  [ OAUTH_REFRESH_TOKEN_VALIDITY = <integer> ]
  [ OAUTH_USE_SECONDARY_ROLES = IMPLICIT | NONE ]
  [ BLOCKED_ROLES_LIST = ( '<role_name>' [ , '<role_name>' , ... ] ) ]
  [ COMMENT = '<string_literal>' ]

**用于自定义客户端的 Snowflake OAuth **

CREATE [ OR REPLACE ] SECURITY INTEGRATION [IF NOT EXISTS]
  <name>
  TYPE = OAUTH
  OAUTH_CLIENT = CUSTOM
  OAUTH_CLIENT_TYPE = 'CONFIDENTIAL' | 'PUBLIC'
  OAUTH_REDIRECT_URI = '<uri>'
  [ ENABLED = { TRUE | FALSE } ]
  [ OAUTH_ALLOW_NON_TLS_REDIRECT_URI = TRUE | FALSE ]
  [ OAUTH_ENFORCE_PKCE = TRUE | FALSE ]
  [ OAUTH_USE_SECONDARY_ROLES = IMPLICIT | NONE ]
  [ PRE_AUTHORIZED_ROLES_LIST = ( '<role_name>' [ , '<role_name>' , ... ] ) ]
  [ BLOCKED_ROLES_LIST = ( '<role_name>' [ , '<role_name>' , ... ] ) ]
  [ OAUTH_ISSUE_REFRESH_TOKENS = TRUE | FALSE ]
  [ OAUTH_REFRESH_TOKEN_VALIDITY = <integer> ]
  [ NETWORK_POLICY = '<network_policy>' ]
  [ OAUTH_CLIENT_RSA_PUBLIC_KEY = <public_key1> ]
  [ OAUTH_CLIENT_RSA_PUBLIC_KEY_2 = <public_key2> ]
  [ COMMENT = '<string_literal>' ]

必填参数（所有 OAuth 客户端）¶

name

字符串，指定集成的标识符（即名称）；在账户中必须是唯一的。

此外，标识符必须以字母字符开头，且不能包含空格或特殊字符，除非整个标识符字符串放在双引号内（例如，"My object"）。放在双引号内的标识符也区分大小写。

有关更多详细信息，请参阅 标识符要求。

TYPE = OAUTH

指定集成类型：

• OAUTH：在 Snowflake 和支持 OAuth 的客户端之间创建安全接口。

OAUTH_CLIENT = { CUSTOM | partner_application }

指定客户端类型：

• CUSTOM：在 Snowflake 和自定义客户端之间创建 OAuth 接口。

• partner_application：在 Snowflake 和合作伙伴应用程序之间创建 OAuth 接口。支持的值包括：

  • TABLEAU_DESKTOP：Tableau Desktop 版本 2019.1 或更高版本。

  • TABLEAU_SERVER：Tableau Online 或 Tableau Server。如果 Tableau Server 使用到 Snowflake 服务的专用连接来连接到 Snowflake，请确保改为指定 OAUTH_CLIENT = CUSTOM。

  • LOOKER：Looker 商业智能工具。

OAUTH_REDIRECT_URI = 'uri'

指定客户端 URI。用户通过身份验证后，Web 浏览器将重定向到此 URI。

当 OAUTH_CLIENT = LOOKER 时，此参数是必填参数。有关详细信息，请参阅 Looker 文档 (https://docs.looker.com/setup-and-management/database-config/snowflake#oauth) 中的示例。

其他必填参数（自定义客户端）¶

仅当 OAUTH_CLIENT = CUSTOM 时才需要（即为自定义客户端创建集成时）

OAUTH_CLIENT_TYPE = { 'CONFIDENTIAL' | 'PUBLIC' }

指定要注册的客户端的类型。Snowflake 同时支持机密客户端和公共客户端。机密客户端可以存储密钥。这些客户端在受保护的区域运行，最终用户无法访问它们。例如，部署在云上的安全服务可以是机密客户端；而在桌面上运行或通过应用商店分发的客户端可以是公共客户端。

OAUTH_REDIRECT_URI = 'uri'

指定客户端 URI。用户通过身份验证后，Web 浏览器将重定向到此 URI。URI 必须受 TLS（传输层安全性）保护，除非可选的 OAUTH_ALLOW_NON_TLS_REDIRECT_URI 参数设置为 TRUE。

在对 授权端点 的请求中，不要包含与重定向 URI 一同发送的查询参数。例如，如果在对授权端点的请求中，redirect_uri 查询参数的值为 https://www.example.com/connect?authType=snowflake，请确保将 OAUTH_REDIRECT_URI 参数设置为 https://www.example.com/connect。

可选参数（所有 OAuth 客户端）¶

ENABLED = { TRUE | FALSE }

指定是启动集成操作还是暂停集成操作。

• TRUE 启用集成。

• FALSE 禁用集成以便进行维护。Snowflake 与第三方服务之间的任何集成都无法正常工作。

默认值为 FALSE。如果创建安全集成时未将该参数设置为 TRUE，Snowflake 会将该参数设置为 FALSE。

其他可选参数（合作伙伴应用程序）¶

当 OAUTH_CLIENT = <partner_application>（即为合作伙伴应用程序创建集成时）时有效

OAUTH_ISSUE_REFRESH_TOKENS = { TRUE | FALSE }

布尔，指定当前访问令牌到期时，是否允许客户端用刷新令牌交换访问令牌。如果设置为 FALSE，则无论 OAUTH_REFRESH_TOKEN_VALIDITY 中设置的整数值如何，都不会发出刷新令牌。用户同意已撤销，用户必须再次确认授权。

默认：TRUE

备注

如果此参数设置为 FALSE，并且安全集成也 ENABLED = TRUE，则 Snowflake OAuth 流程会重复，发出不可配置的访问令牌，并且访问令牌的有效期为 600 秒（10 分钟）。此访问令牌过期后，用户必须重新进行身份验证。

将此参数设置为 FALSE 和 ENABLED = FALSE 会导致不颁发任何令牌并且禁用集成。

OAUTH_REFRESH_TOKEN_VALIDITY = integer

指定刷新令牌的有效时间（整数，以秒为单位）。此参数可用于定期使刷新令牌过期。注意，OAUTH_ISSUE_REFRESH_TOKENS 必须设置为 TRUE。

当刷新令牌过期时，应用程序将需要再次引导用户通过授权流程以获得新的刷新令牌。

支持的最小值、最大值和默认值如下：

应用程序	最小值	最大值	默认值
Tableau Desktop	:code:`60`（1 分钟）	:code:`36000`（10 小时）	:code:`36000`（10 小时）
Tableau Server 或 Tableau Online	:code:`60`（1 分钟）	:code:`7776000`（90 天）	:code:`7776000`（90 天）
自定义客户端	:code:`3600`（1 小时）	:code:`7776000`（90 天）	:code:`7776000`（90 天）

如果因业务需求，需要降低最小值或提高最大值，请让账户管理员向 Snowflake 支持部门 (https://community.snowflake.com/s/article/How-To-Submit-a-Support-Case-in-Snowflake-Lodge) 发送请求。

OAUTH_USE_SECONDARY_ROLES = { IMPLICIT | NONE }

• IMPLICIT：默认情况下，在用户属性中设置的默认辅助角色在打开的会话中处于激活状态。

• NONE：正在打开的会话中不支持默认辅助角色。

默认：NONE

BLOCKED_ROLES_LIST = ( 'role_name' [ , 'role_name' , ... ] )

以逗号分隔的 Snowflake 角色列表，用户在进行身份验证后 无法 显式同意使用这些角色（例如 'BLOCKED_ROLES_LIST = ('custom_role1', 'custom_role2')）。

默认情况下，Snowflake 会阻止 ACCOUNTADMIN、ORGADMIN 和 SECURITYADMIN 角色进行身份验证。要允许这些特权角色进行身份验证，请使用 ALTER ACCOUNT 命令，将 OAUTH_ADD_PRIVILEGED_ROLES_TO_BLOCKED_LIST 账户参数设为 FALSE。

COMMENT = 'string_literal'

指定集成的注释。

默认：无值

其他可选参数（自定义客户端）¶

当 OAUTH_CLIENT = CUSTOM 时有效（即为自定义客户端创建集成时）

OAUTH_ALLOW_NON_TLS_REDIRECT_URI = { TRUE | FALSE }

如果为 TRUE，则允许将 OAUTH_REDIRECT_URI 设置为 不受 TLS 保护的 URI。我们强烈建议使用 TLS 来防止用于网络钓鱼攻击的中间人 OAuth 重定向。

默认：FALSE

OAUTH_ENFORCE_PKCE = { TRUE | FALSE }

布尔，用于指定集成是否需要代码交换证明密钥 (PKCE)。

默认情况下，PKCE 是可选的，并且仅当 code_challenge 和 code_challenge_method 参数都包含在授权端点 URL 中时才强制执行。但是，我们 强烈 建议客户端要求所有授权都使用 PKCE，以使 OAuth 流更加安全。有关更多信息，请参阅 为自定义客户端配置 Snowflake OAuth。

默认：FALSE

OAUTH_USE_SECONDARY_ROLES = { IMPLICIT | NONE }

• IMPLICIT：默认情况下，在用户属性中设置的默认辅助角色在打开的会话中处于激活状态。

• NONE：正在打开的会话中不支持默认辅助角色。

默认：NONE

PRE_AUTHORIZED_ROLES_LIST = ( 'role_name' [ , 'role_name' , ... ] )

以逗号分隔的 Snowflake 角色列表，用户在进行身份验证后无需显式同意使用这些角色（例如 PRE_AUTHORIZED_ROLES_LIST = ('custom_role1', 'custom_role2')）。请注意，此列表中不能包含 ACCOUNTADMIN、ORGADMIN 和 SECURITYADMIN 角色。

备注

此参数仅支持用于机密客户端。

BLOCKED_ROLES_LIST = ( 'role_name' [ , 'role_name' , ... ] )

以逗号分隔的 Snowflake 角色列表，用户在进行身份验证后 无法 显式同意使用这些角色（例如 BLOCKED_ROLES_LIST = ('custom_role1', 'custom_role2')）。

请注意，默认情况下，此列表中包含 ACCOUNTADMIN、ORGADMIN 和 SECURITYADMIN 角色；但是，如果应从账户中移除这些角色，请让账户管理员向 Snowflake 支持部门 (https://community.snowflake.com/s/article/How-To-Submit-a-Support-Case-in-Snowflake-Lodge) 发送请求。

OAUTH_ISSUE_REFRESH_TOKENS = { TRUE | FALSE }

布尔，指定当前访问令牌到期时，是否允许客户端用刷新令牌交换访问令牌。如果设置为 FALSE，则不会发放刷新令牌。用户同意已撤销，用户必须再次确认授权。

默认：TRUE

OAUTH_REFRESH_TOKEN_VALIDITY = integer

指定刷新令牌的有效时间（整数，以秒为单位）。此参数可用于定期使刷新令牌过期。注意，OAUTH_ISSUE_REFRESH_TOKENS 必须设置为 TRUE。

请注意，如果组织希望降低此参数的最小值或提高其最大值，请让账户管理员向 Snowflake 支持部门 (https://community.snowflake.com/s/article/How-To-Submit-a-Support-Case-in-Snowflake-Lodge) 发送请求。

值:

:code:`86400`（1 天）至 :code:`7776000`（90 天）

默认值:

7776000

NETWORK_POLICY = 'network_policy'

指定现有的 网络策略。此网络策略控制以下网络流量：试图授权交换访问或刷新令牌的授权代码，或使用刷新令牌获取新的访问令牌。

如果还为账户或用户设置了网络策略，请参阅 网络策略优先顺序。

OAUTH_CLIENT_RSA_PUBLIC_KEY = public_key1

指定 RSA 公钥。

OAUTH_CLIENT_RSA_PUBLIC_KEY_2 = public_key2

指定第二个 RSA 公钥。用于键的轮换。

COMMENT = 'string_literal'

指定集成的注释。

默认：无值

访问控制要求¶

用于执行此 SQL 命令的 角色 必须至少具有以下 权限：

有关创建具有指定权限集的自定义角色的说明，请参阅 创建自定义角色。

有关对 安全对象 执行 SQL 操作的相应角色和权限授予的一般信息，请参阅 访问控制概述。

使用说明¶

• 关于元数据：

  注意

  客户应确保在使用 Snowflake 服务时，不会将个人数据（用户对象除外）、敏感数据、出口管制数据或其他受监管数据作为元数据输入。有关更多信息，请参阅 Snowflake 中的元数据字段。

• CREATE OR REPLACE <object> 语句是原子的。也就是说，当对象被替换时，旧对象将被删除，新对象将在单个事务中创建。

示例¶

DESC SECURITY INTEGRATION td_oauth_int1;

DESC SECURITY INTEGRATION ts_oauth_int1;