> ## Documentation Index
> Fetch the complete documentation index at: https://docs.opal.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# On-prem connector agent

> Sync and manage access to an Active Directory or LDAP server that Opal can't reach, through an agent you run inside your network.

The on-prem connector agent lets Opal manage an Active Directory or LDAP server that isn't reachable from the internet. You run the agent inside your network, next to the directory. It connects out to Opal over HTTPS, so you don't open any inbound firewall ports.

The directory's address, TLS settings, and service account credentials stay in the agent's config file on your host. They are never sent to Opal.

> [!NOTE]
>
> The on-prem connector agent is in beta. Contact your Opal representative to turn it on for your organization.

## How it works

Opal runs the sync, the same as for a directory it can reach. Instead of connecting to the directory itself, Opal sends the agent one directory operation at a time, such as a search for a group's members. The agent runs the operation against your directory and returns the result.

The agent limits what Opal can do, using lists that you set on your host:

* **`allowedBaseDns`**: the parts of the directory Opal can read. The agent refuses any search outside them, and drops any entry outside them from a result.
* **`writableBaseDns`**: the groups whose membership Opal can change. This list starts empty, so the agent is read-only until you fill it in.

Because these lists live on your host, a change in Opal can't widen them.

## Supported resources

| App | Read | Grant and revoke access |
| - | - | - |
| [Active Directory](https://docs.opal.dev/integrations/active-directory.md) groups | ✔️ | ✔️ |
| [LDAP](https://docs.opal.dev/integrations/ldap.md) groups (`groupOfNames`) | ✔️ | ✔️ |
| LDAP groups (`posixGroup`) | ✔️ | |

Through an agent, Opal grants and revokes access by adding and removing group members. It doesn't manage accounts, so it can't:

* Create Active Directory accounts, or set their passwords.
* Disable or re-enable Active Directory accounts. Deprovisioning a user in Opal doesn't disable their account.
* Change `posixGroup` membership. Those groups list members by uid, which the agent can't hold to `allowedBaseDns`.

## Requirements

Before you begin, you'll need:

* **Admin access** to Opal.
* **A place to run the agent**: a Kubernetes cluster with Helm 3.8 or later, or a Linux host with Docker. The image runs on `linux/amd64` and `linux/arm64`.
* **Outbound HTTPS** from the agent to your Opal URL, for example `https://acme.opal.dev`. The agent also honors `HTTPS_PROXY`.
* **Network access** from the agent to your directory's LDAP or LDAPS port.
* **A service account** in the directory, with read access to the users and groups that Opal syncs. To grant and revoke access, it also needs permission to change the membership of those groups. In Active Directory, use the Delegation of Control Wizard on the groups' OU and choose **Modify the membership of a group**.

Each agent replica requests 100m CPU and 128Mi of memory, with a 1Gi memory limit. The Helm chart runs two replicas.

## Set up the agent

**1. Register the agent in Opal**

Go to **Settings** > **On-prem Agents** and select **Register agent**. Name the agent after where it will run, for example the host name, and select **Register**.

Copy the token that appears. Opal stores only a hash of it, so it can't be shown again. Then select **Download agent bundle**. The bundle holds everything you need to run the agent:

| File | Contents |
| - | - |
| `config.json` | Your directory's address, TLS settings, credentials, and base DN lists, to fill in |
| `opal-agent.env` | The agent's token |
| `docker-compose.yml` | Runs the agent with Docker Compose |
| `values.yaml` | Helm values for Kubernetes |
| `README.md` | How to run the agent |

`config.json` and `opal-agent.env` hold secrets. Keep them readable only by the user who unpacks the bundle.

**2. Route your apps through the agent**

When you create an Active Directory or LDAP app, set **Sync through** to the agent. For an existing app, change **Sync through** in its **App Setup** section.

Once you route an app through an agent, Opal clears the app's server address, TLS settings, and credentials, and doesn't show those fields. You enter them in the agent's `config.json` instead. To route an app back through Opal, you'll need to re-enter them in Opal.

**3. Fill in config.json**

Go back to **Settings** > **On-prem Agents** and select **Configure** on the agent. Opal shows a `config.json` that lists every app routed through the agent, keyed by its Opal ID. Copy it over the `config.json` from the bundle, then fill it in:

```json config.json theme={null}
{
  "connections": {
    "3f7c0e2a-1111-2222-3333-444455556666": {
      "metadata": {
        "ad": {
          "serverHostname": "dc01.corp.example.com",
          "serverPort": 636,
          "tlsMode": true,
          "tlsCaCertContent": ""
        }
      },
      "credentials": {
        "ad": {
          "rootUsername": "OpalServiceAccount",
          "rootPassword": "..."
        }
      },
      "allowedBaseDns": [
        "OU=Groups,DC=corp,DC=example,DC=com",
        "OU=People,DC=corp,DC=example,DC=com"
      ],
      "writableBaseDns": [
        "OU=Groups,DC=corp,DC=example,DC=com"
      ]
    }
  }
}
```

| Field | Value |
| - | - |
| `serverHostname`, `serverPort` | Your directory server. Port `636` always uses LDAPS. |
| `tlsMode` | Whether to connect over TLS on other ports. |
| `tlsCaCertContent` | Optional. The base64-encoded PEM of the CA that signed the server's certificate, if your hosts don't already trust it. |
| `rootUsername`, `rootPassword` | Active Directory: the service account's username and password. |
| `rootUserDistinguishedName`, `rootPassword` | LDAP: the service account's DN and password. |
| `allowedBaseDns` | The parts of the directory Opal can read. Opal pre-fills the base DNs the app uses. Keep both your users and your groups in it. |
| `writableBaseDns` | The groups whose membership Opal can change. Leave it empty to keep the app read-only. |

Opal can only add a user to a group if the user is also within `allowedBaseDns`.

**4. Run the agent**

> [tab] Helm (Kubernetes)
>
> From the unpacked bundle, store the token and the config in Kubernetes Secrets, then install the chart with the bundle's values:
>
> ```bash theme={null}
> kubectl create secret generic opal-agent-token --from-env-file=opal-agent.env
> kubectl create secret generic opal-agent-config --from-file=config.json
> helm install opal-agent oci://ghcr.io/opalsecurity/charts/opal-agent --version <version> \
>   -f values.yaml --set existingConfigSecret.name=opal-agent-config
> ```
>
> Use the version from the bundle's `README.md`.
>
> Keeping the config in a Secret you manage keeps your directory credentials out of Helm's release state. It also works with External Secrets or Vault: put the whole `config.json` in the Secret, under the key `config.json`.
>
> To send the agent's traffic to Opal through a proxy, add it to your values:
>
> ```yaml values.yaml theme={null}
> extraEnv:
>   - name: HTTPS_PROXY
>     value: http://proxy.corp.example.com:3128
> ```

> [tab] Docker Compose
>
> From the unpacked bundle:
>
> ```bash theme={null}
> echo "AGENT_USER=$(id -u):$(id -g)" > .env
> docker compose up -d
> ```
>
> The agent runs as your user, so it can read `config.json`. To use a proxy, add `HTTPS_PROXY=http://proxy.corp.example.com:3128` to `opal-agent.env`.

**5. Check that it's connected**

In **Settings** > **On-prem Agents**, the agent's **Version** and **Last seen** fill in once it connects. Then sync the app to check the agent can reach your directory.

## Manage the agent

### Change the config

The agent rereads `config.json` before every operation, so you don't need to restart it. When you route another app through the agent, copy the new `config.json` from **Configure**, fill in the new app's details, and replace the file on the host. With Helm, update the `opal-agent-config` Secret. Kubernetes takes up to a minute or so to show the agent the new Secret.

### Upgrade the agent

The agent is versioned separately from Opal, and any release works with your Opal tenant. The bundle pins the release that was current when you downloaded it, so the agent stays on that version until you upgrade it. The [package page](https://github.com/orgs/opalsecurity/packages/container/package/opal-agent) lists every release.

> [tab] Helm (Kubernetes)
>
> ```bash theme={null}
> helm upgrade opal-agent oci://ghcr.io/opalsecurity/charts/opal-agent --version <version> --reuse-values
> ```

> [tab] Docker Compose
>
> In `docker-compose.yml`, change the version at the end of `image: ghcr.io/opalsecurity/opal-agent:<version>`, then:
>
> ```bash theme={null}
> docker compose up -d
> ```

### Replace the token

Agent tokens don't expire. To replace one, register a new agent, route your apps through it, and then delete the old agent.

### Run more operations at once

Each agent replica runs four operations at once. If many apps sync through one agent at the same time, set `OPAL_AGENT_WORKERS` higher, with Helm's `extraEnv` or in `opal-agent.env`. Raise the memory limit with it, since each operation in progress can hold a large search result in memory.

## Security

* **No inbound access.** The agent only makes outbound HTTPS requests to Opal. It listens on no port.
* **Credentials stay on your host.** Your directory's address, TLS settings, and credentials never leave the agent's config.
* **What Opal can read.** Entries within `allowedBaseDns`, and only the attributes Opal names. The agent refuses to read well-known credential attributes, such as `userPassword`, `unicodePwd`, or LAPS passwords, or to filter on them. It can't recognize a secret held in an attribute your own schema adds, so don't give the service account read access to those. The directory's own error text stays in the agent's logs. Opal gets only the error code.
* **What Opal can change.** Only group membership, only in groups within `writableBaseDns`, and only for members within `allowedBaseDns`. The agent refuses every other change, including passwords and account settings.
* **The container.** The image is distroless, runs as a non-root user, and writes no files.

## Troubleshooting

> [accordion] A sync fails with “did not pick up work within 30s”
>
> No agent replica took the operation. Check that the agent is running and that **Last seen** is recent. If it is, every worker was busy: raise `OPAL_AGENT_WORKERS`.

> [accordion] A sync fails with “no local config for connection”
>
> The agent's `config.json` doesn't list the app. Copy the current `config.json` from **Configure**, fill in the app's details, and replace the file on the host.

> [accordion] A sync fails with “outside this agent's allowed base DNs”
>
> The app reads part of the directory that `allowedBaseDns` doesn't cover. Add the app's users and groups base DNs to `allowedBaseDns`.

> [accordion] Granting access fails with “outside this agent's writable base DNs”
>
> The group isn't within `writableBaseDns`. Add the group, or the OU that holds it, to `writableBaseDns`.

> [accordion] A sync fails with “the agent's config file could not be read”
>
> `config.json` isn't valid JSON, or the agent can't read it. The agent's logs say which. They are kept there because the error could quote your credentials.

> [accordion] The agent logs “Opal Cloud rejected this agent's token”
>
> The token is wrong, or the agent was deleted in Opal. Check `opal-agent.env`, or the `opal-agent-token` Secret with Helm, against the token you copied. If you no longer have it, register a new agent.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.