CREATE SECURITY INTEGRATION (Snowflake OAuth)¶

在账户中创建新的 Snowflake OAuth 安全集成或替换现有集成。Snowflake OAuth 安全集成使支持 OAuth 的客户端能够将用户重定向到授权页面并生成访问 Snowflake 的访问令牌（以及可选的刷新令牌）。

For information about creating other types of security integrations (e.g. External OAuth), see CREATE SECURITY INTEGRATION.

See also:: ALTER SECURITY INTEGRATION (Snowflake OAuth) , DROP INTEGRATION , SHOW INTEGRATIONS

语法

用于合作伙伴应用程序的 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_SINGLE_USE_REFRESH_TOKENS_REQUIRED = { TRUE | FALSE } ]
  [ OAUTH_USE_SECONDARY_ROLES = { IMPLICIT | NONE } ]
  [ NETWORK_POLICY = '<network_policy>' ]
  [ BLOCKED_ROLES_LIST = ( '<role_name>' [ , '<role_name>' , ... ] ) ]
  [ USE_PRIVATELINK_FOR_AUTHORIZATION_ENDPOINT = { TRUE | FALSE } ]
  [ 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_SINGLE_USE_REFRESH_TOKENS_REQUIRED = { 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> ]
  [ USE_PRIVATELINK_FOR_AUTHORIZATION_ENDPOINT = { TRUE | FALSE } ]
  [ COMMENT = '<string_literal>' ]

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

name

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

In addition, the identifier must start with an alphabetic character and cannot contain spaces or special characters unless the entire identifier string is enclosed in double quotes (e.g. "My object"). Identifiers enclosed in double quotes are also case-sensitive.

For more details, see Identifier requirements.

TYPE = OAUTH

指定集成类型：

OAUTH: Creates a security interface between Snowflake and a client that supports OAuth.

OAUTH_CLIENT = { CUSTOM | partner_application }

指定客户端类型：

CUSTOM: Creates an OAuth interface between Snowflake and a custom client.
partner_application: Creates an OAuth interface between Snowflake and a partner application. Supported values are:
- TABLEAU_DESKTOP: Tableau Desktop version 2019.1 or higher.
- TABLEAU_SERVER: Tableau Cloud. If Tableau Cloud is connecting to Snowflake using private connectivity to the Snowflake service, be sure to specify OAUTH_CLIENT = CUSTOM instead.
- LOOKER: The Looker business intelligence tool.

OAUTH_REDIRECT_URI = 'uri'

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

This parameter is required when OAUTH_CLIENT = LOOKER. For details, see the example in the Looker documentation (https://docs.looker.com/setup-and-management/database-config/snowflake#oauth).

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

Required only when OAUTH_CLIENT = CUSTOM (i.e. when creating an integration for a custom client)

OAUTH_CLIENT_TYPE = { 'CONFIDENTIAL' | 'PUBLIC' }

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

OAUTH_REDIRECT_URI = 'uri'

Specifies the client URI. After a user is authenticated, the web browser is redirected to this URI. The URI must be protected by TLS (Transport Layer Security) unless the optional OAUTH_ALLOW_NON_TLS_REDIRECT_URI parameter is set to TRUE.

Do not include query parameters sent with the redirect URI in the request to the authorization endpoint. For example, if the value of the redirect_uri query parameter in the request to the authorization endpoint is https://www.example.com/connect?authType=snowflake, make sure the OAUTH_REDIRECT_URI parameter is set to https://www.example.com/connect.

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

ENABLED = { TRUE | FALSE }

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

TRUE enables the integration.
FALSE disables the integration for maintenance. Any integration between Snowflake and a third-party service fails to work.

The value is case-insensitive.

The default is TRUE.

OAUTH_SINGLE_USE_REFRESH_TOKENS_REQUIRED = { TRUE | FALSE }

Specifies whether single-use refresh tokens should be used.

Default: FALSE

USE_PRIVATELINK_FOR_AUTHORIZATION_ENDPOINT = { TRUE | FALSE }

When TRUE, the interaction between Snowflake as the authorization server and the user who is authenticating uses private connectivity. Interactions between Snowflake and the client, including the initial request to the authorization endpoint, still happens over the public internet.

默认：:code:FALSE

NETWORK_POLICY = 'network_policy'

Specifies an existing network policy. This network policy controls network traffic that is attempting to exchange an authorization code for an access or refresh token, use a refresh token to obtain a new access token, or obtain Snowflake resources with an access token.

For more information, see Restricting network traffic for Snowflake OAuth.

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

Valid when OAUTH_CLIENT = <partner_application> (i.e. when creating an integration for a partner application)

OAUTH_ISSUE_REFRESH_TOKENS = { TRUE | FALSE }

Boolean that specifies whether to allow the client to exchange a refresh token for an access token when the current access token has expired. If set to FALSE, a refresh token is not issued regardless of the integer value set in OAUTH_REFRESH_TOKEN_VALIDITY. User consent is revoked, and the user must confirm authorization again.

Default: TRUE

Note

If this parameter is set to FALSE and the security integration also has ENABLED = TRUE, the Snowflake OAuth flow repeats, a non-configurable access token is issued, and the access token is valid for 600 seconds (10 minutes). After this access token expires, the user must authenticate again.

Setting this parameter to FALSE and ENABLED = FALSE results in no tokens being issued and the integration is disabled.

OAUTH_REFRESH_TOKEN_VALIDITY = integer

Integer that specifies how long refresh tokens should be valid (in seconds). This can be used to expire the refresh token periodically. Note that OAUTH_ISSUE_REFRESH_TOKENS must be set to TRUE.

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

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

Minimum: 3600 (1 hour)
Maximum: 7776000 (90 days)
Default: 7776000 (90 days)

If you have a business need to lower the minimum value or raise the maximum value, ask your account administrator to send a request to Snowflake Support.

OAUTH_USE_SECONDARY_ROLES = { IMPLICIT | NONE }

IMPLICIT: Default secondary roles set in the user properties are activated by default in the session being opened.
NONE: Default secondary roles are not supported in the session being opened.

Default: NONE

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

Comma-separated list of Snowflake roles that a user cannot explicitly consent to using after authenticating (e.g. 'BLOCKED_ROLES_LIST = ('custom_role1', 'custom_role2')).

By default, Snowflake prevents the ACCOUNTADMIN, ORGADMIN, GLOBALORGADMIN, and SECURITYADMIN roles from authenticating. To allow these privileged roles to authenticate, use the ALTER ACCOUNT command to set the OAUTH_ADD_PRIVILEGED_ROLES_TO_BLOCKED_LIST account parameter to FALSE.

COMMENT = 'string_literal'

指定集成的注释。

默认：无值

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

Valid when OAUTH_CLIENT = CUSTOM (i.e. when creating an integration for a custom client)

OAUTH_ALLOW_NON_TLS_REDIRECT_URI = { TRUE | FALSE }

If TRUE, allows setting OAUTH_REDIRECT_URI to a URI not protected by TLS. We highly recommend use of TLS to prevent man-in-the-middle OAuth redirects for use in phishing attacks.

Default: FALSE

OAUTH_ENFORCE_PKCE = { TRUE | FALSE }

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

By default, PKCE is optional and is enforced only if the code_challenge and code_challenge_method parameters are both included in the authorization endpoint URL. However, we highly recommend that your client require PKCE for all authorizations to make the OAuth flow more secure. For more information, see Configure Snowflake OAuth for custom clients.

Default: FALSE

OAUTH_USE_SECONDARY_ROLES = { IMPLICIT | NONE }

IMPLICIT: Default secondary roles set in the user properties are activated by default in the session being opened.
NONE: Default secondary roles are not supported in the session being opened.

Default: NONE

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

Comma-separated list of Snowflake roles that a user does not need to explicitly consent to using after authenticating (e.g. PRE_AUTHORIZED_ROLES_LIST = ('custom_role1', 'custom_role2')). The ACCOUNTADMIN, ORGADMIN, GLOBALORGADMIN, and SECURITYADMIN roles cannot be included in this list.

Note

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

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

Comma-separated list of Snowflake roles that a user cannot explicitly consent to using after authenticating. For example, BLOCKED_ROLES_LIST = ('custom_role1', 'custom_role2').

The ACCOUNTADMIN, ORGADMIN, GLOBALORGADMIN, and SECURITYADMIN roles are included in this list by default; however, if these roles should be removed for your account, ask your account administrator to send a request to Snowflake Support.

OAUTH_ISSUE_REFRESH_TOKENS = { TRUE | FALSE }

Boolean that specifies whether to allow the client to exchange a refresh token for an access token when the current access token has expired. If set to FALSE, a refresh token is not issued. User consent is revoked, and the user must confirm authorization again.

Default: TRUE

OAUTH_REFRESH_TOKEN_VALIDITY = integer

Integer that specifies how long refresh tokens should be valid (in seconds). This can be used to expire the refresh token periodically. Note that OAUTH_ISSUE_REFRESH_TOKENS must be set to TRUE.

Note that if your organization would like the minimum or maximum values lowered or raised, respectively, ask your account administrator to send a request to Snowflake Support.

Values:: 86400 (1 day) to 7776000 (90 days)
Default:: 7776000

NETWORK_POLICY = 'network_policy'

For more information, see Restricting network traffic for Snowflake OAuth.

network_policy is a string literal that you must enclose in single quotes. If the network policy name is case-sensitive or includes any special characters or spaces, then you must enclose the name in double quotes, and then enclose the double-quoted name in single quotes. For example, NETWORK_POLICY = '"Case-Sensitive Name"'.

OAUTH_CLIENT_RSA_PUBLIC_KEY = public_key1

指定 RSA 公钥。

OAUTH_CLIENT_RSA_PUBLIC_KEY_2 = public_key2

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

COMMENT = 'string_literal'

指定集成的注释。

默认：无值

访问控制要求

A role used to execute this operation must have the following privileges at a minimum:

权限	对象	备注
CREATE INTEGRATION	账户	Only the ACCOUNTADMIN role has this privilege by default. The privilege can be granted to additional roles as needed.

For instructions on creating a custom role with a specified set of privileges, see Creating custom roles.

For general information about roles and privilege grants for performing SQL actions on securable objects, see Overview of Access Control.

使用说明

关于元数据：

Attention

Customers should ensure that no personal data (other than for a User object), sensitive data, export-controlled data, or other regulated data is entered as metadata when using the Snowflake service. For more information, see Metadata fields in Snowflake.

The OR REPLACE and IF NOT EXISTS clauses are mutually exclusive. They can’t both be used in the same statement.
CREATE OR REPLACE <object> statements are atomic. That is, when an object is replaced, the old object is deleted and the new object is created in a single transaction.

示例

Tableau Desktop 示例¶

以下示例使用默认设置来创建 OAuth 集成：

CREATE SECURITY INTEGRATION td_oauth_int1
  TYPE = oauth
  ENABLED = true
  OAUTH_CLIENT = tableau_desktop;

View the integration settings using DESCRIBE INTEGRATION:

DESC SECURITY INTEGRATION td_oauth_int1;

以下示例使用在 10 小时（36000 秒）后过期的刷新令牌创建 OAuth 集成。该集成会阻止用户在使用 SYSADMIN 作为活动角色的情况下启动会话：

CREATE SECURITY INTEGRATION td_oauth_int2
  TYPE = oauth
  ENABLED = true
  OAUTH_CLIENT = tableau_desktop
  OAUTH_REFRESH_TOKEN_VALIDITY = 36000
  BLOCKED_ROLES_LIST = ('SYSADMIN');

Tableau Cloud 示例¶

以下示例使用默认设置来创建 OAuth 集成：

CREATE SECURITY INTEGRATION ts_oauth_int1
  TYPE = oauth
  ENABLED = true
  OAUTH_CLIENT = tableau_server;

View the integration settings using DESCRIBE INTEGRATION:

DESC SECURITY INTEGRATION ts_oauth_int1;

以下示例使用在 1 天（86400 秒）后过期的刷新令牌创建 OAuth 集成。该集成会阻止用户在使用 SYSADMIN 作为活动角色的情况下启动会话：

CREATE SECURITY INTEGRATION ts_oauth_int2
  TYPE = oauth
  ENABLED = true
  OAUTH_CLIENT = tableau_server
  OAUTH_REFRESH_TOKEN_VALIDITY = 86400
  BLOCKED_ROLES_LIST = ('SYSADMIN');

自定义客户端示例

以下示例创建了一个使用密钥对身份验证的 OAuth 集成。该集成允许刷新令牌，这些令牌将在 1 天（86400 秒）后过期。该集成会阻止用户在使用 SYSADMIN 作为活动角色的情况下启动会话：

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
  PRE_AUTHORIZED_ROLES_LIST = ('MYROLE')
  BLOCKED_ROLES_LIST = ('SYSADMIN');