Use app specifications to request external endpoints from consumers¶

Access external services from a Snowflake Native App¶

Some Snowflake Native Apps need to connect to resources that exist outside the Snowflake. Snowflake provides different objects depending on the type of external connection required.

When using automated granting of privileges, an app has the required privileges to create these objects when running the setup script. However, since these objects allow connections outside Snowflake, consumers must approve these connections when configuring the app.

App specifications allow a provider to specify what connection information the app requests. When the consumer installs the app, they review the app specification and approve or decline it as necessary.

App specification workflow¶

The general workflow for configuring and using an app specification is as follows:

1. Providers configure automated granting of privileges for the app. This allows consumers to give permission to an app to create the external access integration.

   Note

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

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

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

   • Network rule

   • External access integration

   • Security integration

   • App specification

   The setup script creates the app specification and other objects when the app is installed or upgraded, or at runtime.

4. When configuring the app, consumers approve the host ports and other external services. For more information, see Approve connections to external resources using app specifications.

Add the CREATE EXTERNAL ACCESS INTEGRATION privilege to the manifest file¶

To configure an app to request the CREATE EXTERNAL ACCESS INTEGRATION privilege, add the following code to the privileges section of the manifest file:

manifest_version: 2
...
privileges:
  - CREATE EXTERNAL ACCESS INTEGRATION:
      description: "Allows the app to create an external access integration to connect to an external service."
...

This entry in the privileges section of the manifest file specifies that the app uses an external access integration. For the app to use automated granting of privileges, the manifest file also requires manifest_version: 2 to be set.

Add a network rule and external access integration to the setup script¶

External access integrations are the Snowflake objects that enable access to specific external network locations. External access integrations contain a list of network rules that specify the external locations that an app can access.

To create a network rule for an app, add the CREATE NETWORK RULE command to the setup script as shown in the following example:

CREATE OR REPLACE NETWORK RULE setup.my_network_rule
 TYPE = HOST_PORT
 VALUE_LIST = ( 'example.com' )
 MODE = EGRESS;

The HOST_PORT and VALUE_LIST properties indicate that the network rule must point to a valid domain, port, or range of ports. When an app is installed or upgraded, a consumer will grant permission for the app to use these domains or ports.

To create an external access integration for an app, add the CREATE EXTERNAL ACCESS INTEGRATION command to the setup script as shown in the following example:

CREATE OR REPLACE EXTERNAL ACCESS INTEGRATION my_app_prefix_eai_rule
  ALLOWED_NETWORK_RULES = (setup.my_network_rule)
  ENABLED = TRUE;

This command creates an external access integration named my_app_prefix_eai_rule that allows the app to access external resources or endpoints. It uses the setup.my_network_rule network rule.

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, use the CREATE SECURITY INTEGRATION (External API Authentication) command 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;

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

Creating an app specification in the setup script¶

To create the app specification, providers add the ALTER APPLICATION SET SPECIFICATIONS command to the setup script.

ALTER APPLICATION SET SPECIFICATION eai_app_spec
        TYPE = EXTERNAL_ACCESS
        LABEL = 'Connection to an external API'
        DESCRIPTION = 'Access an API that exists outside Snowflake'

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');

Best practices for using app specifications¶

automated granting of privileges ensures that the app has the required privileges to create external access integrations. However, consumers can choose to decline the app specification that enables the connection to the external endpoints. When developing an app, providers must account for situations where app specifications might not be approved

For example, an app might ask to use multiple network ports for an external access integration, but the consumer might allow only one. The app should include logic to handle errors that occur if a network port is not available. Also, it is a best practice to catch any HTTP exceptions that might occur.

Using callback functions with app specifications¶

In some contexts, an app might need to know when the consumer has approved or declined an app specification. For example, the app might need to wait until an app specification is approved before creating an object.

To handle this situation, the Snowflake Native App Framework provides a mechanism that allows provider to define a callback stored procedure that runs when the consumer approves or declines an app specification.

Providers can add a stored procedure to the manifest file as shown in the following example:

lifecycle_callbacks:
  specification_action: callbacks.on_spec_update

This example shows how to a stored procedure named callbacks.on_spec_update to the manifest file. In the setup script, providers can add a stored procedure to as shown in the following example:

CREATE OR REPLACE PROCEDURE callbacks.on_spec_update (
  name STRING,
  status STRING,
  payload STRING)
  ...

This example shows the signature of a stored procedure called callbacks.on_spec_update. In the body of this procedure, providers include the code required to check the status of the app specification, create objects, and perform actions as required.