Request external access integrations (EAIs) with app specifications¶

Access to external endpoints from an app¶

To access an external endpoint, an app must create a network rule and an external access integration. An external access integration uses network rules to restrict access to specific external network locations. Network rules define the external endpoints that an app can access.

To configure an app to use an external access integration:

• Use automated granting of privileges to request privileges from the consumer to create an external access integration.

• Add an external access integration to an app.

• Use application specifications to request permissions from the consumer to connect to an external endpoint.

App specification workflow for external access integrations¶

The general workflow for configuring an app to use an external access integration 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

   • 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 on how consumers view and approve app specifications, see Approve connections to external resources using app specifications.

App specification definition for external access integrations¶

For an external access integration, the app specification definition contains the following entries:

• HOST_PORTS: A list of host ports defined in the network rule that the app requires.

• PRIVATE_HOST_PORTS: A list of private host ports that allow private connectivity to resources outside Snowflake.

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

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

The CREATE EXTERNAL ACCESS INTEGRATION privilege allows the app to create an external access integration during installation or upgrade. 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."
...

Using manifest_version: 2, when the app is installed or upgraded, Snowflake automatically grants the CREATE EXTERNAL ACCESS INTEGRATION privilege to the app.

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.

Create an external access integration¶

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;

Create a user-defined function to access the external endpoint¶

After creating the external access integration, the setup script can create user-defined functions and stored procedures that use it to connect to the endpoints defined in the network rule.

The following example shows a user-defined function that uses the my_app_prefix_eai_rule external access integration.

CREATE OR REPLACE FUNCTION setup.EXTERNAL_ACCESS_UDF(hostname STRING)
  RETURNS STRING
  LANGUAGE JAVA
  HANDLER='TestHostNameLookup.compute'
  EXTERNAL_ACCESS_INTEGRATIONS = (my_app_prefix_eai_rule)
  AS
  '
      import java.net.InetAddress;
      import java.net.UnknownHostException;
      class TestHostNameLookup {{
          public static String compute(String hostname) throws Exception {{
              InetAddress addr = null;
              try {
                  addr = InetAddress.getByName(hostname);
              } catch(UnknownHostException ex) {
                  return "Hostname lookup failed";
              }
              return "Hostname lookup successful";
          }
      }
';
GRANT USAGE ON FUNCTION setup.EXTERNAL_ACCESS_UDF(STRING)
  TO APPLICATION ROLE app_public;

This function sets the value of the EXTERNAL_ACCESS_INTEGRATIONS to the external access integration created previously.

This function uses the InetAddress Java package to look up the hostname passed to the procedure. The hostname provided must match one the values provided in the VALUE_LIST property of the network rules used by the external access integration.

Create an app specification for an external access integration¶

The following example shows how to create an app specification for an external access integration:

ALTER APPLICATION SET SPECIFICATION eai_app_spec
        TYPE = EXTERNAL_ACCESS
        LABEL = 'Connection to an external API'
        DESCRIPTION = 'Access an API that exists outside Snowflake'
  HOST_PORTS = ('example.com')

This command creates an app specification named eai_app_spec.

Approve the app specification in the consumer account¶

After the provider configures the app to create the network rule, external access 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.