# 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](https://dts-identity.com/it/docs/directories/enterprise-connectors.md).

## 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

1. Nella console, aprire **Directory → Enterprise Connectors** e creare il connettore da registrare (vedere [Enterprise Connectors](https://dts-identity.com/it/docs/directories/enterprise-connectors.md)).
2. 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.
3. 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

1. 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.
2. Avviare l'applicazione. Al primo avvio registra e avvia il servizio broker locale.
3. 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.

1. 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.
2. Nell'applicazione, aprire **Agents** e scegliere **Provision agent**.
3. 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](https://dts-identity.com/it/docs/directories/enterprise-connector-configuration.md).

### 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:

1. 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.
2. Nella console, creare il secondo connettore e copiare il relativo URL di provisioning.
3. 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:

1. Esportare la coppia di chiavi sulla vecchia macchina.
2. Creare un nuovo connettore nella console e registrarlo sulla nuova macchina con la coppia di chiavi esportata.
3. Verificare che il nuovo connettore riporti **Ready** e gestisca gli accessi.
4. 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

1. Nell'applicazione, aprire **Agents** e scegliere **Stop** per il connettore. La disinstallazione viene offerta solo per un connettore arrestato.
2. Scegliere **Uninstall**. Il servizio Windows viene arrestato e rimosso e la cartella locale del connettore viene eliminata.
3. 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

1. 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.
2. Disinstallare l'applicazione tramite **Impostazioni → App** in Windows.
3. 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](https://dts-identity.com/it/docs/directories/enterprise-connectors.md) per creare, monitorare ed eliminare i connettori nella console.
- [Configurare e gestire un Enterprise Connector](https://dts-identity.com/it/docs/directories/enterprise-connector-configuration.md) per origine dati, TLS, stato, log e diagnostica.
- [Directory utenti](https://dts-identity.com/it/docs/directories/user-directories.md) per le impostazioni di directory servite da un connettore di autenticazione.
