> For the complete documentation index, see [llms.txt](https://docs.openiam.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.openiam.com/solution-architecture/integration/connector-placement.md). # Connector placement Where connector processes physically run — how one deployment reaches several networks, what a cloud-hosted platform needs in order to reach on-premise targets, which integrations genuinely need a Win ## What this is, and when you need it Connectors are the processes that talk to managed systems. Where they run is a network and security decision, and in a cloud-hosted design it is the most common late surprise: the topology is agreed, the platform services are chosen, and then somebody asks how OpenIAM will reach the domain controllers. This page settles four things: how connectors connect and what each host must reach, how one deployment serves several network segments, what a cloud-hosted platform needs in order to reach an on-premise estate, and which integrations genuinely need Windows. Decide them alongside the topology, because the network design is usually frozen first. ## The decision | Placement | Use it for | What it needs | What it costs | | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | | **On the OpenIAM nodes** | Targets reachable from wherever OpenIAM runs — cloud applications, databases and directories in the same network | Nothing extra | Connector work competes with service work for memory | | **On a dedicated Linux connector host** | Targets in another segment; high-volume connectors; anything you want to fail independently | A small Linux VM with outbound access to the broker **and the secrets store** | One more machine per segment | | **On a Windows Server connector host** | Managed systems whose operations are performed by PowerShell | A 64-bit Windows Server 2016 or later host with outbound access to the broker | A Windows machine, with its own patching and installer | | **On the managed system itself** | The Active Directory password filter, which is not a connector | Installation on every domain controller, plus outbound HTTPS from each to OpenIAM's web tier | A component on your domain controllers, in the password-change path | The decision is per connector, not per deployment. A multi-network estate uses the second row several times over. ## How connectors connect, and why it simplifies the firewall The most useful fact about connector placement is the direction of the connection. **Every connector attaches to the message broker and consumes from a queue.** Since the 4.0 series each connector record carries a queue name, and the older notion of a service endpoint that OpenIAM called out to was removed entirely — the record has no address field at all. The connector dials out, subscribes and waits; the platform publishes to the queue named on the record and consumes only the reply. So **OpenIAM never opens a connection to a connector host**, which can sit in a DMZ or across a firewall with no inbound rule — and **a connector host can live anywhere the broker is reachable from**, including on-premise when OpenIAM runs in a cloud. ```mermaid flowchart LR SVC[OpenIAM services] --> MQ[Message broker] LC[Linux connector host] --> MQ LC --> VAULT[Secrets store] WC[Windows connector host] --> MQ DC[Domain controller with password filter] --> WEB[OpenIAM web tier] LC --> TGT[Directory, database, application] WC --> AD[Active Directory, Exchange, Windows servers] ``` Read the arrows as "opens a connection to". Everything dials out; nothing dials in. ## What a connector host must actually reach More than "the broker", and the difference decides whether a cloud-plus-on-premise design works. | Host | Must reach | Does not need | | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- | | **Java connector** | The broker, **and the secrets store** — unless started with the secrets store disabled, holding credentials locally | The database, the search tier, the graph store and Cassandra: it talks to none of them | | **.NET/PowerShell connector** | The broker, and nothing else. Its installer collects broker host, port, virtual host, queue, credentials and a TLS option; no secrets-store parameter exists | Everything else | | **AD password filter** | OpenIAM's **web tier** over HTTPS, from every domain controller, with a stored OpenIAM credential | The broker and the secrets store — it uses neither | The Java row catches designs. A connector resolves its credentials through the secrets store at startup by default, so a host that reaches the broker but not the secrets store does not start. Running with the secrets store disabled and local credentials is supported and is often right for a remote host, but it is a decision about where secrets live. Plan a Java connector host around exactly the two connections in the table — the broker, and the secrets store unless the host is deliberately run without it. ### The exposure asymmetry, and why it decides cloud designs The most likely late surprise in a cloud-plus-on-premise design, and it appears in no diagram. **The broker has a shipped exposure control; the secrets store does not.** The broker's service type is a documented, supported variable — internal load balancer, private endpoint or public load balancer are all reachable through shipped configuration. The secrets store's service is **hard coded internal-only, with no equivalent variable.** An on-premise **Java** connector talking to a Kubernetes-hosted platform therefore has two paths: run with the secrets store disabled and hold credentials locally, or expose the secrets store yourself, outside anything shipped configuration does. Decide at design time. It does not arise for the .NET/PowerShell family, which never talks to the secrets store. ## Reaching several networks Estates with a DMZ, an acquired company's network, a partner segment or a plant network ask whether OpenIAM supports multi-network. It does, and the mechanism is smaller than the phrase suggests. **There is no site, zone, group or cluster concept.** Nothing about a connector's network is modelled anywhere. The only routing-relevant thing on a connector record is its **queue name**, generated when the record is created and immutable afterwards. A managed system points at a connector record; that record's queue name is the routing key; whichever process consumes that queue does the work. The pattern is therefore: **one connector record per network segment**, each with its own generated queue; **one connector process per segment**, consuming that queue; and **each managed system pointed at the record for the segment its target lives in.** **The limit that follows: two consumers on one queue means round-robin.** You cannot point one connector record at two hosts in two networks and expect OpenIAM to choose correctly — messages for network A's targets will land on network B's connector about half the time, and fail there. **One queue per network, always.** Where a segment needs a second process for throughput, the two are interchangeable, which is exactly when round-robin is what you want. Segmentation is therefore enforced by queue-name discipline and by the network itself. OpenIAM does not know where a connector runs and will not stop you pointing a managed system at the wrong segment, so the segment map lives in the design document. ## Cloud platform, on-premise targets The pattern that catches cloud-hosted designs, ranked by what shipped configuration supports. | Option | Shipped support | | -------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Connector on-premise, dialling out to the broker** | Fully supported and documented for both families; the Windows installer takes the broker parameters at install time | | **Broker on an internal or private load balancer** | Supported by shipped configuration — the service type is a documented variable, and an internal load-balancer example ships in the values | | **Broker exposed publicly with mutual TLS** | Supported — public service type plus the shipped TLS configuration, which verifies the peer certificate and can disable plain TCP | | **Site-to-site connectivity** — a tunnel or a dedicated interconnect | **Not provisioned by the shipped infrastructure modules.** They build the cloud-side network and the peering managed services need internally; corporate connectivity is outside their scope | | **A relay, or a broker-of-brokers** | **No such component exists** | The first row is the pattern: the connector sits where its targets already are, the boundary-crossing traffic is one connection per host to one destination on one port, and adding a managed system on-premise adds no new boundary rule. The alternative — connectors in the cloud, with a path opened inbound to every domain controller, database and application — is worse on every count. Describing the site-to-site link as *the* answer under-sells the second row. **The broker does not have to be publicly reachable — it has to be reachable**, and a private endpoint or internal load balancer is shipped configuration rather than a customer build. Where a link is chosen anyway, raise it in the first architecture session: it is often the longest-lead dependency in a cloud-hosted programme, and because it appears in no component diagram it is discovered when the first integration is attempted. ## Shared credentials, and what that means for a remote host Two things belong in the build of any design that puts a connector outside the platform's own network, and both are cheaper to do then than to retrofit. **Give a lower-trust connector host a broker account scoped to what it serves.** A connector host in a DMZ, a partner network or any other lower-trust segment should be given a broker account scoped to the connector virtual host and to the queues that host consumes, rather than one the platform itself uses. **Scoping that account is work the design has to include**, because the shipped configuration does not do it for you — write it into the build, not into a hardening backlog. **Set the payload-encryption key at build time.** A shared symmetric key protects broker payloads and every connector host must hold it, so choose its value deliberately when the estate is built; changing it afterwards is a whole-estate operation. Both follow from the same architectural point, and it is a genuine placement consideration: a remote connector host holds credentials, so it is a host whose compromise matters. That is a reason to keep the number of connector hosts deliberate rather than incidental. ## What genuinely requires Windows "Microsoft integrations need a Windows connector" is too broad, and designing to it puts a Windows VM into architectures that do not need one. **Active Directory itself does not.** The directory connector is a Java process and reaches Active Directory over LDAP or LDAPS like any other directory, covering the full user and group lifecycle including password reset. An estate whose only Microsoft target is Active Directory over LDAP needs no Windows host at all. **Entra ID and Microsoft 365 over Microsoft Graph need a distinction rather than an answer.** A managed system definition for Microsoft Graph is **seeded**, with a complete policy-map template — but **the Graph connector runtime is not in the shipped connector set.** A seeded definition is not a delivered integration, and *Shipped connectors* in the Administration Guide is the list that settles which is which for a given release. **The .NET and PowerShell family does need Windows**, and its packaging is specific enough to design around. These connectors — for Active Directory, Exchange, Azure and Entra, Dynamics, SQL Server, SharePoint, Teams, local Windows accounts and a generic scripting target among others — **run as a Windows Service, installed by an MSI-based installer distributed separately from both the Linux packages and the container charts.** The installer collects the broker host, port, virtual host, queue name and credentials at install time, so the queue mapping that implements the segment pattern above is chosen during installation. **The installer enforces a 64-bit Windows Server 2016 or later, Server SKU** — a client operating system will not install it, which is worth knowing before somebody offers a spare workstation for a proof of concept. **One packaging note, because it is routinely misread.** The connectors shipped with the container distribution are twenty-five Java, queue-attached processes; **the packaged Linux installer bootstraps exactly one of them, the LDAP connector**, and every other connector is a separate download onto the host. Neither distribution contains the Windows installer. So the question is not "is the target Microsoft?" but **"does the integration need an operation only PowerShell can perform?"** — usually Exchange mailbox operations, Windows local accounts, or Active Directory behaviours with no clean LDAP equivalent. **Which operations a given connector implements is a per-connector fact, not something to infer from its name** — *Shipped connectors* and *Managed system fields and the connector request* in the Administration Guide are where that answer lives, per connector and per release. ## The Active Directory password filter is a different thing It is often folded into the connector conversation and it obeys none of the rules above. The password filter is a Windows component installed **on the domain controllers**, so a password changed in Windows can be captured and propagated. It is not a connector, it consumes no queue, and **it talks to neither the broker nor the secrets store.** Instead **every domain controller makes an outbound HTTPS call to OpenIAM's web tier**, authenticated with a stored OpenIAM credential — a distinct firewall requirement, to a different destination from everything else on this page, and routinely missed. **It is also an availability decision:** the policy-validation call sits synchronously in the password-change path, so a domain controller that cannot reach the web tier is one with a degraded password change. And it is the only OpenIAM component that runs on a domain controller, which is a conversation with different stakeholders and a longer approval path than adding a VM. [Password strategy](/solution-architecture/access/password-strategy.md) covers whether you need it. ## Connector version drift **The packaged platform upgrade does not touch connectors.** Their binaries are not replaced, so every connector stays at the version it was installed at and **the shipped upgrade produces a mixed-version estate by default**, drifting further with each release unless somebody owns connector upgrades as a separate task. **The .NET and PowerShell family is versioned independently**, on its own four-part scheme, and carries at least one documented cross-version constraint: recent versions default to a broker queue type that older platform releases do not support. Record which connector versions run against which platform version, and treat connector upgrades as a named activity in the upgrade runbook. Nothing in the product reports drift. ## What we recommend **Put connector hosts next to their targets, not next to OpenIAM.** The outbound-only model makes this cheaper and more secure almost every time, and it is the only sensible arrangement when OpenIAM is in a cloud and the targets are not. **Expose the broker privately before you build a network.** An internal load balancer or private endpoint is shipped configuration; a site-to-site link is a customer project with a lead time. **Settle the secrets-store question for every remote Java connector at design time.** Either it reaches the secrets store, or it runs with the secrets store disabled and holds local credentials. **Draw the segment map early and keep it.** One connector record, one queue and one connector process per segment, with every managed system's segment written down. The product holds none of this. **Establish the Windows question per managed system.** If every Microsoft target is reachable over LDAP or Graph, no Windows host is needed; if any needs PowerShell, one Windows host serves all of them. **Give high-volume connectors their own host.** A reconciliation against a large directory is the heaviest thing a connector does, and keeping it off the nodes that serve sign-in is the same argument that separates the infrastructure tier in the larger topologies. **Scope a broker credential per connector host if any sit outside your own network** — before the first DMZ host exists, rather than after. The circumstance that changes this advice is an entirely cloud-native estate: no on-premise directory, no on-premise applications. There, connectors run on the OpenIAM nodes, there is no Windows host and no segment map, and this page reduces to a single sentence. ## What OpenIAM does not do here * **OpenIAM does not connect to a connector host.** The connection is always outbound to the broker, so a connector host cannot be reached or managed through OpenIAM's network path. * **There is no site, zone or network concept.** Segmentation is queue-name discipline plus the network; the platform does not know where a connector runs, and two consumers on one queue round-robin. * **A connector's queue name cannot be changed.** It is generated at creation and fixed thereafter. * **The secrets store has no shipped exposure control.** The broker does; the secrets store's service is internal-only with no equivalent variable. * **The shipped configuration does not create a connector-scoped broker credential.** Scoping an account to the connector virtual host and its queues is design work, as is setting the shared payload-encryption key that every connector host holds. * **The shipped infrastructure modules do not build connectivity to your corporate network**, and there is no relay or broker-of-brokers. * **The Linux packages and container charts do not include the Windows connector installer**, which will not install on a Windows client operating system. * **The packaged platform upgrade does not upgrade connectors**, and nothing reports the drift. * **The password filter cannot run anywhere but on the domain controllers.** ## Related * [Connector strategy](/solution-architecture/integration/connector-strategy.md) — which integration each system uses, decided before this page places it. * [Topologies using cloud platform services](/solution-architecture/deployment/platform-service-topologies.md) — the topology that assumes on-premise connector hosts. * *Verify connectivity to the target* and *Rotate service credentials* in the Administration Guide — proving a placement works, and changing the credentials it depends on. * The [Installation Guide](/installation/installation.md) — installing connector hosts, including the Windows one. *Applies to OpenIAM 2026.8.1. Last reviewed 13 August 2026.* --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.openiam.com/solution-architecture/integration/connector-placement.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.