Installation et configuration du connecteur via des commandes SQL¶

Configuration de OAuth¶

Vous pouvez configurer le Snowflake Connector for ServiceNow® afin qu’il utilise OAuth pour s’authentifier auprès de l’instance ServiceNow :

• Dans ServiceNow, vous devez configurer l’instance pour qu’elle prenne en charge l’utilisation de OAuth avec le flux d’accord de code.

• Dans le Snowflake Connector for ServiceNow® :

  • Le connecteur utilise une intégration de sécurité avec TYPE = API_AUTHENTICATION pour connecter Snowflake à l’instance ServiceNow.

    L’intégration de la sécurité spécifie l’ID de client ServiceNow OAuth, le secret du client et l’URL du point de terminaison pour l’authentification à l’instance ServiceNow.

  • Le connecteur utilise un objet secret Snowflake pour gérer les informations sensibles, y compris les informations d’authentification.

    Dans le cas de l’utilisation de OAuth pour l’authentification, le connecteur stocke le jeton d’actualisation ServiceNow OAuth, l’heure d’expiration du jeton d’actualisation et le nom de l’intégration de sécurité dans l’objet secret Snowflake.

Pour configurer le Snowflake Connector for ServiceNow® de sorte à utiliser OAuth, procédez comme suit :

1. Configurez votre instance ServiceNow pour utiliser OAuth avec le flux d’accord de code.

   • Si votre instance ServiceNow utilise déjà le flux d’octroi de code OAuth et si vous souhaitez utiliser cette instance avec le Snowflake Connector for ServiceNow®, notez l’ID du client, le secret du client et l’URL du point de terminaison qui correspond au jeton OAuth.

     Pour plus d’informations, voir Gérer les jetons OAuth. Après avoir pris note de ces informations, créez une intégration de sécurité à l’étape suivante.

   • Si vous souhaitez utiliser une instance ServiceNow différente, accédez à l’instance ou créez-la et configurez-la pour qu’elle utilise OAuth avec le flux d’accord de code comme indiqué dans Configurer OAuth et Créer un point de terminaison pour l’accès des clients à l’instance.

2. Créez un registre d’applications dans ServiceNow et utilisez-le pour configurer le connecteur.

   1. Connectez-vous à votre instance ServiceNow, puis sélectionnez Homepage.

   2. Recherchez OAuth, puis sélectionnez Application Registry.

   3. Sélectionnez New, puis sélectionnez Create an OAuth API endpoint for external clients.

      Une page de configuration du registre d’applications s’affiche, comme le montre l’image suivante :

      

   4. Dans ServiceNow, entrez un nom pour le registre d’applications OAuth dans le champ Name.

   5. Dans ServiceNow, dans Redirect URL field, entrez ce qui suit :

      https://apps-api.c1.<cloud_region_id>.<cloud>.app.snowflake.com/oauth/complete-secret
      

      Copy

      Où :

      cloud_region_id

      Spécifie l’identificateur de la région cloud de votre compte Snowflake.

      cloud

      Spécifie l’identificateur de la plate-forme Cloud (par exemple aws, azure ou gcp).

   6. Si nécessaire, dans ServiceNow, mettez à jour les valeurs des champs Refresh Token Lifespan et Access Token Lifespan.

      • Snowflake recommande de fixer la durée de vie du jeton d’accès à au moins 600 secondes.

      • Pour la durée de vie du jeton d’actualisation, indiquez une valeur de 7776000 (90 jours).

   7. Dans ServiceNow, sélectionnez Submit.

      Le registre d’applications OAuth apparaît dans la liste des registres d’applications.

   8. Dans ServiceNow, sélectionnez le registre d’applications que vous venez de créer.

      Notez que ServiceNow a généré des valeurs pour les champs Client ID et Client Secret. Vous utiliserez ces valeurs dans la section suivante lors de la création d’une intégration de sécurité.

Génération du jeton d’actualisation OAuth¶

Pour générer le jeton d’actualisation OAuth :

1. Assurez-vous d’avoir effectué les tâches décrites dans Configuration de OAuth.

2. Envoyez une requête HTTP au point de terminaison /oauth_token.do de votre instance ServiceNow, comme expliqué dans Exemple REST OAuth dans la documentation ServiceNow.

   Par exemple, si vous utilisez curl pour envoyer la requête HTTP :

   curl -d "grant_type=password" --data-urlencode "client_id=<client_id>" --data-urlencode "client_secret=<client_secret>" --data-urlencode "username=<username>" --data-urlencode "password=<password>" -X POST https://<instance_name>.service-now.com/oauth_token.do
   

   Copy

   Where

   instance_name

   Spécifie le nom de votre instance ServiceNow.

   client_id et client_secret

   Spécifiez les valeurs que vous avez obtenues lors de la configuration du point de terminaison ServiceNow.

   username et password

   Spécifiez les identifiants de connexion pour votre instance ServiceNow.

   Note

   L’exemple ci-dessus utilise l’indicateur de ligne de commande data-urlencode dans curl pour encoder en URL le secret du client, le nom d’utilisateur et le mot de passe dans la requête HTTP envoyée à ServiceNow.

   Si vous utilisez un autre outil pour envoyer la requête HTTP, assurez-vous que vous encodez ces valeurs en URL dans la requête.

   Le corps de la réponse HTTP contient un objet JSON. Récupérer le jeton d’actualisation du champ refresh_token de cet objet :

   {"access_token":"abcd1234","refresh_token":"cdef567","scope":"useraccount","token_type":"Bearer","expires_in":1799}
   

   Copy

Création d’une intégration de sécurité¶

Une intégration de sécurité est un objet Snowflake qui fournit une interface entre Snowflake et un service OAuth 2.0 tiers.

Utilisez la commande CREATE SECURITY INTEGRATION pour créer une intégration de sécurité comme indiqué dans l’exemple suivant :

CREATE SECURITY INTEGRATION <name>
 TYPE = API_AUTHENTICATION
 AUTH_TYPE = OAUTH2
 OAUTH_CLIENT_AUTH_METHOD = CLIENT_SECRET_POST
 OAUTH_CLIENT_ID = '<client_id>'
 OAUTH_CLIENT_SECRET = '<client_secret>'
 OAUTH_TOKEN_ENDPOINT = 'https://<my_instance>.service-now.com/oauth_token.do'
 ENABLED = TRUE;

Où :

name

Spécifie le nom de l’intégration de sécurité.

client_id

Spécifie la valeur du champ Client ID que vous avez obtenue à partir de ServiceNow dans la section précédente.

client_secret

Spécifie la valeur du champ Client Secret que vous avez obtenue à partir de ServiceNow dans la section précédente.

my_instance

Spécifie le nom de votre instance ServiceNow. Il s’agit de la première partie du nom d’hôte de votre instance ServiceNow. Par exemple, si l’URL de votre instance ServiceNow est :

https://myinstance.service-now.com

Copy

Le nom de votre instance serait myinstance.

Création d’un objet secret¶

Créez l’objet secret Snowflake que le Snowflake Connector for ServiceNow® utilise pour l’authentification.

Snowflake recommande d’utiliser un rôle dédié pour gérer l’objet secret, distinct du rôle ACCOUNTADMIN (le rôle que vous utilisez pour installer, configurer et exécuter le connecteur). Snowflake recommande également de stocker l’objet secret dans une base de données et un schéma dédiés. Notez que vous pouvez choisir n’importe quel rôle pour gérer le secret, et que vous pouvez choisir n’importe quelle base de données et n’importe quel schéma pour stocker le secret.

Pour créer un rôle personnalisé afin de gérer le secret, utilisez la commande CREATE ROLE. Pour plus d’informations sur les privilèges que vous pouvez accorder à un rôle, voir Privilèges de contrôle d’accès.

Les sections suivantes expliquent comment créer un objet secret stocké dans une base de données et un schéma distincts et géré par un rôle personnalisé.

Création d’un entrepôt¶

Snowflake recommande de créer un entrepôt dédié au connecteur. Un entrepôt dédié permet une meilleure gestion des coûts et un meilleur suivi des ressources. Pour faciliter le suivi des ressources, vous pouvez éventuellement ajouter une ou plusieurs balises à l’entrepôt dédié.

Pour l’entrepôt de connecteurs, Snowflake recommande d’utiliser un entrepôt multi-cluster de grande taille.

Pour créer un entrepôt de grande taille nommé servicenow_conn_warehouse, exécutez la commande suivante :

USE ROLE accountadmin;
CREATE WAREHOUSE servicenow_conn_warehouse WAREHOUSE_SIZE = LARGE;

Copy

Création d’une base de données et d’un schéma pour les données ServiceNow¶

Ensuite, créez une base de données et un schéma pour les données ServiceNow. Le Snowflake Connector for ServiceNow® ingère les données ServiceNow dans cette base de données et ce schéma.

Lors de la création de la base de données et du schéma, notez les points suivants :

• Les noms du schéma et de la base de données doivent être des identificateurs d’objets valides.

• Pour contrôler l’accès aux données ServiceNow ingérées dans Snowflake, vous pouvez accorder les privilèges sur le schéma aux rôles qui devraient être autorisés à accéder aux données.

Pour créer la base de données et le schéma, exécutez les commandes CREATE DATABASE et CREATE SCHEMA.

Par exemple, pour créer la base de données dest_db et le schéma dest_schema pour les données ServiceNow, exécutez les commandes suivantes :

USE ROLE accountadmin;
CREATE DATABASE dest_db;
CREATE SCHEMA dest_schema;

Copy

Création d’une intégration d’API pour communiquer avec l’instance ServiceNow¶

Ensuite, créez une intégration d’API pour communiquer avec l’instance ServiceNow. Exécutez la commande CREATE API INTEGRATION avec la syntaxe suivante :

CREATE API INTEGRATION <integration_name>
  API_ALLOWED_PREFIXES = ('https://<servicenow_instance_name>.service-now.com')
  ALLOWED_AUTHENTICATION_SECRETS = (<secret_name>)
  ENABLED = TRUE

Copy

Où :

integration_name

Spécifie le nom de l’intégration API. Le nom doit être un identificateur d’objet valide. Le nom doit être unique parmi les intégrations API de votre compte.

API_ALLOWED_PREFIXES = ('https://servicenow_instance_name.service-now.com')

Spécifie l’URL de votre instance ServiceNow. Cela limite l’utilisation de cette intégration d’API à l’instance avec l’URL spécifiée.

ALLOWED_AUTHENTICATION_SECRETS = (secret_name)

Spécifie la liste des noms des secrets dont l’utilisation est autorisée dans le cadre de l’intégration d’API.

Indiquez le nom de l’objet secret que vous avez créé dans Création d’un objet secret.

ENABLED = TRUE

Spécifie si cette intégration API est activée ou désactivée. Si l’intégration API est désactivée, aucune fonction externe qui en dépend ne fonctionne.

TRUE

Permet l’exécution de l’intégration en fonction des paramètres spécifiés dans l’intégration de définition.

FALSE

Suspend l’intégration pour la maintenance. Toute intégration entre Snowflake et un service tiers échoue.

Par exemple, pour créer l’intégration d’API nommée servicenow_api_integration pour l’instance ServiceNow nommée myinstance, exécutez la commande suivante :

USE ROLE accountadmin;
CREATE API INTEGRATION servicenow_api_integration
  API_ALLOWED_PREFIXES = ('https://myinstance.service-now.com')
  ALLOWED_AUTHENTICATION_SECRETS = (secretsdb.apiauth.servicenow_creds_pw)
  ENABLED = TRUE

Copy

Configuration de la journalisation pour le connecteur¶

Le Snowflake Connector for ServiceNow® utilise des tables d’événements pour stocker les journaux d’erreurs du connecteur. Pour mettre en place une table d’événement, suivez le guide Configuration d’une table d’événements. Si la table des événements n’est pas configurée, les informations relatives aux journaux et aux événements sont ignorées.

Création d’un rôle personnalisé pour le connecteur¶

Ensuite, créez un rôle personnalisé pour le connecteur et accordez-lui les privilèges nécessaires à l’exécution du connecteur.

Ce rôle permet au connecteur d’effectuer les opérations suivantes :

• Créer et gérer des tâches pour l’ingestion des données.

• Utiliser l’entrepôt dédié.

• Accéder au secret et à l’intégration d’API pour vous connecter à l’instance ServiceNow.

Le rôle est également le propriétaire des tables et des vues contenant les données ServiceNow ingérées par le connecteur.

Pour créer ce rôle et accorder les privilèges :

1. En utilisant le rôle système USERADMIN, exécutez la commande CREATE ROLE pour créer un rôle personnalisé qui détiendra les données. Par exemple, pour créer le rôle personnalisé connector_resources_provider pour la possession des données, exécutez les commandes suivantes :

   USE ROLE useradmin;
   CREATE ROLE connector_resources_provider;
   

   Copy

2. En utilisant le rôle ACCOUNTADMIN, exécutez la commande GRANT <privilèges> to ROLE pour accorder les privilèges suivants au rôle personnalisé :

   • EXECUTE TASK sur le compte

   • L’un des éléments suivants, mais pas les deux :

     • EXECUTE MANAGED TASK

       Accordez ce privilège si vous avez configuré le connecteur sans entrepôt dédié.

     • USAGE sur l’entrepôt que vous avez créé pour le connecteur.

       Accordez ce privilège si vous utilisez un entrepôt dédié pour le connecteur.

   • USAGE sur la base de données que vous avez créée pour les données ServiceNow

   • USAGE, CREATE TABLE, et CREATE VIEW sur le schéma que vous avez créé pour les données ServiceNow

   • USAGE sur l’intégration d’API que vous avez créée pour ServiceNow

   • USAGE sur la base de données que vous avez créée pour le secret

   • USAGE sur le schéma que vous avez créé pour le secret

   • USAGE sur le secret que vous avez créé

   Par exemple, pour accorder les privilèges suivants au rôle nommé connector_resources_provider :

   • EXECUTE TASK sur le compte

   • EXECUTE MANAGED TASK sur le compte

   • USAGE sur l’entrepôt servicenow_conn_warehouse

   • USAGE sur la base de données dest_db

   • USAGE, CREATE TABLE et CREATE VIEW sur le schéma dest_db.dest_schema

   • USAGE sur l’intégration servicenow_api_integration

   • USAGE sur la base de données secretsdb

   • USAGE sur le schéma secretsdb.apiauth

   • USAGE sur le secret secretsdb.apiauth.servicenow_creds_oauth_code secret

   Exécutez les commandes suivantes :

   USE ROLE accountadmin;
   
   GRANT EXECUTE TASK ON ACCOUNT TO ROLE connector_resources_provider;
   GRANT EXECUTE MANAGED TASK ON ACCOUNT TO ROLE connector_resources_provider;
   
   GRANT USAGE ON WAREHOUSE servicenow_conn_warehouse TO ROLE connector_resources_provider;
   
   GRANT USAGE ON DATABASE dest_db TO ROLE connector_resources_provider;
   GRANT USAGE ON SCHEMA dest_db.dest_schema TO ROLE connector_resources_provider;
   GRANT CREATE TABLE ON SCHEMA dest_db.dest_schema TO ROLE connector_resources_provider;
   GRANT CREATE VIEW ON SCHEMA dest_db.dest_schema TO ROLE connector_resources_provider;
   
   GRANT USAGE ON INTEGRATION servicenow_api_integration TO ROLE connector_resources_provider;
   
   GRANT USAGE ON DATABASE secretsdb TO ROLE connector_resources_provider;
   GRANT USAGE ON SCHEMA secretsdb.apiauth TO ROLE connector_resources_provider;
   GRANT USAGE ON SECRET secretsdb.apiauth.servicenow_creds_oauth_code TO ROLE connector_resources_provider;
   

   Copy

Après avoir installé le Snowflake Connector for ServiceNow®, vous accordez ce rôle au connecteur.

Bien qu’il soit recommandé de créer des rôles distincts et plus affinés pour accéder aux données ingérées après le début de l’ingestion, vous pouvez utiliser ce rôle pour interroger les données ingérées et vous pouvez l’étendre avec des privilèges supplémentaires. Inversement, la révocation des privilèges des rôles pour les objets requis par le connecteur ou la modification de la propriété des rôles sur les tables et les vues contenant des données ingérées n’est pas autorisée et entraînera l’interruption du connecteur.

Installation de l”Snowflake Connector for ServiceNow®¶

Pour installer le connecteur :

1. Créez une base de données pour l’instance de connecteur en utilisant Snowsight. Pour plus d’informations sur la création de la base de données, consultez Installation et configuration du connecteur avec Snowsight.

2. Naviguez jusqu’à la feuille de calcul SQL.

3. Connectez-vous en tant qu’utilisateur ayant le rôle ACCOUNTADMIN. Par exemple :

   USE ROLE ACCOUNTADMIN;
   

   Copy

4. Attribuez le rôle personnalisé du connecteur (le rôle que vous avez créé précédemment) à la base de données qui sert d’instance au connecteur.

   Par exemple, pour accorder le rôle nommé connector_resources_provider à la base de données my_connector_servicenow, exécutez la commande suivante :

   GRANT ROLE connector_resources_provider TO DATABASE my_connector_servicenow;
   

   Copy

5. Définir la propriété de la base de données FIREWALL_CONFIGURATION sur la base de données installée. Inclure le préfixe d’URL pour votre instance ServiceNow.

   Par exemple, si votre base de données s’appelle my_connector_servicenow et que le nom de l’instance ServiceNow est my-instance, exécutez la commande suivante :

   ALTER DATABASE my_connector_servicenow SET FIREWALL_CONFIGURATION = ('https://my-instance.service-now.com')
   

   Copy

6. Exécutez la commande USE DATABASE pour utiliser la base de données pour le connecteur. Par exemple :

   USE DATABASE my_connector_servicenow;
   

   Copy

7. Configurez la connexion à l’instance ServiceNow en utilisant la commande CALL pour appeler la procédure stockée nommée CONFIGURE_CONNECTION :

   CALL CONFIGURE_CONNECTION({
      'serviceNowUrl': '<servicenow_base_url>',
      'secret': '<secret_name>',
      'apiIntegrationName': '<api_integration_name>'
   })
   

   Copy

   Où :

   servicenow_base_url

   Spécifie l’URL de l’instance ServiceNow que le connecteur doit utiliser. L’URL doit avoir le format suivant :

   https://<servicenow_instance_name>.service-now.com
   

   Copy

   secret_name

   Spécifie le nom complet de l’objet secret contenant les identifiants de connexion pour s’authentifier auprès de ServiceNow (le secret que vous avez créé précédemment).

   Vous devez spécifier le nom complet de l’objet secret au format suivant :

   <database_name>.<schema_name>.<secret_name>
   

   Copy

   Les noms de la base de données, du schéma et du secret doivent être des identificateurs d’objets valides.

   api_integration_name

   Spécifie le nom de l’intégration d’API pour ServiceNow (l’intégration d’API que vous avez créée précédemment).

   Le nom de l’intégration doit être un identificateur d’objet valide.

   Par exemple, pour configurer la connexion à une instance ServiceNow qui :

   • Possède l’URL https://myinstance.service-now.com.

   • Utilise le secret stocké dans secretsdb.apiauth.servicenow_creds_oauth_code.

   • Utilise l’intégration d’API nommée servicenow_api_integration.

   Exécutez la commande suivante :

    CALL CONFIGURE_CONNECTION({
       'serviceNowUrl': 'https://myinstance.service-now.com',
       'secret': 'SECRETSDB.APIAUTH.SERVICENOW_CREDS_OAUTH_CODE',
       'apiIntegrationName': 'SERVICENOW_API_INTEGRATION'
   });
   

   Copy

   Si la connexion a été configurée avec succès, cette procédure stockée affiche le message suivant :

   Connection configured successfully
   

   Copy

   Note

   Une fois le connecteur configuré, il n’est pas possible de modifier le nom du secret transmis ni de l’intégration API. Le connecteur les référence par leur nom. Par conséquent, toute tentative de suppression ou de modification du nom de ces objets coupe le connecteur et l’empêche de fonctionner.

8. Démarrez le connecteur comme décrit dans Démarrage du Snowflake Connector for ServiceNow®.

La base de données nouvellement créée est une instance du connecteur et contient les éléments suivants :

• Procédures stockées que vous utilisez pour configurer le connecteur. Voir Configuration de l’ingestion de données à l’aide d’instructions SQL pour plus d’informations.

• Vues contenant les messages enregistrés et les statistiques pour le connecteur. Voir À propos de la surveillance du connecteur pour plus d’informations.

Démarrage et arrêt du Snowflake Connector for ServiceNow®¶

Les sections suivantes décrivent comment démarrer, arrêter et reprendre le connecteur.

CALL START_CONNECTOR(
  '<warehouse_name>',
  '<dest_db_schema>',
  '<name_of_journal_table>',
  '<connector_role>',
);

Successfully started the |SNC|. The connector can be configured now.

CALL RESUME_CONNECTOR();

Délégation de privilèges pour la configuration et la surveillance du Snowflake Connector for ServiceNow®¶

Après avoir installé le connecteur, seul le rôle ACCOUNTADMIN peut exécuter les procédures de configuration et accéder aux vues utilisées pour surveiller le connecteur.

Pour déléguer ces privilèges à un autre rôle, exécutez la commande GRANT IMPORTED PRIVILEGES ON DATABASE ... TO ROLE .... Cette commande utilise la syntaxe suivante :

GRANT IMPORTED PRIVILEGES ON DATABASE <connector_name> TO ROLE <connector_config_role>;

Où :

connector_name

Spécifie le nom de la base de données qui sert d’instance au connecteur.

connector_config_role

Spécifie le nom du rôle auquel doivent être accordés les privilèges de configuration et de surveillance du connecteur.

Par exemple, pour créer un rôle personnalisé nommé connector_config_role et lui accorder les privilèges nécessaires pour configurer et surveiller l’instance de connecteur nommée my_connector_servicenow, exécutez la commande suivante :

USE ROLE useradmin;
CREATE ROLE connector_config_role;

USE ROLE securityadmin;
GRANT IMPORTED PRIVILEGES ON DATABASE my_connector_servicenow TO ROLE connector_config_role;

Modification de l’entrepôt utilisé par le connecteur (facultatif)¶

Si vous souhaitez modifier l’entrepôt utilisé par le connecteur ou ajouter un entrepôt dédié, vous pouvez le faire en appelant :

CALL CONFIGURE_WAREHOUSE('<warehouse_name>');

Copy

Où :

warehouse_name

Spécifie le nom de l’entrepôt que le connecteur doit utiliser.

Pour configurer le connecteur afin qu’il fonctionne sans utiliser d’entrepôt dédié, saisissez une chaîne vide pour le nom de l’entrepôt.

Prochaines étapes¶

Après avoir installé et configuré le connecteur, effectuez les étapes décrites dans Configuration de l’ingestion de données pour vos données ServiceNow®.