Exemple - Configurer l’accès externe pour les services dans une application avec des conteneurs¶

Ajouter une référence d’intégration d’accès externe au fichier manifeste¶

L’exemple suivant montre comment un fournisseur définit une intégration d’accès externe dans le fichier manifeste :

references:
  ...
  - my_external_access:
      label: "Default External Access Integration"
      description: "This EAI is required to access xyz.com"
      privileges:
        - USAGE
      object_type: EXTERNAL ACCESS INTEGRATION
      required_at_setup: true
      register_callback: config.REGISTER_EAI_CALLBACK
      configuration_callback: config.get_config_for_ref

Cet exemple spécifie les propriétés suivantes, entre autres, sous references :

• my_external_access : spécifie le nom de la référence externe.

  • privileges : répertorie les privilèges requis par l’intégration d’accès externe. Dans cet exemple, le privilège USAGE est requis.

  • object_type: EXTERNAL ACCESS INTEGRATION : indique une référence à une intégration d’accès externe.

  • required_at_setup : indique que le consommateur doit autoriser l’accès à l’objet avant que l’application puisse créer l’objet lorsqu’il est défini sur true.

  • register_callback : spécifie la procédure stockée de rappel utilisée pour enregistrer la référence auprès de l’application.

  • configuration_callback : spécifie la fonction de rappel de configuration pour le secret. Voir Ajouter la fonction configuration_callback au script d’installation pour plus d’informations.

Ajoutez une référence de secret au fichier manifeste.¶

L’exemple suivant montre comment un fournisseur définit un secret dans le fichier manifeste :

references:
 ...
 - consumer_secret:
     label: "Consumer secret"
     description: "Needed to authenticate with an external endpoint"
     privileges:
       - READ
     object_type: SECRET
     register_callback: config.register_my_secret
     configuration_callback: config.get_config_for_ref

Cet exemple spécifie les propriétés suivantes, entre autres, sous references :

• consumer_secret : spécifie le nom de la référence.

  • privileges : répertorie les privilèges requis par le secret. Dans cet exemple, le privilège READ est spécifié.

  • object_type: SECRET : indique que la référence est un secret.

  • register_callback : spécifie la procédure stockée de rappel utilisée pour enregistrer la référence auprès de l’application.

  • configuration_callback : spécifie la fonction de rappel de configuration pour le secret. Voir Ajouter la fonction configuration_callback au script d’installation pour plus d’informations.

Ajouter la fonction configuration_callback au script d’installation¶

Après avoir ajouté les références pour l’intégration du secret et de l’accès externe, vous devez ajouter la fonction configuration_callback au script d’installation. Pour créer une intégration ou un secret d’accès externe, l’application doit pouvoir déterminer les valeurs du port hôte, du type de secret, du point de terminaison de l’autorisation et du jeton pour OAuth, etc. La fonction configuration_callback fournit ces informations du compte du consommateur à l’application.

CREATE OR REPLACE PROCEDURE CONFIG.GET_CONFIG_FOR_REFERENCE(ref_name STRING)
RETURNS STRING
LANGUAGE SQL
AS
$$
BEGIN
 CASE (UPPER(ref_name))
   WHEN 'my_external_access' THEN
     RETURN '{
       "type": "CONFIGURATION",
       "payload":{
         "host_ports":["google.com"],
         "allowed_secrets" : "LIST",
         "secret_references":["CONSUMER_SECRET"]}}';
   WHEN 'consumer_secret' THEN
     RETURN '{
       "type": "CONFIGURATION",
       "payload":{
         "type" : "OAUTH2",
         "security_integration": {
           "oauth_scopes": ["https://www.googleapis.com/auth/analytics.readonly"],
           "oauth_token_endpoint": "https://oauth2.googleapis.com/token",
           "oauth_authorization_endpoint":
               "https://accounts.google.com/o/oauth2/auth"}}}';
  END CASE;
  RETURN '';
END;
$$;

Snowsight exécute cette procédure de rappel pour remplir la boîte de dialogue de configuration qui invite l’utilisateur à configurer les objets requis.

La procédure doit être attribuée à un rôle d’application pour être exécutée tel que montré dans l’exemple suivant :

GRANT USAGE ON PROCEDURE CONFIG.GET_CONFIG_FOR_REFERENCE(STRING)
  TO APPLICATION ROLE app_admin;

Bonnes pratiques lors de l’utilisation d’intégrations d’accès externes dans une application avec des conteneurs¶

Snowflake recommande les bonnes pratiques suivantes lors de l’utilisation d’intégrations d’accès externes dans une application avec des conteneurs :

• Toute référence aux intégrations d’accès externes qui sont spécifiées dans une commande CREATE SERVICE ou ALTER SERVICE doit être liée avant que les commandes ne soient exécutées dans le script d’installation. Ces commandes échouent lorsque la référence n’est pas liée.

• Toutes les références aux secrets spécifiés dans la spécification de service doivent également être liées avant que les commandes CREATE SERVICE ou ALTER SERVICE soient exécutées dans le script d’installation. Ces commandes échouent lorsque la référence n’est pas liée.

• Si vous renvoyez une charge utile de type ERROR dans la fonction configuration_callback, les fournisseurs doivent renvoyer un message d’erreur informatif qui aide le consommateur à comprendre la cause de l’erreur et comment la résoudre. Par exemple :

  • S’il y a une erreur dans l’application

  • Si la référence n’est pas encore requise

  • Si la référence n’est pas prête à être autorisée.

• Si la fonction configuration_callback contient des références avec la propriété required_at_setup définie sur TRUE, la fonction configuration_callback doit aboutir au moment de la configuration. Dans ce contexte, la fonction configuration_callback ne peut pas dépendre des informations fournies par le consommateur.

• Lorsque vous utilisez une référence à une intégration d’accès externe avec un service, envisagez de créer le service à l’aide de ALLOWED_AUTHENTICATION_SECRETS = ALL si l’application nécessite des secrets fournis par le consommateur. Cela simplifie la gestion d’un secret au sein d’une intégration d’accès externe.

• Si une application n’a besoin d’atteindre que des points de terminaison spécifiques et ne nécessite aucun secret, utilisez ALLOWED_AUTHENTICATION_SECRETS = NONE. NONE est la valeur par défaut. Voir CREATE EXTERNAL ACCESS INTEGRATION pour plus d’informations.

• Si l’application doit mettre à jour une référence, commencez par dissocier la référence, puis demandez au consommateur de créer et de lier un nouvel objet à la référence. Un consommateur peut choisir de modifier et de lier un objet existant. Voir CREATE EXTERNAL ACCESS INTEGRATION.