Request security integrations with app specifications

This topic describes how to configure a Snowflake Native App to use app specifications to request access to security integrations in the consumer account. Security integrations allow an app to connect to third-party authentication providers such as OAuth.

Access third-party authentication providers from an app

To implement a third-party authentication service, Snowflake provides security integrations. A security integration allows an app to connect to a third-party authentication service such as OAuth.

Note

Snowflake Native Apps only support security integrations of type API_AUTHENTICATION. For more information, see CREATE SECURITY INTEGRATION (External API Authentication).

App specification workflow for security integrations

The general workflow for configuring an app to use a security integration is as follows:

  1. Providers configure automated granting of privileges for the app. This grants the app privileges to create a security integration.

    Note

    App specifications require that manifest_version = 2 be set in the manifest file.

  2. Providers add the CREATE INTEGRATION privilege to the manifest file.

  3. Providers add SQL statements to the setup script to create the following objects as required:

    Providers can add these commands directly in the setup script, which causes these objects to be created when the app is installed. Alternatively, these commands can be added to a stored procedure that is called at runtime to create these objects.

  4. Consumers approve information related to OAuth intergration when configuring the app. For more information on how consumers view and approve app specifications, see Approve connections to external resources using app specifications.

App specification definition for security integrations

For a security integration, the app specification definition contains the properties required to connect to a third-party provider. For OAuth, the app specification definition depends on the OAuth type. The following table lists the app specification definition for each type:

Security integration type

Values defined in the app specification

CLIENT_CREDENTIALS

  • OAUTH_TOKEN_ENDPOINT (required)

  • OAUTH_ALLOWED_SCOPES (required)

AUTHORIZATION_CODE_GRANT

  • OAUTH_TOKEN_ENDPOINT (required)

  • OAUTH_AUTHORIZATION_ENDPOINT (optional)

JWT

  • OAUTH_TOKEN_ENDPOINT (required)

  • OAUTH_AUTHORIZATION_ENDPOINT (optional)

Set the version of the manifest file

To enable automated granting of privileges for an app, set the version at the beginning of the manifest file as shown in the following example:

manifest_version: 2
Copy

Add the CREATE INTEGRATION privilege to the manifest file

To allow an app to create a security integration, add the CREATE INTEGRATION privilege to the manifest file as shown in the following example:

manifest_version: 2
...
privileges:
  - CREATE INTEGRATION
      description: "Allows the app to create security integrations to access external auth providers"
...
Copy

This entry in the privileges section of the manifest file specifies that the app uses a security integration. For the app to use automated granting of privileges, the manifest file also requires manifest_version: 2.

Add a security integration to the setup script

Security integrations allow an app to connect to a third-party authentication service like OAuth. To create a security integration for an app, add the CREATE SECURITY INTEGRATION (External API Authentication) command to the setup script as shown in the following example:

CREATE SECURITY INTEGRATION external_oauth_provider
  TYPE = API_AUTHENTICATION
  AUTH_TYPE = OAUTH2
  OAUTH_CLIENT_AUTH_METHOD = CLIENT_SECRET_POST
  OAUTH_CLIENT_ID = 'YOUR_CLIENT_ID'
  OAUTH_CLIENT_SECRET = 'YOUR_CLIENT_SECRET'
  OAUTH_GRANT = 'CLIENT_CREDENTIALS'
  OAUTH_TOKEN_ENDPOINT = 'https://login.microsoftonline.com/YOUR_TENANT_ID/oauth2/v2.0/token'
  OAUTH_ALLOWED_SCOPES = ('https://graph.microsoft.com/.default')
  ENABLED = TRUE;
Copy

This example shows how to create a security integration to connect to Microsoft SharePoint using OAuth with client credentials. For other supported methods of connecting to an OAuth provider, see CREATE SECURITY INTEGRATION (External API Authentication).

Create an app specification for a security integration

The following example shows how to create an app specification for a security integration using the CLIENT_CREDENTIALS OAuth type:

ALTER APPLICATION SET SPECIFICATION oauth_app_spec
  TYPE = SECURITY_INTEGRATION
  LABEL = 'Connection to an external OAuth provider'
  DESCRIPTION = 'Integrates an external identity provider in the app'
  OAUTH_TYPE = 'CLIENT_CREDENTIALS'
  OAUTH_TOKEN_ENDPOINT = 'https://login.microsoftonline.com/YOUR_TENANT_ID/oauth2/v2.0/token'
  OAUTH_ALLOWED_SCOPES = ('https://graph.microsoft.com/.default');
Copy

Note

The values you provide when creating the app specification must be the same as those you use when creating the security integration in the setup script.

For information on using other OAuth types, see ALTER APPLICATION SET SPECIFICATIONS.

Approve the app specification in the consumer account

After the provider configures the app to create the security integration and app specification, consumers can view the app specification and approve or decline it as necessary when configuring the app. For more information, see Approve connections to external resources using app specifications.

Language: English