The Active Directory agent

This is a different thing from the read-only LDAP directory-pull connector covered in Connecting Active Directory or LDAP, which reads users and groups over a bind-and-search connection with no agent to install. The AD agent described here is a separate installable Windows service (cmd/ad-agent, the same shape as the PAM agent covered in Enrolling the PAM agent) that runs inside your domain, syncs on a schedule, and can additionally act on behalf of a signing-in user to bind against Active Directory as them — delegated authentication.

Console: Identity → Directories, at /iam/directories.

Registering the agent

An agent is registered from the console with a one-time bearer secret, shown once at creation — the same pattern the PAM agent uses, not HMAC request signing. The agent stores it in a local config file, alongside the AD service account's own bind password. Neither secret ever leaves the machine the agent runs on except the bearer secret, which authenticates the agent back to Qorionix; the AD bind password is used only for the agent's own connection to your directory and is never sent to us. The config file is written with restrictive permissions.

Once registered you can enable or disable the agent from the console without deleting its registration, and — the one piece of this wave that works end to end today — run a test delegated auth action against it to confirm the mechanism works, described below.

The sync loop

The agent runs a periodic search against your Active Directory (using go-ldap, the same LDAP library the read-only connector uses, including paged search for large directories) and feeds what it finds into the same staged-import pipeline described in Staged import with preview: the agent's search results become an import source that is staged, previewed and applied automatically on each sync, rather than sitting as an unreviewed diff waiting for someone to click apply. A directory sync is meant to converge your Qorionix directory toward what Active Directory actually holds, on every run.

Delegated authentication

This is the capability that makes the AD agent more than another sync connector: at the moment someone signs in, the agent can bind to Active Directory as that person, using the credential they typed, to confirm it against your domain directly rather than a copy of it. If the bind succeeds, the person is authenticated; if it fails, they are not.

The mechanism is a signed challenge/response, not a shared secret the agent could be tricked into reusing: a challenge is issued and held only in memory, keyed by a challenge id with its own expiry; the agent polls for it, attempts the bind on a connection separate from its own sync connection, and reports success or failure back. A response is refused unless it names the correct agent id — taken from the agent's own authenticated identity, never from anything the response claims — and the correct nonce, so a forged or replayed response cannot be accepted.

If the agent doesn't answer in time, or is unreachable, behaviour follows a fallback policy you configure per agent: deny (the sign-in fails) or local_password (fall back to the person's ordinary Qorionix password). Choose deliberately — deny means an agent outage becomes a login outage for anyone mastered by it.

What to do with this today

• Register an agent and confirm the sync loop is bringing in the users and groups you expect — see Staged import with preview for how to read a sync run's preview and apply decisions.
• Run test delegated auth to prove the mechanism against a real account before you plan around it.
• Do not rely on delegated auth for your actual login flow yet — it isn't in that path.
• If you only need to read users and groups on a schedule with nothing installed inside your domain, the plain LDAP connector in Connecting Active Directory or LDAP may be the simpler answer.