Installer un Enterprise Connector
Prérequis, téléchargement, installation, enrôlement, mises à jour, migration et suppression de l'Enterprise Connector on-premises.
Cette page traite du volet logiciel : ce que vous installez dans votre propre réseau, comment vous l'enrôlez, le maintenez à jour et le supprimez à nouveau. Le volet console (création d'un connecteur, URL de provisionnement, statut, suppression) est décrit sous Enterprise Connectors.
Ce qui est installé
Une installation Windows héberge l'application agent ainsi qu'un ou plusieurs connecteurs. Ce sont deux choses distinctes :
| Composant | De quoi il s'agit | Fonctionnement |
|---|---|---|
| Application agent | La fenêtre d'administration que vous ouvrez sur la machine. Elle enrôle les connecteurs, conserve leur configuration, affiche le statut, les logs et les diagnostics. | À la demande, lancée par vous. |
| Service de broker local | Enregistré au premier lancement comme service Windows iec-nats. Il achemine la communication interne entre la fenêtre et les connecteurs installés. Lié uniquement à la machine locale. | En permanence, comme service Windows. |
| Service d'agent | Un service Windows par connecteur enrôlé, nommé iec-agent-<agent id>. Il maintient la connexion sortante vers la plateforme et effectue le travail proprement dit. | En permanence, comme service Windows. |
Comme chaque connecteur est un service Windows à part entière, les connecteurs continuent de fonctionner lorsque la fenêtre de l'application est fermée et redémarrent après un redémarrage de la machine. La fenêtre ne vous sert qu'à les configurer, les inspecter ou les mettre à jour.
Une même machine peut héberger plusieurs connecteurs, y compris des connecteurs de types différents et des connecteurs rattachés à des répertoires différents.
Prérequis
- Windows sur x64. Le programme d'installation et l'application nécessitent des droits d'administrateur local, et l'application demande une élévation à chaque lancement parce qu'elle gère des services Windows.
- HTTPS sortant uniquement. Le connecteur établit la connexion vers votre hôte de plateforme sur le port 443 (HTTPS et WebSocket sur TLS) et la maintient ouverte. Aucune règle de pare-feu entrante ni port publié n'est nécessaire de votre côté.
- Accessibilité du système source. Un connecteur d'authentification doit joindre votre contrôleur de domaine ou votre serveur LDAP, normalement sur le port 636 pour LDAPS ou 389 pour LDAP. Un connecteur de provisioning doit joindre la cible SCIM qu'il est censé desservir.
- Un compte de service pour le répertoire. Un connecteur d'authentification se lie à Active Directory ou LDAP avec un compte de lecture dédié (un compte disposant de droits d'écriture uniquement si vous activez la synchronisation ascendante ou la réécriture des mots de passe).
- Aucun accès entrant à la machine elle-même. La communication interne entre la fenêtre et les services est liée à la machine locale et refusée sur toute autre adresse.
Choisissez une machine allumée en permanence et proche du service d'annuaire, par exemple un serveur d'administration sur le même site. Pour la résilience, installez un second connecteur du même répertoire sur une autre machine plutôt qu'un second connecteur sur la même.
Remarque : le programme d'installation n'est pas encore signé, Windows SmartScreen affiche donc un avertissement au premier lancement. Vérifiez la somme de contrôle affichée à côté du téléchargement avant de poursuivre.
Télécharger le programme d'installation
- Dans la console, ouvrez Répertoires → Connecteurs d'entreprise et créez le connecteur que vous souhaitez enrôler (voir Enterprise Connectors).
- Ouvrez le connecteur que vous venez de créer. Tant qu'il n'est pas enrôlé, sa page propose Download for Windows avec la version et la somme de contrôle SHA-1 du programme d'installation.
- Téléchargez le programme d'installation et copiez-le sur la machine cible.
Si la carte de téléchargement n'apparaît pas, le service de téléchargement n'est pas configuré pour votre instance. Demandez le paquet d'installation à votre contact support.
Installer l'application
- Exécutez le programme d'installation sur la machine cible et confirmez la demande d'élévation. Il installe l'application pour tous les utilisateurs et crée un raccourci sur le bureau.
- Démarrez l'application. Au premier lancement, elle enregistre et démarre le service de broker local.
- L'application vous demande de définir un mot de passe au premier démarrage, puis le redemande à chaque démarrage suivant. Toute personne disposant d'un accès à la machine et de ce mot de passe peut gérer les connecteurs qui s'y trouvent : traitez-le comme un identifiant d'administration.
Le mot de passe protège uniquement la fenêtre d'administration locale. Il n'a aucun rapport avec votre compte de console et n'est pas utilisé pour la connexion à la plateforme.
Enrôler un connecteur
L'enrôlement relie l'installation locale à l'enregistrement de connecteur que vous avez créé dans la console.
- Dans la console, ouvrez le connecteur et copiez son URL de provisionnement. Elle n'est affichée qu'aux administrateurs autorisés à modifier le répertoire (et l'API de gestion ne la renvoie qu'aux clients disposant de
enterpriseConnectors.write), car le premier enrôlement définit la clé de chiffrement du répertoire. - Dans l'application, ouvrez Agents et choisissez Provision agent.
- Collez l'URL de provisionnement et validez.
L'application génère une paire de clés, l'échange contre les identifiants permanents du connecteur, installe le service du connecteur et le démarre. En quelques secondes, la console affiche le connecteur comme Ready.
L'URL de provisionnement est à usage unique et expire au bout de quelques jours. Un connecteur déjà enrôlé ne peut pas être enrôlé une seconde fois avec la même URL. Si l'URL a expiré, supprimez le connecteur en attente dans la console et créez-en un nouveau.
Interception TLS et autorités de certification privées
Si votre réseau termine et resigne le trafic TLS, ou si votre hôte de plateforme utilise un certificat émis par une autorité privée, dépliez les advanced TLS options pendant l'enrôlement :
- Custom CA certificates (PEM) permet de coller les certificats d'autorité auxquels le connecteur doit faire confiance en plus du magasin de certificats Windows. C'est la voie recommandée.
- Ignore invalid certificates désactive entièrement la vérification, pour l'enrôlement comme pour la connexion permanente du connecteur. Ne l'utilisez qu'à titre transitoire.
Les deux réglages peuvent être modifiés plus tard sur la page Identity de l'application. Voir Configurer et exploiter un Enterprise Connector.
Plusieurs connecteurs pour le même répertoire
Tous les connecteurs d'authentification d'un même répertoire doivent fonctionner avec la même paire de clés : le premier connecteur enrôlé établit la clé du répertoire, et l'enrôlement de tout connecteur ultérieur est refusé si sa clé diffère. Pour ajouter un second connecteur à un répertoire existant :
- Sur la machine qui exécute déjà un connecteur, ouvrez Identity, saisissez une phrase secrète et choisissez Export keypair. Conservez le bloc chiffré et la phrase secrète en lieu sûr.
- Dans la console, créez le second connecteur et copiez son URL de provisionnement.
- Sur la seconde machine, choisissez Provision agent, collez l'URL, dépliez keypair import et collez le bloc exporté avec sa phrase secrète.
La phrase secrète est la seule protection de la clé privée exportée et le seul moyen de rouvrir le bloc. Supprimez la copie exportée dès que le second connecteur fonctionne.
Déplacer un connecteur vers une autre machine
Utilisez les mêmes étapes d'export et d'import que ci-dessus, puis mettez l'ancienne installation hors service :
- Exportez la paire de clés sur l'ancienne machine.
- Créez un nouveau connecteur dans la console et enrôlez-le sur la nouvelle machine avec la paire de clés exportée.
- Vérifiez que le nouveau connecteur signale Ready et traite les connexions.
- Désinstallez le connecteur sur l'ancienne machine et supprimez son enregistrement dans la console.
Migrer un connecteur précédent
Si un connecteur de la version majeure précédente est installé sur la machine, la page Agents affiche une bannière Previous connector found. L'option Import previous connector reprend son enrôlement, sa paire de clés et ses paramètres de répertoire, puis arrête et supprime l'ancien service Windows. Le connecteur conserve son identité dans la console : ni nouvel enrôlement ni nouvelle URL de provisionnement ne sont nécessaires.
Tout ce qui n'a pas pu être repris est répertorié sous forme d'avertissement après l'import, par exemple un filtre de répertoire stocké dans un ancien format et qui doit être recréé sur la page Data source. Vérifiez les paramètres de la source de données et exécutez un test de connexion avant de considérer la migration comme terminée.
Rester à jour
Les mises à jour se font sur deux niveaux, tous deux gérés sur la page Update de l'application :
- La mise à jour de l'application concerne la fenêtre d'administration elle-même. Choisissez Download update, puis Install & restart. La fenêtre se ferme brièvement ; les services de connecteur continuent de fonctionner.
- Les mises à jour d'agent concernent les binaires des services. Chaque version de l'application embarque les binaires de connecteur correspondants : après une mise à jour de l'application, la liste Agents marque donc les connecteurs concernés avec update available. Choisissez Update pour chaque connecteur, ou utilisez la carte Agent updates de la page Update. Le service du connecteur redémarre dans le cadre de la mise à jour.
Lorsque plusieurs connecteurs desservent un même répertoire, mettez-les à jour un par un afin que les connexions continuent de fonctionner pendant le redémarrage. La page Release notes de l'application liste les changements de chaque version.
Démarrer, arrêter et redémarrer
La liste Agents propose Start, Stop et Restart pour chaque connecteur installé. Un arrêt est mémorisé : le connecteur reste arrêté au fil des redémarrages jusqu'à ce que vous le relanciez.
Tant qu'un connecteur d'authentification est arrêté, son répertoire n'a aucun chemin vers Active Directory ou LDAP, sauf si un autre connecteur de ce répertoire est en ligne. Les connexions des utilisateurs de ce répertoire échouent pendant cette période, et les synchronisations planifiées sont ignorées.
Désinstaller
Supprimer un seul connecteur
- Dans l'application, ouvrez Agents et choisissez Stop pour le connecteur. La désinstallation n'est proposée que pour un connecteur arrêté.
- Choisissez Uninstall. Le service Windows est arrêté et supprimé, et le dossier local du connecteur est effacé.
- Dans la console, supprimez l'enregistrement du connecteur sous Répertoires → Connecteurs d'entreprise.
Supprimer le dernier connecteur d'authentification d'un répertoire prive ce répertoire de toute connexion à sa source : les connexions et la synchronisation s'arrêtent jusqu'à l'enrôlement d'un autre connecteur. La clé partagée du répertoire subsiste après la suppression : un connecteur de remplacement doit donc être enrôlé avec la même paire de clés, exportée au préalable.
Supprimer l'installation complète
- Désinstallez d'abord chaque connecteur dans l'application, comme décrit ci-dessus. Le programme de désinstallation de l'application supprime l'application et le service de broker local, mais pas les services de connecteur encore enregistrés.
- Désinstallez l'application via Paramètres → Applications dans Windows.
- Supprimez les enregistrements de connecteur dans la console.
Dépannage
- SmartScreen bloque le programme d'installation. Comparez la somme de contrôle SHA-1 affichée dans la console avec le fichier téléchargé, puis poursuivez via Informations complémentaires → Exécuter quand même.
- L'enrôlement échoue avec un ticket expiré ou inconnu. L'URL de provisionnement est à usage unique et de courte durée. Supprimez le connecteur en attente dans la console, créez-en un nouveau et enrôlez-le avec sa nouvelle URL.
- L'enrôlement est refusé en raison d'une clé publique différente. Un autre connecteur du même répertoire a été enrôlé avec une paire de clés différente. Exportez la paire de clés depuis le connecteur en fonctionnement et importez-la lors de l'enrôlement.
- L'enrôlement échoue avec une erreur de certificat. Votre réseau intercepte le trafic TLS, ou le certificat de la plateforme provient d'une autorité privée. Collez les certificats de l'autorité sous les options TLS avancées.
- Le service du connecteur ne démarre pas. Ouvrez Insight → Logs dans l'application pour ce connecteur. Un service qui ne parvient pas à joindre la plateforme réessaie en continu : un échec persistant provient donc généralement d'une restriction de pare-feu ou de proxy sortant sur le port 443.
- Un service Windows est signalé comme marqué pour suppression. Fermez toute console Services ouverte ainsi que l'onglet Services du Gestionnaire des tâches, puis réessayez. Si l'état persiste, redémarrez la machine.
- La console affiche le connecteur hors ligne alors que le service fonctionne. Le connecteur fonctionne mais ne parvient pas à établir la connexion sortante. Vérifiez la page Status de l'application, puis les logs.
Voir aussi
- Enterprise Connectors pour créer, superviser et supprimer des connecteurs dans la console.
- Configurer et exploiter un Enterprise Connector pour la source de données, TLS, le statut, les logs et les diagnostics.
- Répertoires utilisateur pour les paramètres de répertoire qu'un connecteur d'authentification dessert.
Enterprise Connectors
Gérez les connecteurs sur site qui relient votre réseau à la plateforme pour l'authentification, la synchronisation et le provisionnement.
Configurer et exploiter un Enterprise Connector
Source de données, TLS, statut, logs et diagnostics dans l'application Enterprise Connector sur votre propre machine.