Installare un Enterprise Connector
Requisiti, download, installazione, registrazione, aggiornamenti, migrazione e rimozione dell'Enterprise Connector on-premises.
Questa pagina tratta il lato software: che cosa si installa nella propria rete, come lo si registra, come lo si mantiene aggiornato e come lo si rimuove. Il lato console (creazione del connettore, URL di provisioning, stato, eliminazione) è descritto in Enterprise Connectors.
Che cosa viene installato
Una singola installazione Windows ospita l'applicazione agent e uno o più connettori. Sono elementi distinti:
| Componente | Che cos'è | Esecuzione |
|---|---|---|
| Applicazione agent | La finestra di gestione che si apre sulla macchina. Registra i connettori, ne conserva la configurazione e mostra stato, log e diagnostica. | Su richiesta, avviata dall'amministratore. |
| Servizio broker locale | Registrato al primo avvio come servizio Windows iec-nats. Trasporta la comunicazione interna tra la finestra e i connettori installati. Associato esclusivamente alla macchina locale. | In modo permanente, come servizio Windows. |
| Servizio agent | Un servizio Windows per ogni connettore registrato, denominato iec-agent-<agent id>. Mantiene la connessione in uscita verso la piattaforma e svolge il lavoro effettivo. | In modo permanente, come servizio Windows. |
Poiché ogni connettore è un servizio Windows a sé stante, i connettori restano in esecuzione quando la finestra dell'applicazione viene chiusa e ripartono dopo un riavvio. La finestra serve soltanto per configurarli, controllarli o aggiornarli.
Una macchina può ospitare più connettori, anche di tipo diverso e riferiti a directory diverse.
Requisiti
- Windows su x64. L'installer e l'applicazione richiedono diritti di amministratore locale e l'applicazione richiede l'elevazione dei privilegi a ogni avvio, perché gestisce servizi Windows.
- Solo HTTPS in uscita. Il connettore apre la connessione verso l'host della piattaforma sulla porta 443 (HTTPS e WebSocket su TLS) e la mantiene aperta. Sul lato dell'organizzazione non serve alcuna regola firewall in entrata né alcuna porta pubblicata.
- Raggiungibilità del sistema di origine. Un connettore di autenticazione deve raggiungere il domain controller o il server LDAP, normalmente sulla porta 636 per LDAPS o 389 per LDAP. Un connettore di provisioning deve raggiungere la destinazione SCIM che dovrà servire.
- Un account di servizio per la directory. Un connettore di autenticazione si collega ad Active Directory o LDAP con un account di sola lettura dedicato (un account con diritti di scrittura solo se si abilita la sincronizzazione upstream o la riscrittura delle password).
- Nessun accesso in entrata alla macchina stessa. La comunicazione interna tra finestra e servizi è associata alla macchina locale e viene rifiutata su qualsiasi altro indirizzo.
Scegliere una macchina sempre accesa e vicina al servizio di directory, ad esempio un server di gestione nella stessa sede. Per la resilienza è preferibile installare un secondo connettore della stessa directory su un'altra macchina anziché un secondo connettore sulla stessa.
Nota: l'installer non è ancora firmato digitalmente, quindi Windows SmartScreen mostra un avviso al primo avvio. Verificare il checksum indicato accanto al download prima di procedere.
Scaricare l'installer
- Nella console, aprire Directory → Enterprise Connectors e creare il connettore da registrare (vedere Enterprise Connectors).
- Aprire il connettore appena creato. Finché non è registrato, la sua pagina offre Download for Windows insieme alla versione e al checksum SHA-1 dell'installer.
- Scaricare l'installer e copiarlo sulla macchina di destinazione.
Se la scheda di download non viene mostrata, il servizio di download non è configurato per questa istanza. Richiedere il pacchetto di installazione al proprio contatto di supporto.
Installare l'applicazione
- Eseguire l'installer sulla macchina di destinazione e confermare la richiesta di elevazione dei privilegi. L'installazione avviene per tutti gli utenti e crea un collegamento sul desktop.
- Avviare l'applicazione. Al primo avvio registra e avvia il servizio broker locale.
- Al primo avvio l'applicazione chiede di impostare una password e la richiede a ogni avvio successivo. Chi dispone dell'accesso alla macchina e di questa password può gestire i connettori presenti, quindi va trattata come una credenziale amministrativa.
La password protegge esclusivamente la finestra di gestione locale. Non ha alcun rapporto con l'account della console e non viene utilizzata per la connessione alla piattaforma.
Registrare un connettore
La registrazione collega l'installazione locale al record del connettore creato nella console.
- Nella console, aprire il connettore e copiare il relativo URL di provisioning. Viene mostrato solo agli amministratori autorizzati a modificare la directory (e restituito dall'API di gestione solo ai client con
enterpriseConnectors.write), poiché la prima registrazione imposta la chiave di cifratura della directory. - Nell'applicazione, aprire Agents e scegliere Provision agent.
- Incollare l'URL di provisioning e inviare il modulo.
L'applicazione genera una coppia di chiavi, la scambia con le credenziali permanenti del connettore, installa il servizio del connettore e lo avvia. Nel giro di pochi secondi la console mostra il connettore come Ready.
L'URL di provisioning è monouso e scade dopo alcuni giorni. Un connettore già registrato non può essere registrato una seconda volta con lo stesso URL. Se l'URL è scaduto, eliminare il connettore in sospeso nella console e crearne uno nuovo.
Intercettazione TLS e autorità di certificazione private
Se la rete termina e rifirma il traffico TLS, oppure se l'host della piattaforma utilizza un certificato di un'autorità privata, espandere le advanced TLS options durante la registrazione:
- Custom CA certificates (PEM) consente di incollare i certificati delle autorità a cui il connettore deve dare fiducia in aggiunta all'archivio certificati di Windows. È il percorso consigliato.
- Ignore invalid certificates disattiva completamente la verifica, sia per la registrazione sia per la connessione permanente del connettore. Utilizzarlo solo come misura temporanea.
Entrambe le impostazioni possono essere modificate in seguito nella pagina Identity dell'applicazione. Vedere Configurare e gestire un Enterprise Connector.
Più connettori per la stessa directory
Tutti i connettori di autenticazione di una directory devono funzionare con la stessa coppia di chiavi: il primo connettore che si registra fissa la chiave della directory e la registrazione di ogni connettore successivo viene rifiutata se la sua chiave è diversa. Per aggiungere un secondo connettore a una directory esistente:
- Sulla macchina che esegue già un connettore, aprire Identity, inserire una passphrase e scegliere Export keypair. Conservare il blocco cifrato e la passphrase in un luogo sicuro.
- Nella console, creare il secondo connettore e copiare il relativo URL di provisioning.
- Sulla seconda macchina, scegliere Provision agent, incollare l'URL, espandere keypair import e incollare il blocco esportato insieme alla passphrase.
La passphrase è l'unica protezione della chiave privata esportata e l'unico modo per riaprire il blocco. Eliminare la copia esportata non appena il secondo connettore è in funzione.
Spostare un connettore su un'altra macchina
Utilizzare gli stessi passaggi di esportazione e importazione descritti sopra, quindi dismettere la vecchia installazione:
- Esportare la coppia di chiavi sulla vecchia macchina.
- Creare un nuovo connettore nella console e registrarlo sulla nuova macchina con la coppia di chiavi esportata.
- Verificare che il nuovo connettore riporti Ready e gestisca gli accessi.
- Disinstallare il connettore sulla vecchia macchina ed eliminarne il record nella console.
Migrare un connector precedente
Se sulla macchina è installato un connector della versione principale precedente, la pagina Agents mostra un banner Previous connector found. Scegliendo Import previous connector vengono trasferiti la registrazione, la coppia di chiavi e le impostazioni della directory, dopodiché il vecchio servizio Windows viene arrestato e rimosso. Il connettore mantiene la propria identità nella console, quindi non servono una nuova registrazione né un nuovo URL di provisioning.
Tutto ciò che non è stato possibile trasferire viene elencato come avviso al termine dell'importazione, ad esempio un filtro di directory memorizzato in un vecchio formato che deve essere ricreato nella pagina Data source. Controllare le impostazioni dell'origine dati ed eseguire un test di connessione prima di considerare conclusa la migrazione.
Mantenere tutto aggiornato
Gli aggiornamenti sono su due livelli, entrambi gestiti nella pagina Update dell'applicazione:
- L'aggiornamento dell'applicazione riguarda la finestra di gestione stessa. Scegliere Download update e poi Install & restart. La finestra si chiude brevemente; i servizi dei connettori restano in esecuzione.
- Gli aggiornamenti degli agent riguardano i binari del servizio. Ogni versione dell'applicazione include i binari dei connettori corrispondenti, quindi dopo un aggiornamento dell'applicazione l'elenco Agents contrassegna i connettori interessati con update available. Scegliere Update per singolo connettore oppure utilizzare la scheda Agent updates nella pagina Update. Il servizio del connettore si riavvia nel corso dell'aggiornamento.
Quando più connettori servono la stessa directory, aggiornarne uno alla volta, in modo che gli accessi continuino a funzionare durante il riavvio. La pagina Release notes dell'applicazione elenca le modifiche di ogni versione.
Avviare, arrestare e riavviare
L'elenco Agents offre Start, Stop e Restart per ogni connettore installato. L'arresto viene memorizzato: il connettore resta arrestato anche dopo un riavvio della macchina, finché non viene riavviato manualmente.
Finché un connettore di autenticazione è arrestato, la sua directory non ha alcun percorso verso Active Directory o LDAP, a meno che un altro connettore della stessa directory non sia online. In quel periodo gli accessi degli utenti di quella directory non riescono e le sincronizzazioni pianificate vengono saltate.
Disinstallare
Rimuovere un singolo connettore
- Nell'applicazione, aprire Agents e scegliere Stop per il connettore. La disinstallazione viene offerta solo per un connettore arrestato.
- Scegliere Uninstall. Il servizio Windows viene arrestato e rimosso e la cartella locale del connettore viene eliminata.
- Nella console, eliminare il record del connettore in Directory → Enterprise Connectors.
La rimozione dell'ultimo connettore di autenticazione di una directory lascia quella directory senza connessione alla propria origine: accessi e sincronizzazione si interrompono finché non viene registrato un altro connettore. La chiave condivisa della directory sopravvive alla rimozione, quindi un connettore sostitutivo deve essere registrato con la stessa coppia di chiavi, esportata in precedenza.
Rimuovere l'intera installazione
- Disinstallare prima ogni connettore nell'applicazione, come descritto sopra. Il programma di disinstallazione rimuove l'applicazione e il servizio broker locale, ma non i servizi dei connettori ancora registrati.
- Disinstallare l'applicazione tramite Impostazioni → App in Windows.
- Eliminare i record dei connettori nella console.
Risoluzione dei problemi
- SmartScreen blocca l'installer. Confrontare il checksum SHA-1 mostrato nella console con il file scaricato, quindi proseguire tramite Ulteriori informazioni → Esegui comunque.
- La registrazione non riesce per un ticket scaduto o sconosciuto. L'URL di provisioning è monouso e di breve durata. Eliminare il connettore in sospeso nella console, crearne uno nuovo e registrarlo con il suo URL aggiornato.
- La registrazione viene rifiutata per una chiave pubblica diversa. Un altro connettore della stessa directory è stato registrato con una coppia di chiavi differente. Esportare la coppia di chiavi dal connettore in funzione e importarla durante la registrazione.
- La registrazione non riesce per un errore di certificato. La rete intercetta il traffico TLS oppure il certificato della piattaforma proviene da un'autorità privata. Incollare i certificati dell'autorità di certificazione nelle advanced TLS options.
- Il servizio del connettore non si avvia. Aprire Insight → Logs nell'applicazione per quel connettore. Un servizio che non raggiunge la piattaforma riprova di continuo, quindi un errore persistente dipende di norma da una restrizione di firewall o proxy in uscita sulla porta 443.
- Un servizio Windows viene segnalato come contrassegnato per l'eliminazione. Chiudere la console Servizi eventualmente aperta e la scheda Servizi di Gestione attività, quindi riprovare. Se lo stato persiste, riavviare la macchina.
- La console mostra il connettore offline mentre il servizio è in esecuzione. Il connettore è in funzione ma non riesce a completare la connessione in uscita. Controllare la pagina Status dell'applicazione e successivamente i log.
Vedere anche
- Enterprise Connectors per creare, monitorare ed eliminare i connettori nella console.
- Configurare e gestire un Enterprise Connector per origine dati, TLS, stato, log e diagnostica.
- Directory utenti per le impostazioni di directory servite da un connettore di autenticazione.
Enterprise Connectors
Gestire i connector on-premises che collegano la propria rete alla piattaforma per autenticazione, sincronizzazione e provisioning.
Configurare e gestire un Enterprise Connector
Origine dati, TLS, stato, log e diagnostica nell'applicazione Enterprise Connector installata sulla propria macchina.