# Enterprise Connector installeren

Vereisten, download, installatie, registratie, updates, migratie en verwijdering van de on-premises Enterprise Connector.

Deze pagina behandelt de softwarekant: wat u in uw eigen netwerk installeert, hoe u die registreert, actueel houdt en weer verwijdert. De consolekant (een connector aanmaken, de provisioning-URL, status, verwijderen) is beschreven onder [Enterprise Connectors](https://dts-identity.com/nl/docs/directories/enterprise-connectors.md).

## Wat er wordt geïnstalleerd

Eén Windows-installatie herbergt de **agentapplicatie** plus een of meer **connectors**. Dat zijn gescheiden zaken:

| Component | Wat het is | Draait |
|---|---|---|
| **Agentapplicatie** | Het beheervenster dat u op de machine opent. Registreert connectors, bevat hun configuratie, toont status, logs en diagnostiek. | Op verzoek, door u gestart. |
| **Lokale brokerservice** | Wordt bij de eerste start als Windows-service `iec-nats` geregistreerd. Draagt de interne communicatie tussen het venster en de geïnstalleerde connectors. Uitsluitend aan de lokale machine gebonden. | Doorlopend, als Windows-service. |
| **Agentservice** | Eén Windows-service per geregistreerde connector, met de naam `iec-agent-<agent id>`. Houdt de uitgaande verbinding met het platform in stand en doet het eigenlijke werk. | Doorlopend, als Windows-service. |

Omdat elke connector een eigen Windows-service is, blijven connectors draaien wanneer het applicatievenster is gesloten en starten ze na een herstart opnieuw. U hebt het venster alleen nodig om ze te configureren, te inspecteren of bij te werken.

Eén machine kan meerdere connectors herbergen, ook connectors van verschillende typen en connectors die op verschillende directory's zijn gericht.

## Vereisten

- **Windows op x64.** Het installatieprogramma en de applicatie vereisen lokale beheerdersrechten, en de applicatie vraagt bij elke start om verhoogde rechten omdat zij Windows-services beheert.
- **Uitsluitend uitgaand HTTPS.** De connector maakt verbinding met uw platformhost op poort 443 (HTTPS en WebSocket over TLS) en houdt die verbinding open. Aan uw kant is geen inkomende firewallregel en geen gepubliceerde poort nodig.
- **Bereikbaarheid van het bronsysteem.** Een verificatieconnector moet uw domeincontroller of LDAP-server bereiken, normaal gesproken op poort 636 voor LDAPS of 389 voor LDAP. Een provisioningconnector moet het SCIM-doel bereiken dat hij moet bedienen.
- **Een serviceaccount voor de directory.** Een verificatieconnector bindt zich met een specifiek leesaccount aan Active Directory of LDAP (een account met schrijfrechten alleen wanneer u upstreamsynchronisatie of het terugschrijven van wachtwoorden inschakelt).
- **Geen inkomende toegang tot de machine zelf.** De interne communicatie tussen venster en services is aan de lokale machine gebonden en wordt op elk ander adres geweigerd.

Kies een machine die permanent aanstaat en dicht bij de directoryservice staat, bijvoorbeeld een beheerserver op dezelfde locatie. Installeer voor uitwijkzekerheid een tweede connector voor dezelfde directory op een andere machine in plaats van een tweede connector op dezelfde machine.

> **Opmerking:** het installatieprogramma is nog niet ondertekend, dus Windows SmartScreen waarschuwt bij de eerste start. Controleer de controlesom die naast de download wordt getoond voordat u doorgaat.

## Het installatieprogramma downloaden

1. Open in de console **Directory's → Enterprise Connectors** en maak de connector aan die u wilt registreren (zie [Enterprise Connectors](https://dts-identity.com/nl/docs/directories/enterprise-connectors.md)).
2. Open de zojuist aangemaakte connector. Zolang deze niet is geregistreerd, biedt zijn pagina **Download for Windows** aan, samen met de versie en de SHA-1-controlesom van het installatieprogramma.
3. Download het installatieprogramma en kopieer het naar de doelmachine.

Wordt de downloadkaart niet getoond, dan is de downloadservice niet geconfigureerd voor uw instantie. Vraag het installatiepakket op bij uw supportcontact.

## De applicatie installeren

1. Voer het installatieprogramma uit op de doelmachine en bevestig de vraag om verhoogde rechten. Het installeert voor alle gebruikers en maakt een snelkoppeling op het bureaublad aan.
2. Start de applicatie. Bij de eerste start registreert en start zij de lokale brokerservice.
3. De applicatie vraagt u bij de eerste start een **wachtwoord in te stellen** en vraagt daar bij elke volgende start om. Wie toegang heeft tot de machine en tot dit wachtwoord, kan de connectors daarop beheren, dus behandel het als een beheerderswachtwoord.

Het wachtwoord beschermt uitsluitend het lokale beheervenster. Het staat los van uw consoleaccount en wordt niet gebruikt voor de verbinding met het platform.

## Een connector registreren

De registratie verbindt de lokale installatie met het connectorrecord dat u in de console hebt aangemaakt.

1. Open de connector in de console en kopieer zijn **provisioning-URL**. Deze wordt alleen getoond aan beheerders die de directory mogen bewerken (en door de management-API alleen teruggegeven aan clients met `enterpriseConnectors.write`), omdat de eerste registratie de encryptiesleutel van de directory vastlegt.
2. Open in de applicatie **Agents** en kies **Provision agent**.
3. Plak de provisioning-URL en verzend het formulier.

De applicatie genereert een sleutelpaar, wisselt dat in voor de permanente inloggegevens van de connector, installeert de connectorservice en start die. Binnen enkele seconden toont de console de connector als **Ready**.

De provisioning-URL is eenmalig bruikbaar en verloopt na enkele dagen. Een connector die al is geregistreerd, kan niet met dezelfde URL een tweede keer worden geregistreerd. Is de URL verlopen, verwijder dan de openstaande connector in de console en maak een nieuwe aan.

### TLS-onderschepping en private certificeringsinstanties

Als uw netwerk TLS termineert en opnieuw ondertekent, of als uw platformhost een certificaat van een private instantie gebruikt, klap dan tijdens de registratie **advanced TLS options** uit:

- Met **Custom CA certificates (PEM)** plakt u de certificaten van de instanties die de connector naast het Windows-certificaatarchief moet vertrouwen. Dit is de aanbevolen weg.
- **Ignore invalid certificates** schakelt de controle volledig uit, zowel voor de registratie als voor de doorlopende verbinding van de connector. Gebruik dit alleen als tijdelijke maatregel.

Beide instellingen kunt u later wijzigen op de pagina **Identity** van de applicatie. Zie [Enterprise Connector configureren en beheren](https://dts-identity.com/nl/docs/directories/enterprise-connector-configuration.md).

### Meerdere connectors voor dezelfde directory

Alle verificatieconnectors van één directory moeten met **hetzelfde sleutelpaar** draaien: de eerste connector die zich registreert, vestigt de sleutel voor de directory, en de registratie van elke latere connector wordt geweigerd wanneer zijn sleutel afwijkt. Zo voegt u een tweede connector aan een bestaande directory toe:

1. Open op de machine waarop al een connector draait de pagina **Identity**, voer een wachtwoordzin in en kies **Export keypair**. Bewaar het versleutelde blok en de wachtwoordzin veilig.
2. Maak in de console de tweede connector aan en kopieer zijn provisioning-URL.
3. Kies op de tweede machine **Provision agent**, plak de URL, klap **keypair import** uit en plak het geëxporteerde blok samen met de wachtwoordzin.

De wachtwoordzin is de enige bescherming van de geëxporteerde privésleutel en de enige manier om het blok weer te openen. Verwijder de geëxporteerde kopie zodra de tweede connector draait.

## Een connector naar een andere machine verplaatsen

Gebruik dezelfde export- en importstappen als hierboven en neem daarna de oude installatie buiten gebruik:

1. Exporteer het sleutelpaar op de oude machine.
2. Maak een nieuwe connector aan in de console en registreer die op de nieuwe machine met het geëxporteerde sleutelpaar.
3. Controleer of de nieuwe connector **Ready** meldt en aanmeldingen verwerkt.
4. Verwijder de connector op de oude machine en verwijder zijn record in de console.

## Een eerdere connector migreren

Staat er op de machine een connector van de vorige hoofdversie, dan toont de pagina **Agents** een banner **Previous connector found**. Met **Import previous connector** worden zijn registratie, zijn sleutelpaar en zijn directory-instellingen overgenomen, waarna de oude Windows-service wordt gestopt en verwijderd. De connector behoudt zijn identiteit in de console, dus een nieuwe registratie en een nieuwe provisioning-URL zijn niet nodig.

Alles wat niet kon worden overgenomen, wordt na de import als waarschuwing vermeld, bijvoorbeeld een directoryfilter in een oud formaat dat op de pagina **Data source** opnieuw moet worden aangemaakt. Controleer de instellingen van de gegevensbron en voer een verbindingstest uit voordat u de migratie als afgerond beschouwt.

## Actueel houden

Updates komen in twee lagen, beide op de pagina **Update** van de applicatie:

- De **applicatie-update** betreft het beheervenster zelf. Kies **Download update** en daarna **Install & restart**. Het venster sluit kort; de connectorservices blijven draaien.
- De **agentupdates** betreffen de binaries van de services. Elke applicatieversie levert de bijbehorende connectorbinaries mee, dus na een applicatie-update markeert de lijst **Agents** de betrokken connectors met **update available**. Kies **Update** per connector of gebruik de kaart **Agent updates** op de pagina **Update**. De connectorservice start als onderdeel van de update opnieuw op.

Werk bij meerdere connectors van één directory telkens één connector tegelijk bij, zodat aanmeldingen tijdens de herstart blijven werken. De pagina **Release notes** in de applicatie vermeldt wat er in elke versie is gewijzigd.

## Starten, stoppen en opnieuw starten

De lijst **Agents** biedt **Start**, **Stop** en **Restart** voor elke geïnstalleerde connector. Een stop blijft behouden: de connector blijft over herstarts heen gestopt totdat u die weer start.

Zolang een verificatieconnector is gestopt, heeft zijn directory geen weg naar Active Directory of LDAP, tenzij een andere connector van die directory online is. Aanmeldingen van de gebruikers van die directory mislukken in die periode, en geplande synchronisaties vervallen.

## Verwijderen

### Eén enkele connector verwijderen

1. Open in de applicatie **Agents** en kies **Stop** voor de connector. Verwijderen wordt alleen aangeboden voor een gestopte connector.
2. Kies **Uninstall**. De Windows-service wordt gestopt en verwijderd, en de lokale map van de connector wordt gewist.
3. Verwijder in de console het connectorrecord onder **Directory's → Enterprise Connectors**.

Wordt de laatste verificatieconnector van een directory verwijderd, dan heeft die directory geen verbinding meer met zijn bron: aanmeldingen en synchronisatie liggen stil tot een andere connector is geregistreerd. De gedeelde sleutel van de directory blijft na de verwijdering bestaan, dus een vervangende connector moet met hetzelfde, vooraf geëxporteerde sleutelpaar worden geregistreerd.

### De volledige installatie verwijderen

1. Verwijder eerst elke connector in de applicatie, zoals hierboven beschreven. Het verwijderprogramma van de applicatie verwijdert de applicatie en de lokale brokerservice, maar niet de connectorservices die nog geregistreerd zijn.
2. Verwijder de applicatie via **Instellingen → Apps** in Windows.
3. Verwijder de connectorrecords in de console.

## Probleemoplossing

- **SmartScreen blokkeert het installatieprogramma.** Vergelijk de SHA-1-controlesom die in de console wordt getoond met het gedownloade bestand en ga daarna verder via **Meer informatie → Toch uitvoeren**.
- **Registratie mislukt met een verlopen of onbekend ticket.** De provisioning-URL is eenmalig bruikbaar en kortlevend. Verwijder de openstaande connector in de console, maak een nieuwe aan en registreer die met de nieuwe URL.
- **Registratie wordt geweigerd wegens een afwijkende publieke sleutel.** Een andere connector van dezelfde directory is met een ander sleutelpaar geregistreerd. Exporteer het sleutelpaar van de draaiende connector en importeer het tijdens de registratie.
- **Registratie mislukt met een certificaatfout.** Uw netwerk onderschept TLS, of het platformcertificaat komt van een private instantie. Plak de certificaten van de certificeringsinstantie onder de geavanceerde TLS-opties.
- **De connectorservice start niet.** Open **Insight → Logs** in de applicatie voor die connector. Een service die het platform niet kan bereiken, probeert het doorlopend opnieuw; een blijvende storing komt daarom meestal door een uitgaande firewall- of proxybeperking op poort 443.
- **Een Windows-service wordt gemeld als gemarkeerd voor verwijdering.** Sluit een geopende Services-console en het tabblad Services van Taakbeheer en probeer het opnieuw. Blijft de toestand bestaan, start de machine dan opnieuw op.
- **De console toont de connector offline terwijl de service draait.** De connector draait, maar kan de uitgaande verbinding niet tot stand brengen. Controleer de pagina **Status** van de applicatie en daarna de logs.

## Zie ook

- [Enterprise Connectors](https://dts-identity.com/nl/docs/directories/enterprise-connectors.md) voor het aanmaken, monitoren en verwijderen van connectors in de console.
- [Enterprise Connector configureren en beheren](https://dts-identity.com/nl/docs/directories/enterprise-connector-configuration.md) voor de gegevensbron, TLS, status, logs en diagnostiek.
- [Gebruikersdirectory's](https://dts-identity.com/nl/docs/directories/user-directories.md) voor de directory-instellingen die een verificatieconnector bedient.
