Categories:
User & Security DDL (Third-Party Service Integrations)

CREATE SECURITY INTEGRATION

Creates a new security integration in the account or replaces an existing integration. An integration is a Snowflake object that provides an interface between Snowflake and third-party services.

A security integration enables clients that support OAuth to redirect users to an authorization page and generate access tokens (and optionally, refresh tokens) for access to Snowflake.

See also:
ALTER SECURITY INTEGRATION , DROP INTEGRATION , SHOW INTEGRATIONS

In this Topic:

Syntax

OAuth for partner applications
CREATE [ OR REPLACE ] SECURITY INTEGRATION [IF NOT EXISTS]
  <name>
  TYPE = OAUTH
  ENABLED = { TRUE | FALSE }
  OAUTH_CLIENT = <partner_application>
  [ OAUTH_ISSUE_REFRESH_TOKENS = TRUE | FALSE ]
  [ OAUTH_REFRESH_TOKEN_VALIDITY = <integer> ]
  [ BLOCKED_ROLES_LIST = ( '<role_name>' [ , '<role_name>' , ... ] ) ]
  [ COMMENT = '<string_literal>' ]
OAuth for custom clients
CREATE [ OR REPLACE ] SECURITY INTEGRATION [IF NOT EXISTS]
  <name>
  TYPE = OAUTH
  ENABLED = { TRUE | FALSE }
  OAUTH_CLIENT = CUSTOM
  OAUTH_CLIENT_TYPE = 'CONFIDENTIAL' | 'PUBLIC'
  OAUTH_REDIRECT_URI = '<uri>'
  [ OAUTH_ALLOW_NON_TLS_REDIRECT_URI = TRUE | FALSE ]
  [ OAUTH_ENFORCE_PKCE = TRUE | FALSE ]
  [ 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>' ]

Required Parameters

name

String that specifies the identifier (i.e. name) for the integration; must be unique in your account.

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 Syntax.

TYPE = OAUTH

Specify the type of integration:

  • OAUTH: Creates a security interface between Snowflake and a client that supports OAuth.
ENABLED = TRUE | FALSE

Specifies whether to initiate operation of the integration or suspend it.

  • TRUE enables the integration.
  • FALSE disables the integration for maintenance. Any integration between Snowflake and a third-party service fails to work.
OAUTH_CLIENT = CUSTOM | partner_application

Specify the client type:

  • 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 Online or Tableau Server.

OAuth Custom Client Parameters

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

OAUTH_CLIENT_TYPE = 'CONFIDENTIAL' | 'PUBLIC'
Specifies the type of client being registered. Snowflake supports both confidential and public clients. Confidential clients can store a secret. They run in a protected area where end users cannot access them. For example, a secured service deployed on the cloud could be a confidential client; whereas, a client running on a desktop or distributed through an app store could be a public client.
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.

Optional Parameters

OAuth Partner Application Parameters

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. 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.

When a refresh token expires, the application will need to direct the user through the authorization flow again to obtain a new refresh token.

The supported minimum, maximum, and default values are as follows:

Application Minimum Maximum Default
Tableau Desktop 60 (1 minute) 36000 (10 hours) 36000 (10 hours)
Tableau Server or Tableau Online 60 (1 minute) 7776000 (90 days) 7776000 (90 days)
Custom client 86400 (1 day) 7776000 (90 days) 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.

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. 'custom_role1', 'custom_role2'.

Note that the ACCOUNTADMIN 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.

COMMENT = 'string_literal'

String (literal) that specifies a comment for the integration.

Default: No value

OAuth Custom Client Parameters

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

Boolean that specifies whether Proof Key for Code Exchange (PKCE) should be required for the integration.

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 Configuring OAuth for Custom Clients.

Default: FALSE

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. 'custom_role1', 'custom_role2'). Note that the ACCOUNTADMIN and SECURITYADMIN roles cannot be included in this list.

Note

This parameter is supported for confidential clients only.

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. 'custom_role1', 'custom_role2'. Note that the ACCOUNTADMIN 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'
Specifies an existing network policy active for your account. The network policy restricts the list of user IP addresses when exchanging an authorization code for an access or refresh token and when using a refresh token to obtain a new access token. If this parameter is not set, the network policy for the account (if any) is used instead.
OAUTH_CLIENT_RSA_PUBLIC_KEY = public_key1
Specifies an RSA public key. For more information, see OAuth.
OAUTH_CLIENT_RSA_PUBLIC_KEY_2 = public_key2
Specifies a second RSA public key. Used for key rotation.
COMMENT = 'string_literal'

String (literal) that specifies a comment for the integration.

Default: No value

Usage Notes

  • Only account administrators (users with the ACCOUNTADMIN role) can execute this command.

Examples

OAuth Tableau Desktop Example

The following example creates an OAuth integration with the default settings:

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;

The following example creates an OAuth integration with refresh tokens that expire after 10 hours (36000 seconds). The integration blocks users from starting a session with SYSADMIN as the active role:

CREATE SECURITY INTEGRATION td_oauth_int2
  TYPE = OAUTH
  ENABLED = TRUE
  OAUTH_REFRESH_TOKEN_VALIDITY = 36000
  BLOCKED_ROLES_LIST = ('SYSADMIN');

OAuth Tableau Online or Tableau Server Example

The following example creates an OAuth integration with the default settings:

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;

The following example creates an OAuth integration with refresh tokens that expire after 1 day (86400 seconds). The integration blocks users from starting a session with SYSADMIN as the active role:

CREATE SECURITY INTEGRATION ts_oauth_int2
  TYPE = OAUTH
  ENABLED = TRUE
  OAUTH_CLIENT = TABLEAU_SERVER
  OAUTH_REFRESH_TOKEN_VALIDITY = 86400
  BLOCKED_ROLES_LIST = ('SYSADMIN');

OAuth Custom Client Example

The following example creates an OAuth integration that uses key pair authentication. The integration allows refresh tokens, which expire after 1 day (86400 seconds). The integration blocks users from starting a session with SYSADMIN as the active role:

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