CREATE SECURITY INTEGRATION (External OAuth)¶

语法¶

CREATE [ OR REPLACE ] SECURITY INTEGRATION [IF NOT EXISTS]
  <name>
  TYPE = EXTERNAL_OAUTH
  ENABLED = { TRUE | FALSE }
  EXTERNAL_OAUTH_TYPE = { OKTA | AZURE | PING_FEDERATE | CUSTOM }
  EXTERNAL_OAUTH_ISSUER = '<string_literal>'
  EXTERNAL_OAUTH_TOKEN_USER_MAPPING_CLAIM = { '<string_literal>' | ('<string_literal>' [ , '<string_literal>' , ... ] ) }
  EXTERNAL_OAUTH_SNOWFLAKE_USER_MAPPING_ATTRIBUTE = { 'LOGIN_NAME' | 'EMAIL_ADDRESS' }
  [ EXTERNAL_OAUTH_JWS_KEYS_URL = { '<string_literal>' | ('<string_literal>' [ , '<string_literal>' , ... ] ) } ]
  [ EXTERNAL_OAUTH_BLOCKED_ROLES_LIST = ( '<role_name>' [ , '<role_name>' , ... ] ) ]
  [ EXTERNAL_OAUTH_ALLOWED_ROLES_LIST = ( '<role_name>' [ , '<role_name>' , ... ] ) ]
  [ EXTERNAL_OAUTH_RSA_PUBLIC_KEY = <public_key1> ]
  [ EXTERNAL_OAUTH_RSA_PUBLIC_KEY_2 = <public_key2> ]
  [ EXTERNAL_OAUTH_AUDIENCE_LIST = { '<string_literal>' | ('<string_literal>' [ , '<string_literal>' , ... ] ) } ]
  [ EXTERNAL_OAUTH_ANY_ROLE_MODE = { DISABLE | ENABLE | ENABLE_FOR_PRIVILEGE } ]
  [ EXTERNAL_OAUTH_SCOPE_DELIMITER = '<string_literal>' ]
  [ EXTERNAL_OAUTH_SCOPE_MAPPING_ATTRIBUTE = '<string_literal>' ]
  [ COMMENT = '<string_literal>' ]

必填参数¶

name

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

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

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

TYPE = EXTERNAL_OAUTH

区分 External OAuth 集成与 Snowflake OAuth 集成。

ENABLED = { TRUE | FALSE }

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

• TRUE 允许集成基于管道定义中指定的参数运行。

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

EXTERNAL_OAUTH_TYPE = { OKTA | AZURE | PING_FEDERATE | CUSTOM }

指定 OAuth 2.0 授权服务器为 Okta、Microsoft Entra ID、Ping Identity PingFederate 或自定义 OAuth 2.0 授权服务器。

EXTERNAL_OAUTH_ISSUER = 'string_literal'

指定 URL 以定义 OAuth 2.0 授权服务器。

EXTERNAL_OAUTH_TOKEN_USER_MAPPING_CLAIM = { 'string_literal' | ('string_literal' [ , 'string_literal' , ... ] ) }

指定可将访问令牌映射到用户记录的一个或多个访问令牌声明。

声明的数据类型必须是字符串或字符串列表。

EXTERNAL_OAUTH_SNOWFLAKE_USER_MAPPING_ATTRIBUTE = { 'LOGIN_NAME' | 'EMAIL_ADDRESS' }

指明应使用哪个 Snowflake 用户记录属性以将访问令牌映射到用户记录。

可选参数¶

EXTERNAL_OAUTH_JWS_KEYS_URL = { 'string_literal' | ('string_literal' [ , 'string_literal' , ... ] ) }

指定要从中下载公钥或证书以验证 External OAuth 访问令牌的 URL 或 URLs 列表。

如果将 EXTERNAL_OAUTH_TYPE 参数设置为 AZURE，则最多可以指定三个 URLs。例如，要指定两个 URLs，可使用以下语法：

EXTERNAL_OAUTH_JWS_KEYS_URL = ('https://example.ca', 'https://example.co.uk')

Copy

如果将 EXTERNAL_OAUTH_TYPE 参数设置为 OKTA、PING_FEDERATE 或 CUSTOM，则只能指定一个 URL。例如：

EXTERNAL_OAUTH_JWS_KEYS_URL = 'https://example.ca'

Copy

EXTERNAL_OAUTH_RSA_PUBLIC_KEY = public_key1

指定 Base64 编码的 RSA 公钥，无需 -----BEGIN PUBLIC KEY----- 和 -----END PUBLIC KEY----- 标头。

EXTERNAL_OAUTH_RSA_PUBLIC_KEY_2 = public_key2

指定另一个 RSA 公钥，无需 -----BEGIN PUBLIC KEY----- 和 -----END PUBLIC KEY----- 标头。用于键的轮换。

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

指定客户端 不能 设置为:ref:主要角色 <label-access_control_role_enforcement> 的角色列表。此列表中的角色 不能 在基于来自 External OAuth 授权服务器的访问令牌创建 Snowflake 会话时使用。

默认情况下，此列表包括 ACCOUNTADMIN、ORGADMIN 和 SECURITYADMIN 角色。要从列表中移除这些拥有权限的角色，请使用 ALTER ACCOUNT 命令将 EXTERNAL_OAUTH_ADD_PRIVILEGED_ROLES_TO_BLOCKED_LIST 账户参数设置为 FALSE。

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

指定客户端不能设置为主要角色的角色列表。

根据 External OAuth 授权服务器提供的访问令牌创建 Snowflake 会话时，可以使用此列表中的角色。

小心

该参数支持 ACCOUNTADMIN、ORGADMIN 和 SECURITYADMIN 系统角色。

创建将这些高权限角色设置为主要角色的 Snowflake 会话时请务必小心。

EXTERNAL_OAUTH_AUDIENCE_LIST = { 'string_literal' | ('string_literal' [ , 'string_literal' , ... ] ) }

在使用客户的 Snowflake 账户 URL（即 <account_identifier>.snowflakecomputing.cn）的基础上，为访问令牌的受众验证指定附加值。有关更多信息，请参阅 账户标识符。

有关使用 Power BI SSO 时此参数的详细信息，请参阅 Power BI SSO 安全集成。

目前，只可以将多名受众 URLs 指定为 External OAuth 自定义客户端。每个 URL 必须放在单引号内，并用逗号分隔每个 URL。例如：

EXTERNAL_OAUTH_AUDIENCE_LIST = ('https://example.com/api/v2/', 'https://example.com')

Copy

EXTERNAL_OAUTH_ANY_ROLE_MODE = { DISABLE | ENABLE | ENABLE_FOR_PRIVILEGE }

指定 OAuth 客户端或用户是否可以使用未在 OAuth 访问令牌中定义的角色。请注意，在将 :doc:` Power BI 用于 Snowflake 集成 </user-guide/oauth-powerbi>` 时，PowerBI 用户即使启用此参数也无法切换角色。

• DISABLE 不允许 OAuth 客户端或用户切换角色（即 USE ROLE role;）。默认。

• ENABLE 允许 OAuth 客户端或用户切换角色。

• ENABLE_FOR_PRIVILEGE 允许 OAuth 客户端或用户仅为具有 USE_ANY_ROLE 权限的客户端或用户切换角色。可以将此权限授予用户可以使用的一个或多个角色，也可以撤消。例如：

  GRANT USE_ANY_ROLE ON INTEGRATION external_oauth_1 TO role1;
  

  Copy

  REVOKE USE_ANY_ROLE ON INTEGRATION external_oauth_1 FROM role1;
  

  Copy

请注意，该值可以选择放在单引号内（例如 DISABLE 或者 'DISABLE'）。

EXTERNAL_OAUTH_SCOPE_DELIMITER = 'string_literal'

指定授权令牌中的作用域分隔符来替换默认分隔符 ','。分隔符可以是任何单个字符，例如逗号 (',') 或空格 (' ')。

只有将 EXTERNAL_OAUTH_TYPE 参数设置为 CUSTOM 才能使用此属性。

EXTERNAL_OAUTH_SCOPE_MAPPING_ATTRIBUTE = 'string_literal'

指定可将访问令牌映射到账户角色的访问令牌声明。

只能将此参数设置为 scp 或 scope。

只有将 EXTERNAL_OAUTH_TYPE 参数设置为 CUSTOM 才能使用此参数。

COMMENT = 'string_literal'

指定集成的注释。

默认：无值

访问控制要求¶

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

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

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

使用说明¶

• 关于元数据：

  注意

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

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

示例¶

DESC SECURITY INTEGRATION external_oauth_azure_1;

DESC SECURITY INTEGRATION external_oauth_okta_1;