Skip to Content

Install an Enterprise Connector

Requirements, download, installation, enrollment, updates, migration and removal of the on-prem Enterprise Connector.

This page covers the software side: what you install in your own network, how you enroll it, keep it current, and remove it again. The console side (creating an connector, its provisioning URL, status, deletion) is described on Enterprise Connectors.

What gets installed

One Windows installation hosts the Agent application plus one or more connectors. They are separate things:

ComponentWhat it isRuns
Agent applicationThe management window you open on the machine. Enrolls connectors, holds their configuration, shows status, logs and diagnostics.On demand, started by you.
Local broker serviceRegistered as the Windows service iec-nats on first launch. Carries the internal communication between the window and the installed connectors. Bound to the local machine only.Always, as a Windows service.
Agent serviceOne Windows service per enrolled connector, named iec-agent-<agent id>. Holds the outbound connection to the platform and does the actual work.Always, as a Windows service.

Because each connector is its own Windows service, connectors keep running when the application window is closed and start again after a reboot. You only need the window to configure, inspect, or update them.

One machine can host several connectors, including connectors of different types and connectors pointing at different directories.

Requirements

  • Windows on x64. The installer and the application require local administrator rights, and the application asks for elevation on every launch because it manages Windows services.
  • Outbound HTTPS only. The connector dials out to your platform host on port 443 (HTTPS and WebSocket over TLS) and keeps that connection open. No inbound firewall rule and no published port is needed on your side.
  • Reachability of the source system. An authentication connector needs to reach your domain controller or LDAP server, normally on port 636 for LDAPS or 389 for LDAP. A provisioning connector needs to reach the SCIM target you intend to serve.
  • A service account for the directory. An authentication connector binds to Active Directory or LDAP with a dedicated read account (a write-capable account only if you enable upstream sync or password writeback).
  • No inbound access to the machine itself. The internal communication between window and services is bound to the local machine and is refused on any other address.

Pick a machine that is always on and close to the directory service, for example a management server in the same site. For resilience, install a second connector for the same directory on a different machine rather than a second connector on the same one.

Note: The installer is not code-signed yet, so Windows SmartScreen warns on first run. Verify the checksum shown next to the download before you continue.

Download the installer

  1. In the console, open Directories → Enterprise Connectors and create the connector you want to enroll (see Enterprise Connectors).
  2. Open the newly created connector. As long as it is not enrolled, its page offers Download for Windows together with the version and the SHA-1 checksum of the installer.
  3. Download the installer and copy it to the target machine.

If the download card is not shown, the download service is not configured for your instance. Ask your support contact for the installer package.

Install the application

  1. Run the installer on the target machine and confirm the elevation prompt. It installs for all users and creates a desktop shortcut.
  2. Start the application. It registers and starts the local broker service on first launch.
  3. The application asks you to set a password on first start, and asks for it on every later start. Anyone with access to the machine and this password can manage the connectors on it, so treat it like an administrative credential.

The password protects the local management window only. It is unrelated to your console account, and it is not used for the connection to the platform.

Enroll an connector

Enrollment ties the local installation to the connector record you created in the console.

  1. In the console, open the connector and copy its provisioning URL. It is shown only to admins who may edit the directory (and returned by the management API only to clients with enterpriseConnectors.write), since the first enrollment sets the directory's encryption key.
  2. In the application, open Agents and choose Provision agent.
  3. Paste the provisioning URL and submit.

The application generates a key pair, exchanges it for the connector's permanent credentials, installs the connector service and starts it. Within a few seconds the console shows the connector as Ready.

The provisioning URL is single-use and expires after a few days. An connector that is already enrolled cannot be enrolled a second time with the same URL. If the URL has expired, delete the pending connector in the console and create a new one.

TLS interception and private certificate authorities

If your network terminates and re-signs TLS, or your platform host uses a certificate from a private authority, expand advanced TLS options during enrollment:

  • Custom CA certificates (PEM) lets you paste the authority certificates the connector should trust in addition to the Windows trust store. This is the recommended path.
  • Ignore invalid certificates disables verification entirely, for enrollment and for the connector's ongoing connection. Use it only as a temporary measure.

Both settings can be changed later on the application's Identity page. See Configure and operate an Enterprise Connector.

Several connectors for the same directory

All authentication connectors of one directory must run with the same key pair: the first connector to enroll establishes the key for the directory, and enrollment of any later connector is refused when its key differs. To add a second connector for an existing directory:

  1. On the machine that already runs an connector, open Identity, enter a passphrase and choose Export keypair. Store the encrypted block and the passphrase safely.
  2. In the console, create the second connector and copy its provisioning URL.
  3. On the second machine, choose Provision agent, paste the URL, expand keypair import, and paste the exported block together with its passphrase.

The passphrase is the only protection of the exported private key, and the only way to open the block again. Delete the exported copy once the second connector runs.

Move an connector to another machine

Use the same export and import steps as above, then retire the old installation:

  1. Export the key pair on the old machine.
  2. Create a new connector in the console and enroll it on the new machine with the exported key pair.
  3. Confirm the new connector reports Ready and handles sign-ins.
  4. Uninstall the connector on the old machine and delete its record in the console.

Migrate a previous connector

If a connector of the previous major version is installed on the machine, the Agents page shows a Previous connector found banner. Choosing Import previous connector carries over its enrollment, its key pair and its directory settings, then stops and removes the old Windows service. The connector keeps its identity in the console, so no re-enrollment and no new provisioning URL is needed.

Anything that could not be carried over is listed as a warning after the import, for example a directory filter stored in an old format that has to be re-created on the Data source page. Review the data source settings and run a connection test before you consider the migration complete.

Keep it current

Updates come in two layers, both handled on the Update page of the application:

  • Application update covers the management window itself. Choose Download update, then Install & restart. The window closes briefly; the connector services keep running.
  • Agent updates cover the service binaries. Each application version ships the matching connector binaries, so after an application update the Agents list marks affected connectors with update available. Choose Update per connector, or use the Agent updates card on the Update page. The connector service restarts as part of the update.

Update one connector of a directory at a time when several connectors serve it, so sign-ins keep working during the restart. The Release notes page in the application lists what changed in each version.

Start, stop and restart

The Agents list has Start, Stop and Restart for every installed connector. A stop is remembered: the connector stays stopped across reboots until you start it again.

While an authentication connector is stopped, its directory has no path to Active Directory or LDAP unless another connector of that directory is online. Sign-ins of that directory's users fail during that window, and scheduled synchronization is skipped.

Uninstall

Remove a single connector

  1. In the application, open Agents and Stop the connector. Uninstall is only offered for a stopped connector.
  2. Choose Uninstall. The Windows service is stopped, removed, and the connector's local folder is deleted.
  3. In the console, delete the connector record under Directories → Enterprise Connectors.

Removing the last authentication connector of a directory leaves that directory without a connection to its source: sign-ins and synchronization stop until another connector is enrolled. The directory's shared key survives the removal, so a replacement connector must be enrolled with the same key pair, exported beforehand.

Remove the whole installation

  1. Uninstall every connector in the application first, as described above. The application uninstaller removes the application and the local broker service, but not connector services that are still registered.
  2. Uninstall the application through Settings → Apps in Windows.
  3. Delete the connector records in the console.

Troubleshooting

  • SmartScreen blocks the installer. Compare the SHA-1 checksum shown in the console with the downloaded file, then continue through More info → Run anyway.
  • Enrollment fails with an expired or unknown ticket. The provisioning URL is single-use and short-lived. Delete the pending connector in the console, create a new one, and enroll with its fresh URL.
  • Enrollment is refused because of a different public key. Another connector of the same directory was enrolled with a different key pair. Export the key pair from the running connector and import it during enrollment.
  • Enrollment fails with a certificate error. Your network intercepts TLS or the platform certificate comes from a private authority. Paste the authority certificates under advanced TLS options.
  • The connector service does not start. Open Insight → Logs in the application for that connector. A service that cannot reach the platform retries continuously, so a persistent failure is usually an outbound firewall or proxy restriction on port 443.
  • A Windows service is reported as marked for deletion. Close any open Services console and the Services tab of Task Manager, then retry. If the state persists, reboot the machine.
  • The console shows the connector as offline while the service runs. The connector is running but cannot complete the outbound connection. Check the Status page of the application, then the logs.

See also

On this page