Overview of app specifications¶

Access external services from a Snowflake Native App¶

Some Snowflake Native Apps need to connect to resources that exist outside Snowflake. To handle connections to these resources, Snowflake provides different objects for different types of connections.

To access external services, Snowflake provides the following objects:

External access integrations:

Allow secure access to external network endpoints within a user-defined function or stored procedure. External access integrations use network rules to restrict access to specific external network locations.

Security integrations:

Allow secure access to third-party authentication providers such as OAuth. Security integrations provide secure authentication and access control.

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.

Using automated granting of privileges with app specifications has the following benefits:

• Consumers do not have to manually create the external access integration or security integrations required by the app and approve access to them using references.

• Providers do not have to write code that checks for the existence of the required privileges and objects during installation or upgrade.

Use app specifications to allow consumers to approve external connections¶

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

For information on using app specifications to request access to external endpoint access, see Request external access integrations (EAIs) with app specifications. For information on using app specifications to request access to OAuth integrations, see Request security integrations with app specifications. Request external access integrations (EAIs) with app specifications.

App specification definition¶

An app specification definition contains the properties that are required for the app to configure connections to resources outside of Snowflake. These properties are displayed to the consumer for approval. an external access integration or security integration. The app specification definition contains a subset of the metadata and properties of an external access integration or security integration.

For information about the app specification definition for security integrations, see App specification definition for security integrations.

For information about the app specification definition for external access integrations, see App specification definition for external access integrations.

The sequence numbers of an app specification¶

The sequence number is similar to a version number for the app specification. Sequence numbers are automatically incremented when a provider changes the definition of the app specification. The definition of an app specification includes configuration details and other required information. Fields that are not part of the definition, such as description, do not trigger an update to the sequence number.

Sequence numbers allow providers and consumers to identify different versions of an app specification. For example, if a provider adds a new configuration detail to the app specification definition, the sequence number is incremented. When the consumer views the app specification, they can see that the sequence number has changed, and they can review the updated app specification.

Best practices when 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.