Skip to main content
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.
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

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: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:
config.json
Opal can only add a user to a group if the user is also within allowedBaseDns.
4

Run the agent

From the unpacked bundle, store the token and the config in Kubernetes Secrets, then install the chart with the bundle’s values:
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:
values.yaml
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 lists every release.

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

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.
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.
The app reads part of the directory that allowedBaseDns doesn’t cover. Add the app’s users and groups base DNs to allowedBaseDns.
The group isn’t within writableBaseDns. Add the group, or the OU that holds it, to writableBaseDns.
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.
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.
Last modified on November 5, 2026