Agent de connecteur Microsoft Graph

  • Article

L’utilisation de connecteurs locaux nécessite l’installation du logiciel de l’agent de connecteur Microsoft Graph . Il permet un transfert de données sécurisé entre les données locales et les API de connecteur. Cet article vous guide tout au long de l’installation et de la configuration de l’agent.

Installation

Téléchargez la dernière version de l’agent de connecteur Microsoft Graph et installez le logiciel à l’aide de l’Assistant Configuration d’installation. Les notes de publication du logiciel de l’agent de connecteur sont disponibles ici

Vérifier la stratégie d’exécution

La stratégie d’exécution doit être définie pour autoriser l’exécution de scripts signés à distance. Si une stratégie au niveau de l’ordinateur ou du groupe restreint la même chose, l’installation de GCA échoue. Exécutez la commande suivante pour obtenir la stratégie d’exécution :

Get-ExecutionPolicy -List

Pour en savoir plus et définir la stratégie d’exécution appropriée, consultez Stratégie d’exécution.

À l’aide de la configuration recommandée de la machine, l’instance de l’agent de connecteur peut gérer jusqu’à trois connexions. Toutes les connexions au-delà peuvent dégrader les performances de toutes les connexions sur l’agent. Voici la configuration recommandée :

Si les serveurs proxy ou les pare-feu de votre organisation bloquent la communication avec des domaines inconnus, ajoutez les règles suivantes à la liste « autoriser » :

M365 Entreprise M365 GCC M365 GCCH
1. *.servicebus.windows.net 1. *.servicebus.usgovcloudapi.net 1. *.servicebus.usgovcloudapi.net
2. *.events.data.microsoft.com 2. *.events.data.microsoft.com 2. *.events.data.microsoft.com
3. *.office.com 3. *.office.com 3. *.office.com, *.office365.us
4. https://login.microsoftonline.com 4. https://login.microsoftonline.com 4. https://login.microsoftonline.com, https://login.microsoftonline.us
5. https://gcs.office.com/ 5. https://gcsgcc.office.com 5. https://gcs.office365.us/
6. https://graph.microsoft.com/ 6. https://graph.microsoft.com 6. https://graph.microsoft.com/, https://graph.microsoft.us/

Notes

L’authentification par proxy n’est pas prise en charge. Si votre environnement a un proxy qui nécessite une authentification, nous vous recommandons d’autoriser l’agent du connecteur à contourner le proxy.

Mise à niveau

L’agent de connecteur Graph peut être mis à niveau de deux manières :

  1. Téléchargement et installation manuelle de l’agent de connecteur Graph à partir du lien fourni dans la section d’installation.

  2. Cliquez sur le bouton « Mettre à niveau » disponible dans le volet de connexion, comme indiqué dans l’image : Exemple d’instantané de la mise à niveau de GCA en un clic à partir du volet de connexion.

Le bouton de mise à niveau n’est pas disponible pour les agents qui effectuent une mise à niveau de la version 1.x vers la version 2.x. Procédez comme suit si l’agent effectue une mise à niveau de la version 1.x vers la version 2.x :

  1. Téléchargez le programme d’installation à partir du lien fourni dans la section d’installation.

  2. Le programme d’installation vous demande d’installer le runtime .NET 8 Desktop, s’il n’est pas déjà installé.

  3. Autorisez la communication vers le point de terminaison *.office.com.

  4. Après l’installation, l’application de configuration GCA redémarre. Si GCA n’est pas inscrit, connectez-vous et poursuivez l’inscription.

  5. Si GCA est déjà inscrit, l’application de configuration GCA affiche le message de réussite suivant : Exemple d’instantané de réussite de la vérification d’intégrité sur la page de connexion GCA.

  6. Si vous observez des erreurs, suivez les étapes d’atténuation suggérées dans le message d’erreur et fermez & rouvrez l’application de configuration GCA.

  7. Si le message d’erreur indique : « Impossible de déterminer l’intégrité de l’agent. Si l’erreur persiste, contactez le support." , redémarrez GcaHostService(étapes mentionnées dans la section résolution des problèmes) et ouvrez à nouveau l’application de configuration GCA.

  8. Vous pouvez exécuter les vérifications à tout moment en fermant et en ouvrant l’application GCA Config ou en utilisant le bouton « Contrôle d’intégrité » en regard du bouton « Modifier » dans l’écran des détails d’inscription. Exemple d’instantané de réussite du contrôle d’intégrité sur la page d’inscription GCA.

Créer et configurer une application pour l’agent

Tout d’abord, connectez-vous et notez que le privilège minimal requis sur le compte est l’administrateur de recherche. L’agent vous demande ensuite de fournir des détails d’authentification. Suivez les étapes pour créer une application et générer les détails d’authentification requis.

Créer une application

  1. Accédez au portail Azure et connectez-vous avec les informations d’identification d’administrateur du locataire.

  2. Accédez à Id Microsoft Entra ->Inscriptions d’applications dans le volet de navigation, puis sélectionnez Nouvelle inscription.

  3. Fournissez un nom pour l’application, puis sélectionnez Inscrire.

  4. Notez l’ID d’application (client).

  5. Ouvrez autorisations d’API dans le volet de navigation et sélectionnez Ajouter une autorisation.

  6. Sélectionnez Microsoft Graph , puis Autorisations d’application.

  7. Recherchez les autorisations suivantes, puis sélectionnez Ajouter des autorisations.

    Permission Quand l’autorisation est-elle requise
    ExternalItem.ReadWrite.OwnedBy ou ExternalItem.ReadWrite.All Toujours
    ExternalConnection.ReadWrite.OwnedBy Toujours
    Directory.Read.All Requis pour le partage de fichiers, les connecteurs MS SQL et Oracle SQL

  8. Sélectionnez Accorder le consentement administrateur pour [TenantName] et confirmez en sélectionnant Oui.

  9. Vérifiez que les autorisations sont dans l’état « accordé ».

    Autorisations affichées comme accordées en vert sur la colonne de droite.

Configuration de l’authentification

Vous pouvez fournir des détails d’authentification à l’aide d’une clé secrète client ou d’un certificat. Suivez les étapes de votre choix.

Configuration de la clé secrète client pour l’authentification

  1. Accédez au portail Azure et connectez-vous avec les informations d’identification d’administrateur du locataire.

  2. Ouvrez Inscription de l’application à partir du volet de navigation et accédez à l’application appropriée. Sous Gérer, sélectionnez Certificats et secrets.

  3. Sélectionnez Nouvelle clé secrète client , puis sélectionnez une période d’expiration pour le secret. Copiez le secret généré et enregistrez-le, car il n’est plus affiché.

  4. Utilisez cette clé secrète client et l’ID d’application pour configurer l’agent. Les caractères alphanumériques sont acceptés. Vous ne pouvez pas utiliser d’espaces vides dans le champ Nom de l’agent.

Utilisation d’un certificat pour l’authentification

Il existe trois étapes simples pour utiliser l’authentification basée sur les certificats :

  1. Créer ou obtenir un certificat
  2. Charger le certificat sur le portail Azure
  3. Affecter le certificat à l’agent
Étape 1 : Obtenir un certificat

Vous pouvez utiliser le script pour générer un certificat auto-signé. Votre organisation peut ne pas autoriser les certificats auto-signés. Dans ce cas, utilisez ces informations pour comprendre les exigences et acquérir un certificat conformément aux stratégies de votre organisation.

$dnsName = "<TenantDomain like agent.onmicrosoft.com>" # Your DNS name
$password = "<password>" # Certificate password
$folderPath = "D:\New folder\" # Where do you want the files to get saved to? The folder needs to exist.
$fileName = "agentcert" # What do you want to call the cert files? without the file extension
$yearsValid = 10 # Number of years until you need to renew the certificate
$certStoreLocation = "cert:\LocalMachine\My"
$expirationDate = (Get-Date).AddYears($yearsValid)
$certificate = New-SelfSignedCertificate -DnsName $dnsName -CertStoreLocation $certStoreLocation -NotAfter $expirationDate -KeyExportPolicy Exportable -KeySpec Signature -KeyLength 2048 -KeyAlgorithm RSA -HashAlgorithm SHA256
$certificatePath = $certStoreLocation + '\' + $certificate.Thumbprint
$filePath = $folderPath + '\' + $fileName
$securePassword = ConvertTo-SecureString -String $password -Force -AsPlainText
Export-Certificate -Cert $certificatePath -FilePath ($filePath + '.cer')
Export-PfxCertificate -Cert $certificatePath -FilePath ($filePath + '.pfx') -Password $securePassword
Étape 2 : Charger le certificat sur le portail Azure

  1. Ouvrez l’application et accédez à la section Certificats et secrets dans le volet gauche.

  2. Sélectionnez Charger le certificat et chargez le fichier .cer.

  3. Ouvrez Inscription de l’application et sélectionnez Certificats et secrets dans le volet de navigation. Copiez l’empreinte numérique du certificat.

Liste des certificats d’empreinte numérique lorsque certificats et secrets sont sélectionnés dans le volet gauche.

Étape 3 : Affecter le certificat à l’agent

L’utilisation de l’exemple de script pour générer un certificat permet d’enregistrer le fichier PFX à l’emplacement identifié dans le script.

  1. Téléchargez le fichier pfx de certificat sur l’ordinateur agent.

  2. Double-cliquez sur le fichier pfx pour lancer la boîte de dialogue d’installation du certificat.

  3. Sélectionnez Ordinateur local pour l’emplacement du magasin lors de l’installation du certificat.

  4. Après avoir installé le certificat, ouvrez Gérer les certificats d’ordinateur via le menu Démarrer .

  5. Sélectionnez le certificat nouvellement installé sous Certificats personnels>.

  6. Sélectionnez et maintenez (ou cliquez avec le bouton droit) sur le certificat, puis sélectionnez Toutes les tâches>Gérer les clés privées Option.

  7. Dans la boîte de dialogue autorisations, sélectionnez Ajouter une option. Une nouvelle fenêtre s’affiche. Sélectionnez l’option « Emplacements » qui s’y trouve. Sélectionnez l’ordinateur sur lequel l’agent est installé parmi les emplacements répertoriés affichés, puis sélectionnez OK.

  8. Dans la boîte de dialogue de sélection de l’utilisateur, écrivez : NT Service\GcaHostService , puis sélectionnez OK. Ne sélectionnez pas le bouton Vérifier les noms .

  9. Sélectionnez OK dans la boîte de dialogue autorisations. L’ordinateur de l’agent est maintenant configuré pour que l’agent génère des jetons à l’aide du certificat.

Résolution des problèmes

Échec de l’installation

En cas d’échec de l’installation, vérifiez les journaux d’installation en exécutant : msiexec /i "< path to msi >\GcaInstaller.msi » /L*V "< destination path >\install.log ». Vérifiez que vous ne recevez aucune exception de sécurité. En règle générale, ces exceptions surviennent en raison de paramètres de stratégie incorrects. La stratégie d’exécution doit être signée à distance. Pour en savoir plus, consultez la section « Installation » de ce document.

Si les erreurs ne sont pas résolvables, envoyez un e-mail au support via MicrosoftGraphConnectorsFeedback@service.microsoft.com avec les journaux.

Échec de l’inscription

Si la connexion pour configurer l’application échoue et affiche l’erreur « Échec de la connexion, sélectionnez le bouton de connexion pour réessayer », même après la réussite de l’authentification du navigateur, ouvrez services.msc et vérifiez si GcaHostService est en cours d’exécution. S’il ne démarre pas, démarrez-le manuellement. Dans le Gestionnaire des tâches, accédez à l’onglet Services, vérifiez si GcaHostService est en cours d’exécution. Si ce n’est pas le cas, cliquez avec le bouton droit et démarrez le service.

Capture d’écran des services dans le Gestionnaire des tâches.

Lorsque le service ne parvient pas à démarrer avec l’erreur « Le service n’a pas démarré en raison d’un échec de connexion », vérifiez si le compte virtuel « NT Service\GcaHostService » est autorisé à se connecter en tant que service sur l’ordinateur. Consultez ce lien pour obtenir des instructions. Si l’option d’ajout d’un utilisateur ou d’un groupe est grisée dans stratégies locales\Attribution des droits de l’utilisateur, cela signifie que l’utilisateur qui tente d’ajouter ce compte n’a pas de privilèges d’administrateur sur cet ordinateur, ou qu’une stratégie de groupe le substitue. La stratégie de groupe doit être mise à jour pour permettre au service hôte de se connecter en tant que service.

Échec après l’inscription

Après l’inscription, certains paramètres locaux peuvent affecter la connectivité de l’agent.

L’agent est hors connexion

L’agent est considéré comme hors connexion s’il n’est pas en mesure de contacter les services du connecteur graph. Dans ce cas, procédez comme suit :

  1. Vérifier si l’agent est en cours d’exécution : connectez-vous à l’ordinateur sur lequel l’agent est installé et vérifiez s’il est en cours d’exécution. Dans le Gestionnaire des tâches, accédez à l’onglet Services, vérifiez si GcaHostService est en cours d’exécution. Si ce n’est pas le cas, cliquez avec le bouton droit et démarrez le service.

    Capture d’écran des services dans le Gestionnaire des tâches.

  2. Vérifiez si gcs.office.com de domaine est accessible. (Pour un locataire GCC, remplacez gcsgcc.office.com et, pour un locataire GCCHigh, remplacez gcs.office365.us, comme indiqué dans le tableau initial.) Procédez comme suit :

    • À partir de PowerShell, exécutez la commande suivante :
    tnc gcs.office.com -Port 443

    La réponse doit contenir la sortie « TcpTestSucceeded : True » comme indiqué :

    Capture d’écran de tnc.

    S’il est faux, vérifiez que le domaine est autorisé dans votre proxy/pare-feu et que les demandes transitent par le proxy.

    • Pour un test plus spécifique, ou si vous ne pouvez pas exécuter tnc parce que le test ping ICMP est bloqué dans votre réseau, exécutez la commande suivante :
    wget https://gcs.office.com/v1.0/admin/AdminDataSetCrawl/healthcheck

    La sortie doit contenir « StatusCode : 200 ».

    Capture d’écran de wget 200.

    S’il n’est pas 200, vérifiez que le domaine est autorisé dans votre proxy/pare-feu et que les demandes transitent par le proxy.

  3. Si les étapes ont réussi et que l’agent est toujours hors connexion, vérifiez les problèmes de proxy réseau dans les journaux GCA.

    • Les journaux GcaHostService se trouvent à l’emplacement donné (vous devrez peut-être accéder manuellement à ce chemin d’accès ; le copier-coller dans l’Explorateur de fichiers peut ne pas fonctionner) :
      1. Pour le système d’exploitation Windows Server 2016 : C :\Users\GcaHostService\AppData\Local\Microsoft\GraphConnectorAgent\HostService\logs
      2. Pour toutes les autres versions de système d’exploitation Windows prises en charge : C :\Windows\ServiceProfiles\GcaHostService\AppData\Local\Microsoft\GraphConnectorAgent\HostService\logs
    • Triez les fichiers journaux dans le dossier dans l’ordre inverse de « Heure de modification » et ouvrez les deux derniers fichiers.
    • Recherchez les messages d’erreur avec le texte suivant : « Aucune connexion n’a pu être établie, car la machine cible l’a refusée activement. »
      1. Cela indique qu’il existe un problème avec les paramètres réseau qui empêche le compte virtuel GcaHostService de contacter le https://gcs.office.com point de terminaison.
      2. Contactez votre équipe réseau/proxy pour autoriser le compte virtuel (NT Service\GcaHostService) à envoyer le trafic vers ce domaine.
      3. Vous pouvez vérifier que le problème est résolu si le fichier journal ne contient plus ces erreurs.

  4. Si aucune des étapes ne résout votre problème, contactez le support en envoyant un e-mail à MicrosoftGraphConnectorsFeedback@service.microsoft.comet fournissez les deux derniers fichiers journaux à partir de l’emplacement mentionné ci-dessus.

L’agent est inaccessible

Lors de la configuration de la connexion si l’agent est inaccessible, vous voyez cet écran :

Capture d’écran de l’agent inaccessible

À l’aide de l’espace de noms Service Bus fourni dans les détails de l’erreur, procédez comme suit pour résoudre les problèmes :

  1. À partir de PowerShell, exécutez la commande suivante :

    tnc <yournamespacename>.servicebus.windows.net -port 443

    La réponse doit contenir la sortie « TcpTestSucceeded : True » :

    Capture d’écran de tnc 2.

    S’il est faux, vérifiez que le domaine est autorisé dans votre proxy/pare-feu et que les demandes transitent par le proxy.

  2. Si vous ne pouvez pas exécuter la commande tnc, car la commande Ping ICMP est bloquée sur votre réseau, exécutez la commande suivante dans PowerShell :

    wget https://<yournamespacename>.servicebus.windows.net/

    La sortie doit contenir « StatusCode : 200 » :

    Capture d’écran de wget 2.

    S’il est faux, vérifiez que le domaine est autorisé dans votre proxy/pare-feu et que les demandes transitent par le proxy.

  3. Si aucune des étapes ne résout votre problème, contactez le support en envoyant un e-mail à MicrosoftGraphConnectorsFeedback@service.microsoft.comet fournissez les deux derniers fichiers journaux à partir de l’emplacement mentionné ci-dessus.

Mise à jour en cours

Cette erreur s’affiche lorsqu’une mise à jour est déjà en cours et que l’erreur doit disparaître au bout d’un maximum de 30 minutes.

Capture d’écran de la mise à jour en cours.

Si l’erreur persiste après 30 minutes, procédez comme suit :

  1. Vérifier si l’agent est en cours d’exécution : connectez-vous à l’ordinateur sur lequel l’agent est installé et vérifiez s’il est en cours d’exécution. Dans le Gestionnaire des tâches, accédez à l’onglet Services, vérifiez si GcaHostService est en cours d’exécution. Si ce n’est pas le cas, cliquez avec le bouton droit et démarrez le service. Capture d’écran des services dans le Gestionnaire des tâches 2.

  2. Si le problème persiste, contactez le support en envoyant un e-mail à MicrosoftGraphConnectorsFeedback@service.microsoft.comet fournissez les deux derniers fichiers journaux. Parcourez manuellement l’emplacement pour accéder aux journaux et le partager avec l’équipe - C :\Windows\System32\config\systemprofile\AppData\Local\Microsoft\GraphConnectorAgent\AgentUpdateApp\logs

Échec de connexion

Si l’action « Tester la connexion » échoue lors de la création d’une connexion et affiche l’erreur « Veuillez vérifier le nom d’utilisateur/mot de passe et le chemin de la source de données », même si le nom d’utilisateur et le mot de passe fournis sont corrects, vérifiez que le compte d’utilisateur dispose de droits de connexion interactifs sur l’ordinateur sur lequel l’agent de connecteur est installé. Vous pouvez consulter la documentation sur la gestion des stratégies d’ouverture de session pour vérifier les droits de connexion. Vérifiez également que la source de données et l’ordinateur de l’agent se trouvent sur le même réseau.