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.
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
posixGroupmembership. Those groups list members by uid, which the agent can’t hold toallowedBaseDns.
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/amd64andlinux/arm64. - Outbound HTTPS from the agent to your Opal URL, for example
https://acme.opal.dev. The agent also honorsHTTPS_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.
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
- Helm (Kubernetes)
- Docker Compose
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 rereadsconfig.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.- Helm (Kubernetes)
- Docker Compose
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, setOPAL_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 asuserPassword,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 withinallowedBaseDns. 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
A sync fails with “did not pick up work within 30s”
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.A sync fails with “no local config for connection”
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.A sync fails with “outside this agent's allowed base DNs”
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.Granting access fails with “outside this agent's writable base DNs”
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.A sync fails with “the agent's config file could not be read”
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.The agent logs “Opal Cloud rejected this agent's token”
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.