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.

In this Topic:

## Syntax¶

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>'
[ EXTERNAL_OAUTH_JWS_KEYS_URL = '<string_literal>' ]
[ EXTERNAL_OAUTH_RSA_PUBLIC_KEY = <public_key1> ]
[ EXTERNAL_OAUTH_RSA_PUBLIC_KEY_2 = <public_key2> ]
[ EXTERNAL_OAUTH_AUDIENCE_LIST = ('<string_literal>') ]
[ EXTERNAL_OAUTH_ANY_ROLE_MODE = 'DISABLE | ENABLE | ENABLE_FOR_PRIVILEGE ]


SAML2

CREATE [ OR REPLACE ] SECURITY INTEGRATION [ IF NOT EXISTS ]
TYPE = SAML2
ENABLED = TRUE | FALSE
SAML2_ISSUER = '<string_literal>'
SAML2_SSO_URL = '<string_literal>'
SAML2_PROVIDER = '<string_literal>'
SAML2_X509_CERT = '<string_literal>'
[ SAML2_ENABLE_SP_INITIATED = TRUE | FALSE ]
[ SAML2_SNOWFLAKE_X509_CERT = '<string_literal>' ]
[ SAML2_SIGN_REQUEST = TRUE | FALSE ]
[ SAML2_REQUESTED_NAMEID_FORMAT = '<string_literal>' ]
[ SAML2_FORCE_AUTHN = TRUE | FALSE ]


SCIM

CREATE [ OR REPLACE ] SECURITY INTEGRATION [ IF NOT EXISTS]
<name>
TYPE = SCIM
SCIM_CLIENT = 'OKTA' | 'AZURE' | 'CUSTOM'
RUN_AS_ROLE = 'OKTA_PROVISIONER' | 'AAD_PROVISIONER' | 'GENERIC_SCIM_PROVISIONER'
[ NETWORK_POLICY ] = '<network_policy>'


Snowflake OAuth for partner applications

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


Snowflake OAuth for custom clients

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 ]
[ 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>' ]


## Parameters¶

### External OAuth¶

#### External OAuth 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 Requirements.

TYPE = EXTERNAL_OAUTH

Distinguishes the External OAuth integration from a Snowflake OAuth integration.

ENABLED = TRUE | FALSE

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

• TRUE allows the integration to run based on the parameters specified in the pipe definition.

• FALSE suspends the integration for maintenance. Any integration between Snowflake and a third-party service fails to work.

EXTERNAL_OAUTH_TYPE = OKTA | AZURE | PING_FEDERATE | CUSTOM

Specifies the OAuth 2.0 authorization server to be Okta, Microsoft Azure AD, Ping Identity PingFederate, or a Custom OAuth 2.0 authorization server.

EXTERNAL_OAUTH_ISSUER = 'string_literal'

Specifies the URL to define the OAuth 2.0 authorization server.

EXTERNAL_OAUTH_TOKEN_USER_MAPPING_CLAIM = 'string_literal'

Specifies which access token claim should be used to map the access token to a Snowflake user record. The type of the claim must be a string or an array of strings with a single entry.

EXTERNAL_OAUTH_SNOWFLAKE_USER_MAPPING_ATTRIBUTE = 'LOGIN_NAME | EMAIL_ADDRESS'

Indicates which Snowflake user record attribute should be used to map the access token to a Snowflake user record.

#### External OAuth Optional Parameters¶

EXTERNAL_OAUTH_JWS_KEYS_URL = 'string_literal'

EXTERNAL_OAUTH_RSA_PUBLIC_KEY = public_key1

Specifies a Base64-encoded RSA public key, without the -----BEGIN PUBLIC KEY----- and -----END PUBLIC KEY----- headers.

EXTERNAL_OAUTH_RSA_PUBLIC_KEY_2 = public_key2

Specifies a second RSA public key, without the -----BEGIN PUBLIC KEY----- and -----END PUBLIC KEY----- headers. Used for key rotation.

EXTERNAL_OAUTH_AUDIENCE_LIST = ('string_literal')

Specifies additional values that can be used for the access token’s audience validation on top of using the Customer’s Snowflake Account URL (i.e. <account>.<region>.snowflakecomputing.com).

Currently, multiple audience URLs can be specified for External OAuth Custom Clients only. Each URL must be enclosed in single quotes, with a comma separating each URL. For example:

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

EXTERNAL_OAUTH_ANY_ROLE_MODE = 'DISABLE | ENABLE | ENABLE_FOR_PRIVILEGE'

Specifies whether the OAuth client or user can use a role that is not defined in the OAuth access token.

• DISABLE does not allow the OAuth client or user to switch roles (i.e. use role <role>;). Default.

• ENABLE allows the OAuth client or user to switch roles.

• ENABLE_FOR_PRIVILEGE allows the OAuth client or user to switch roles only for a client or user with the USE_ANY_ROLE privilege. This privilege can be granted and revoked to one or more roles available to the user. For example:

grant USE_ANY_ROLE on integration external_oauth_1 to role1;

revoke USE_ANY_ROLE on integration external_oauth_1 from role1;


### SAML2¶

#### SAML2 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 Requirements.

TYPE = SAML2

Specify the type of integration:

• SAML2: Creates a security interface between Snowflake and the identity provider.

ENABLED = TRUE | FALSE

The Boolean that specifies whether to initiate operation of the integration or suspend it.

• TRUE allows the integration to run based on the parameters specified in the pipe definition.

• FALSE suspends the integration for maintenance. Any integration between Snowflake and a third-party service fails to work.

SAML2_ISSUER = 'string_literal'

The string containing the IdP EntityID / Issuer.

SAML2_SSO_URL = 'string_literal'

The string containing the IdP SSO URL, where the user should be redirected by Snowflake (the Service Provider) with a SAML AuthnRequest message.

SAML2_PROVIDER = 'string_literal'

The string describing the IdP.

One of the following: OKTA, ADFS, Custom.

SAML2_X509_CERT = 'string_literal'

The Base64 encoded IdP signing certificate on a single line without the leading -----BEGIN CERTIFICATE----- and ending -----END CERTIFICATE----- markers.

#### SAML2 Optional Parameters¶

SAML2_SP_INITIATED_LOGIN_PAGE_LABEL = 'string_literal'

The string containing the label to display after the Log In With button on the login page.

SAML2_ENABLE_SP_INITIATED = TRUE | FALSE

• TRUE displays the Log in With button on the login page.

• FALSE does not display the Log in With button on the login page..

SAML2_SNOWFLAKE_X509_CERT = 'string_literal'

The Base64 encoded self-signed certificate generated by Snowflake for use with Encrypting SAML Assertions and Signed SAML Requests.

You must have at least one of these features (encrypted SAML assertions or signed SAML responses) enabled in your Snowflake account to access the certificate value.

SAML2_SIGN_REQUEST = TRUE | FALSE

The Boolean indicating whether SAML requests are signed.

• TRUE allows SAML requests to be signed.

• FALSE does not allow SAML requests to be signed.

SAML2_REQUESTED_NAMEID_FORMAT = 'string_literal'

The SAML NameID format allows Snowflake to set an expectation of the identifying attribute of the user (i.e. SAML Subject) in the SAML assertion from the IdP to ensure a valid authentication to Snowflake. If a value is not specified, Snowflake sends the urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress value in the authentication request to the IdP.

Optional.

If you choose to specify the SAML NameID format, use one of the following values:

• urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified

• urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress

• urn:oasis:names:tc:SAML:1.1:nameid-format:X509SubjectName

• urn:oasis:names:tc:SAML:1.1:nameid-format:WindowsDomainQualifiedName

• urn:oasis:names:tc:SAML:2.0:nameid-format:kerberos

• urn:oasis:names:tc:SAML:2.0:nameid-format:persistent

• urn:oasis:names:tc:SAML:2.0:nameid-format:transient

SAML2_FORCE_AUTHN = TRUE | FALSE

The Boolean indicating whether users, during the initial authentication flow, are forced to authenticate again to access Snowflake. When set to TRUE, Snowflake sets the ForceAuthn SAML parameter to TRUE in the outgoing request from Snowflake to the identity provider.

• TRUE forces users to authenticate again to access Snowflake, even if a valid session with the identity provider exists.

• FALSE does not force users to authenticate again to access Snowflake.

Default: FALSE.

### SCIM¶

#### SCIM 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 Requirements.

TYPE = SCIM

Specify the type of integration:

• SCIM: Creates a security interface between Snowflake and a client that supports SCIM.

SCIM_CLIENT = 'OKTA' | 'AZURE' | 'CUSTOM'

Specify the SCIM client.

RUN_AS_ROLE = 'OKTA_PROVISIONER' | 'AAD_PROVISIONER' | 'GENERIC_SCIM_PROVISIONER'

Specify the SCIM role in Snowflake that owns any users and roles that are imported from the identity provider into Snowflake using SCIM.

• The values OKTA_PROVISIONER, AAD_PROVISIONER, and GENERIC_SCIM_PROVISIONER are case-sensitive and must always be capitalized.

#### SCIM Optional Parameters¶

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.

### Snowflake OAuth¶

#### Snowflake OAuth 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 Requirements.

TYPE = OAUTH

Specify the type of integration:

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

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.

• LOOKER: The Looker business intelligence tool.

#### Snowflake OAuth Optional Parameters¶

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.

Default FALSE. If a security integration is created without setting this parameter to TRUE, Snowflake sets the parameter to FALSE.

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

#### Snowflake OAuth Partner Application Parameters — Optional¶

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.

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

3600 (1 hour)

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

#### Snowflake OAuth Custom Client Parameters — Optional¶

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 Configure Snowflake 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

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) or a role with the global CREATE INTEGRATION privilege can execute this SQL command.

## Examples¶

### External OAuth¶

#### External OAuth Microsoft Azure AD Example¶

The following example creates an External OAuth security integration for a Microsoft Azure AD OAuth 2.0 authorization server.

create security integration external_oauth_azure_1
type = external_oauth
enabled = true
external_oauth_type = azure
external_oauth_token_user_mapping_claim = 'upn'


View the integration settings using DESCRIBE INTEGRATION:

DESC SECURITY INTEGRATION external_oauth_azure_1;


#### External OAuth and Okta Example¶

The following example creates an External OAuth security integration for an Okta OAuth 2.0 authorization server.

create security integration external_oauth_okta_1
type = external_oauth
enabled = true
external_oauth_type = okta
external_oauth_issuer = '<OKTA_ISSUER>'
external_oauth_jws_keys_url = '<OKTA_JWS_KEY_ENDPOINT>'
external_oauth_token_user_mapping_claim = 'sub'


View the integration settings using DESCRIBE INTEGRATION:

DESC SECURITY INTEGRATION external_oauth_okta_1;


### SAML2¶

#### SAML2 Example¶

The following example creates a Microsoft Active Directory Federation Services (ADFS) security integration with the two optional settings:

create security integration my_idp
type = saml2
enabled = true
saml2_issuer = 'https://example.com'
saml2_sso_url = 'http://myssoprovider.com'
saml2_x509_cert='my_x509_cert'
saml2_enable_sp_initiated = false
;


View the integration settings using DESCRIBE INTEGRATION:

DESC SECURITY INTEGRATION my_idp;


### SCIM¶

#### SCIM and Microsoft Azure AD Example¶

The following example creates a Microsoft Azure AD SCIM integration with the default settings:

View the integration settings using DESCRIBE INTEGRATION:

DESC SECURITY INTEGRATION aad_provisioning;


#### SCIM and Okta Example¶

The following example creates an Okta SCIM integration with the default settings:

View the integration settings using DESCRIBE INTEGRATION:

DESC SECURITY INTEGRATION okta_provisioning;


### Snowflake OAuth¶

#### Snowflake 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


#### Snowflake 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


#### Snowflake 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='https://localhost.com'
OAUTH_ISSUE_REFRESH_TOKENS = TRUE
OAUTH_REFRESH_TOKEN_VALIDITY = 86400
PRE_AUTHORIZED_ROLES_LIST = 'MYROLE'