> 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/installation/rpm/rpm-single-node/add-a-connector.md).

# Add a connector

Install and start a connector so OpenIAM can manage accounts in a target system.

Connectors are how OpenIAM reads from and writes to the systems it manages — directories, databases, cloud services and business applications. Each runs as its own service on the platform host and talks to the platform over the message broker.

The LDAP connector is installed with the platform. This page covers starting it and adding others.

## What this covers, and how long it takes

<table><thead><tr><th width="154.00001525878906"></th><th></th></tr></thead><tbody><tr><td><strong>You get</strong></td><td>A connector installed, running, and ready to be configured against a managed system</td></tr><tr><td><strong>Time</strong></td><td>10 minutes per connector</td></tr><tr><td><strong>Hosts</strong></td><td>The platform host</td></tr><tr><td><strong>Downtime</strong></td><td>None — connectors start and stop independently of the platform</td></tr><tr><td><strong>Reversible</strong></td><td>Yes — stop the service and remove the file</td></tr></tbody></table>

## Before you start

* The deployment passes [*Start and verify*](/installation/rpm/rpm-single-node/start-and-verify.md).
* **The connector file for the system you are integrating.** Your OpenIAM account team supplies the connectors your entitlement covers, from the same channel as the platform components — see [*Obtain the software*](/installation/obtain-the-software.md).
* You know the address and credentials of the target system, for the configuration step that follows.

## Set these first

{% code overflow="wrap" %}

```bash
export CONNECTOR=<the connector's filename without its extension>
```

{% endcode %}

`openiam-cli list-connectors` prints the names, and is the quickest way to confirm one.

***

## Build it

### 1. See what is already installed

{% code overflow="wrap" %}

```bash
openiam-cli list-connectors
```

{% endcode %}

**What you should see:** at minimum `ldap-connector-rabbitmq`, installed with the platform.

### 2. Add a connector file

Connector files live in `/usr/local/openiam/connectors/bin/`:

{% code overflow="wrap" %}

```bash
cp $CONNECTOR.jar /usr/local/openiam/connectors/bin/
chown openiam:openiam /usr/local/openiam/connectors/bin/$CONNECTOR.jar
```

{% endcode %}

**What you should see:** the file listed by `openiam-cli list-connectors` on the next run. The name shown is the filename without its extension, and that is the name you use in the commands below.

### 3. Start it

{% code overflow="wrap" %}

```bash
openiam-cli connector $CONNECTOR start
```

{% endcode %}

**What it does:** starts the connector as a systemd service, `openiam-connector@"$CONNECTOR"`, which connects to the message broker and waits for work.

**What you should see:** `Start Service for $CONNECTOR connector`.

### 4. Confirm it is running

{% code overflow="wrap" %}

```bash
openiam-cli connector $CONNECTOR status
pgrep -af "$CONNECTOR.jar"
```

{% endcode %}

**Expected:** the service active, and a process listed.

### 5. Enable it to start with the host

{% code overflow="wrap" %}

```bash
openiam-cli connector $CONNECTOR enable
```

{% endcode %}

**What you should see:** a confirmation that the unit was enabled. Without this the connector does not return after a host restart. This is `systemctl enable openiam-connector@<name>` under the covers, if you prefer the host's own tooling.

### 6. Configure the managed system

The connector is now running and available to the platform. Defining the managed system it talks to — the target's address, credentials, the attributes to synchronise and the matching rules — is done in the web console and covered in the [Administration Guide](/administration-guide/admin.md).

***

## Managing connectors

<table><thead><tr><th width="291.6000061035156">Task</th><th>Command</th></tr></thead><tbody><tr><td>List installed connectors</td><td><code>openiam-cli list-connectors</code></td></tr><tr><td>Start</td><td><code>openiam-cli connector &#x3C;name> start</code></td></tr><tr><td>Stop</td><td><code>openiam-cli connector &#x3C;name> stop</code></td></tr><tr><td>Status</td><td><code>openiam-cli connector &#x3C;name> status</code></td></tr><tr><td>Recent log output</td><td><code>openiam-cli connector &#x3C;name> log</code></td></tr><tr><td>Start with the host</td><td><code>openiam-cli connector &#x3C;name> enable</code></td></tr></tbody></table>

**The name comes before the action.** Running `openiam-cli connector` with no name prints the installed list.

Source adapters — used for inbound feeds from authoritative sources such as an HR system — follow the same pattern with `openiam-cli list-source-adapters`.

## Verify it

A connector is working end to end when it is running, connected to the broker, and answering a test from the console:

{% code overflow="wrap" %}

```bash
openiam-cli connector $CONNECTOR status
```

{% endcode %}

then, in the Webconsole, use the managed system's **test connection** action. A successful test confirms the whole path: console, platform, broker, connector, target system.

## If it goes wrong

| What you see                                  | What it means                                                                                    | What to do                                                                                    |
| --------------------------------------------- | ------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------- |
| `Connector <name> doesn't exist`              | The file is not in `/usr/local/openiam/connectors/bin/`, or the name does not match the filename | Run `openiam-cli list-connectors` and use a name exactly as listed                            |
| The service starts but the process exits      | Usually a permissions or file-ownership issue                                                    | Confirm the file is owned by `openiam:openiam`, then check `openiam-cli connector <name> log` |
| The connector runs but the console test fails | The connector cannot reach the target system                                                     | Confirm network access and credentials from the platform host to the target                   |
| The connector is gone after a host restart    | The service was not enabled                                                                      | `systemctl enable openiam-connector@<name>`                                                   |

## What this procedure does not cover

Defining the managed system, the attribute mappings, the matching rules, and the synchronisation and reconciliation schedules are all configured in the Webconsole — see the [Administration Guide](/administration-guide/admin.md).

## Related

* [*Start and verify*](/installation/rpm/rpm-single-node/start-and-verify.md)
* [*Troubleshoot*](/installation/rpm/rpm-single-node/troubleshoot.md)
* [*Commands*](/installation/commands.md)
* The [Administration Guide](/administration-guide/admin.md) — managed systems and synchronisation

*Applies to OpenIAM 2026.8.1.*


---

# 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/installation/rpm/rpm-single-node/add-a-connector.md?ask=<question>&goal=<user_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.