Installing the Active Directory Agent

The Adcyma AD agent is a small Windows service that connects your on-premises Active Directory to Adcyma. It syncs users, groups, and OUs to the portal and runs lifecycle operations (create, update, disable, delete, password reset, group membership) against your domain. You need it when your identity provider mode is Active Directory or Hybrid (Active Directory + Entra ID).

This page covers installation. Once the agent is running, Managing the Active Directory Agent covers suspending it, approving directory cleanups, custom attributes, OU scope, updates, and troubleshooting.

How it works

The agent runs on a Windows server inside your network and makes outbound HTTPS calls only to portal.adcyma.com. No inbound ports need to be opened.
Each cycle it sends a heartbeat, pushes directory changes, and picks up queued work. With the current defaults a cycle starts every 30 seconds. Adcyma support can change the interval per tenant or per agent.
Each agent has its own API key, its own request-signing secret, and its own encryption key. Commands sent to it are encrypted, and its requests to the portal are signed. All of this is baked into your personalized installer, so there's nothing to paste in by hand. How the agent is protected has the details.
Your AD service-account password is typed into the installer on the server and stays there. It is never sent to Adcyma.
In Hybrid mode, AD users and groups are matched with their Entra ID counterparts, so Adcyma sees one identity per person. Users are matched on objectGUID, the value Entra Connect derives onPremisesImmutableId from, so the match holds even when display names differ between the two directories. If an AD user has no GUID match, Adcyma falls back to the UPN, but only against Entra users that are synced by Entra Connect. That stops an AD account from being merged onto an unrelated cloud-only account that happens to share a UPN. Groups are matched on their AD SID, which is what on-premises resources authorize against.

Prerequisites

Identity provider mode set to Active Directory or Hybrid under Administration → Settings → Identity Provider
A Windows server that can reach a domain controller, with local administrator rights to run the installer (a UAC prompt appears)
A domain service account for the agent to act as. It needs rights on the OUs you scope Adcyma to: create and update users, enable and disable accounts, reset passwords, delete users if your offboarding workflows delete accounts, and manage group membership.
Outbound HTTPS (port 443) from the server to portal.adcyma.com
Correct time on the server. The agent's signed requests are rejected if the server clock is more than five minutes off. A domain-joined server that syncs time from the domain is fine.

Step 1: Register the agent

Open Administration → Settings → Identity Provider and scroll to the Active Directory Agent card
Click Register agent
Optionally enter the Server hostname and AD domain. Both are just labels to help you recognize the agent in the list; the agent reports its real details once it's running.
Click Register agent in the dialog. The agent appears with the status Waiting for first contact

If you set up Adcyma through the setup wizard and chose Active Directory there, the wizard has already registered the agent for you. You'll find it on the same card.

Step 2: Download the installer

Click Download installer on the agent's row. You get a personalized executable named like AdcymaADSync-AD-SRV-01-1.0.7.exe, where the last part is the installer version.

Treat the installer as a secret

The installer embeds this agent's API key and signing secret. Don't share it or store it somewhere widely accessible. If you suspect the file leaked, contact support to rotate the agent's keys. Rotation stops the running agent immediately, and it needs a reinstall with a fresh installer.

Downloading the installer again for the same agent is safe. It reuses the same credentials, so the running agent keeps working. The download is blocked while an agent is suspended or revoked.

Step 3: Run the installer on the server

Copy the installer to the target Windows server and run it
Accept the elevation (UAC) prompt
When asked, enter the service account credentials (domain username and password) the agent should use for Active Directory operations

The connection settings are preconfigured; you don't need to enter any URLs or API keys. The installer sets up two Windows services that start automatically: the agent itself, and an updater that keeps it on the latest version.

Step 4: Verify the agent is online

Back on the Identity Provider page, the agent card shows its status:

Status	Meaning
Waiting for first contact	Registered, but the agent hasn't checked in yet
Online	The agent is heartbeating normally and can reach Active Directory
Offline	No healthy heartbeat recently. Either the agent has gone quiet, or it is running but reporting a problem, such as not being able to bind to AD
Suspended	Paused by an administrator; all its requests are rejected
Revoked	Permanently disabled by Adcyma support

Within a few minutes of installation the status should flip to Online, and the card shows the reported domain, agent version, and last-seen time. If it stays on Waiting for first contact, see Troubleshooting.

The first sync brings your AD users, groups, and OUs into Adcyma. Which OUs the agent reads is set by its OU scope; see OU scope.

What the agent syncs

Each cycle the agent reports what has changed in the directory within its scoped OUs. Adcyma stores:

Object	Fields
Users	Distinguished name, UPN, `sAMAccountName`, display name, first name, surname, email, department, job title, company, office, street address, city, state, postal code, country, phone, mobile, employee ID, preferred language, proxy addresses, manager, group memberships, enabled state, `objectGUID`, when created and changed, password last set, account expiry, last logon, and your custom attributes
Groups	Distinguished name, name, `sAMAccountName`, description, email, group scope, group category, members, `objectGUID`, SID, when created and changed
Organizational units	Distinguished name, name, description

A cycle with nothing to report finishes without sending anything, so a quiet directory generates no sync traffic.

When an object disappears from AD, the agent reports it and Adcyma removes it. A user who also exists in Entra ID isn't deleted; Adcyma keeps the Entra record and drops the AD link. Large removals found during a full sync are held for approval first; see Directory cleanups.

Bulk group membership changes

When a role template grants several groups at once, or an onboarding adds a batch of people to the same group, Adcyma sends the whole change as a single command rather than one per group or per member. That means fewer round trips and a change that lands closer to all-at-once.

Two things are worth knowing about how the agent handles them:

A failure in one item doesn't abort the rest. If one group in the batch is outside the agent's scoped OUs or no longer exists, the agent still processes every other item and reports the failures together.
Retries are safe. Every membership change checks the current state before changing anything, so re-running a command that partially succeeded is a no-op for the parts that already went through.

Partial failures surface in the task history with each failed item and its reason, so you can see exactly which group or member didn't take.

Next steps

Managing the Active Directory Agent: suspend and reactivate, directory cleanups, custom attributes, updates, troubleshooting
Security: how agent traffic is encrypted and signed