Utiliser les spécifications d’application pour demander des points de terminaison externes aux consommateurs¶

Accéder aux services externes à partir d’une Snowflake Native App¶

Certaines Snowflake Native Apps doivent se connecter à des ressources existantes en dehors de Snowflake. Snowflake fournit différents objets en fonction du type de connexion externe requis.

Lorsque vous utilisez l’octroi automatique de privilèges, une application dispose des privilèges requis pour créer ces objets lors de l’exécution du script d’installation. Cependant, étant donné que ces objets autorisent les connexions en dehors de Snowflake, les consommateurs doivent approuver ces connexions lors de la configuration de l’application.

Les spécifications d’application permettent à un fournisseur de spécifier les informations de connexion demandées par l’application. Lorsque le consommateur installe l’application, il examine la spécification d’application et l’approuve ou la refuse si nécessaire.

Workflow de la spécification d’application¶

Le workflow général de configuration et d’utilisation d’une spécification d’application est le suivant :

1. Les fournisseurs configurent l’octroi automatique de privilèges pour l’application. Cela permet aux consommateurs de donner l’autorisation à une application de créer l’intégration d’accès externe.

   Note

   Les spécifications d’application exigent que manifest_version = 2 soit défini dans le fichier manifeste.

2. Les fournisseurs ajoutent le CREATE EXTERNAL ACCESS INTEGRATION privilège vers le fichier manifeste.

3. Les fournisseurs ajoutent les instructions SQL au script d’installation pour créer les objets suivants en fonction des besoins :

   • Règle de réseau

   • Intégration d’accès externe

   • Intégration de sécurité

   • Spécification d’application

   Le script d’installation crée la spécification d’application et les autres objets lors de l’installation ou de la mise à niveau de l’application, ou lors de son exécution.

4. Lors de la configuration de l’application, les consommateurs approuvent les ports hôtes et les autres services externes. Pour plus d’informations, voir Approuver des connexions à des ressources externes à l’aide de spécifications d’application.

Ajoutez le privilège CREATE EXTERNAL ACCESS INTEGRATION au fichier manifeste.¶

Pour configurer une application afin qu’elle demande le privilège CREATE EXTERNAL ACCESS INTEGRATION, ajoutez le code suivant à la section privileges du fichier manifeste :

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

Cette entrée dans la section privileges du fichier manifeste indique que l’application utilise une intégration d’accès externe. Pour que l’application utilise l’octroi automatique de privilèges, le fichier manifeste requiert également que la manifest_version: 2 soit définie.

Ajouter une règle de réseau et une intégration d’accès externe au script d’installation¶

Les intégrations d’accès externes sont les objets Snowflake qui permettent d’accéder à des emplacements de réseau externes spécifiques. Les intégrations d’accès externes contiennent une liste de règles de réseau qui spécifient les emplacements externes auxquels une application peut accéder.

Pour créer une règle de réseau pour une application, ajoutez la commande CREATE NETWORK RULE au script d’installation comme indiqué dans l’exemple suivant :

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

Les propriétés HOST_PORT et VALUE_LIST indiquent que la règle de réseau doit pointer vers un domaine, un port ou une plage de ports valide. Lorsqu’une application est installée ou mise à niveau, un consommateur accorde l’autorisation à l’application d’utiliser ces domaines ou ports.

Pour créer une intégration d’accès externe pour une application, ajoutez la commande CREATE EXTERNAL ACCESS INTEGRATION au script d’installation comme indiqué dans l’exemple suivant :

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

Cette commande crée une intégration d’accès externe nommée my_app_prefix_eai_rule qui permet à l’application d’accéder à des ressources ou à des points de terminaison externes. Elle utilise la règle de réseau setup.my_network_rule.

Ajouter une intégration de sécurité au script d’installation¶

Les intégrations de sécurité permettent à une application de se connecter à un service d’authentification tiers comme OAuth. Pour créer une intégration de sécurité pour une application, utilisez la commande CREATE SECURITY INTEGRATION (authentification API externe) comme indiqué dans l’exemple suivant :

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;

Cet exemple montre comment créer une intégration de sécurité pour se connecter à Microsoft Sharepoint à l’aide de OAuth avec des identifiants de connexion client. Pour connaître les autres méthodes de connexion à un fournisseur OAuth prises en charge, consultez CREATE SECURITY INTEGRATION (authentification API externe).

Créer une spécification d’application dans le script d’installation¶

Pour créer la spécification d’application, les fournisseurs ajoutent la commande ALTER APPLICATION SET SPECIFICATIONS au script d’installation.

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

Bonnes pratiques pour l’utilisation des spécifications d’application¶

L’octroi automatique de privilèges garantit que l’application dispose des privilèges requis pour créer des intégrations d’accès externes. Toutefois, les consommateurs peuvent choisir de refuser la spécification d’application qui permet la connexion aux points de terminaison externes. Lors du développement d’une application, les fournisseurs doivent tenir compte des situations où les spécifications d’application peuvent ne pas être approuvées.

Par exemple, une application peut demander à utiliser plusieurs ports réseau pour une intégration d’accès externe, mais le consommateur peut n’en autoriser qu’un seul. L’application doit inclure une logique pour gérer les erreurs qui se produisent si un port réseau n’est pas disponible. De plus, il est recommandé de repérer toutes les exceptions HTTP qui pourraient se produire.

Utiliser des fonctions de rappel avec des spécifications d’application¶

Dans certains contextes, une application peut avoir besoin de savoir quand le consommateur a approuvé ou refusé une spécification d’application. Par exemple, l’application peut avoir besoin d’attendre qu’une spécification d’application soit approuvée avant de créer un objet.

Pour gérer cette situation, le Snowflake Native App Framework fournit un mécanisme qui permet au fournisseur de définir une procédure stockée de rappel qui s’exécute lorsque le consommateur approuve ou refuse une spécification d’application.

Les fournisseurs peuvent ajouter une procédure stockée au fichier manifeste comme indiqué dans l’exemple suivant :

lifecycle_callbacks:
  specification_action: callbacks.on_spec_update

Cet exemple montre comment ajouter une procédure stockée nommée callbacks.on_spec_update au fichier manifeste. Dans le script d’installation, les fournisseurs peuvent ajouter une procédure stockée comme indiqué dans l’exemple suivant :

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

Cet exemple montre la signature d’une procédure stockée appelée callbacks.on_spec_update. Dans le corps de cette procédure, les fournisseurs incluent le code nécessaire pour vérifier l’état de la spécification d’application, créer des objets et effectuer les actions nécessaires.