Managing the Active Directory Agent

Once the agent is installed, most of the work happens without you. This page covers the parts that don't: pausing the agent, approving large directory cleanups, choosing which extra attributes to sync, and what to check when something stops working.

Everything here lives in two places in the portal:

• Administration → Settings → Identity Provider, on the Active Directory Agent card
• Administration → Settings → Preferences, on the Directory custom attributes card

Both cards only appear when your identity provider mode is Active Directory or Hybrid.

Who can do what

Some agent actions are yours. A few are deliberately kept with Adcyma support, because they are either permanent or affect how much of your directory Adcyma can change in one go.

"Tenant admin" means a portal user with the admin role. To get anything in the support column done, email support@adcyma.com.

Agent states

An agent is always in one of three states. This is separate from Online and Offline, which only say whether the agent has checked in recently.

Suspend and reactivate

Click Suspend on the agent's row to pause it. Use it during a maintenance window, while you investigate something odd, or any time you want Adcyma to stop touching AD right now.

Suspending does three things straight away:

• Every request from the agent is rejected, so no sync and no commands
• Commands that were queued for the agent and not yet picked up are cancelled
• The workflow tasks behind those commands are marked failed and go through the normal retry handling, so you see them in the task history rather than having them sit silently

While an agent is suspended, Download installer is disabled. That stops a fresh installer from handing out working credentials for an agent you just paused.

Click Reactivate to resume. The agent picks up again on its next check-in. Commands that were cancelled during the suspension aren't replayed automatically; retry the affected tasks if you still need them.

Revoke

Revocation is for an agent whose credentials you no longer trust, for example a compromised server. Contact support to revoke. A revoked agent stays in the list for audit purposes, shows Revoked, and has no buttons. Queued commands are cancelled the same way as for a suspension.

To connect AD again after a revocation, register a new agent and install it with a new installer.

Removing an agent

There's no delete button in the portal. If you're decommissioning a server, uninstall the Adcyma services from it and ask support to remove the agent. Removing it cancels any commands still queued for it. If you want it to stop immediately while you wait, suspend it first.

Directory cleanups awaiting approval

When an object disappears from AD in the normal course of things, the agent reports it and Adcyma removes it. Full syncs are different: the agent sends the complete list of what it can see, and Adcyma compares it with what it has stored. Anything stored but not in the list is treated as gone.

That comparison is where things can go badly wrong. A changed OU scope, a service account that lost read rights on an OU, or a domain controller having a bad day can all make a large part of your directory look deleted. So Adcyma guards it in two ways.

The full sync has to be provably complete. The agent sends a full sync in chunks and finishes with a count and a SHA-256 fingerprint of everything it sent. If Adcyma's copy doesn't match exactly, nothing is removed. Missing objects stay in Adcyma until the next full sync that does verify.

Large removals wait for a person. How much would be removed decides what happens:

A held cleanup shows up as an amber Directory cleanup awaiting approval notice at the top of the Active Directory Agent card. It tells you how many of your synced objects are missing and what share that is.

<!-- TODO screenshot: /img/ADAgentCleanupAwaitingApproval.png | URL: https://portal.adcyma.com/administration/identity_provider | Amber "Directory cleanup awaiting approval" notice on the Active Directory Agent card with Approve cleanup / Reject buttons. Only appears when a sweep is pending; the demo tenant likely has none, so this may need to stay as a description. Do NOT click Approve or Reject -->

• Approve cleanup removes the missing objects from Adcyma. Users who also exist in Entra ID aren't deleted; they keep their Entra record and lose the AD link. Anything the agent has synced again since the full sync ran is left alone, so a held cleanup approved days later can't remove an object that has come back.
• Reject dismisses the cleanup. Nothing is removed.

Reject it if the number looks wrong, especially right after an OU scope change or a permissions change on the service account. Fix the cause, and the next verified full sync produces a fresh result.

Held cleanups expire after seven days. An expired cleanup can't be approved; approve the one from a later full sync instead.

Custom attributes

On top of the standard fields, the agent syncs a list of extra AD user attributes that you choose. By default that's the 15 Exchange custom attributes, extensionAttribute1 to extensionAttribute15. Many organisations already keep cost centres, contract types, or employee categories there.

Manage the list under Administration → Settings → Preferences, on the Directory custom attributes card.

<!-- TODO screenshot: /img/ADAgentCustomAttributesCard.png | URL: https://portal.adcyma.com/administration/preferences | "Directory custom attributes" card with the attribute table (Attribute / Display name / Synced values). Scroll to it; don't edit or save -->

For each attribute you can:

• Give it a display name. "Cost center" reads better than extensionAttribute3 in a user profile. Up to 64 characters. Leave it empty to show the LDAP name.
• See how many users have a value. The Synced values column shows a user count, or no values yet.
• Remove it with the X, to stop syncing it.

To add one, type its LDAP display name, for example costCenter or one of your own schema extensions, and click Add. If synced data already contains attributes that aren't on your list, they appear under Also present in synced data but not in the list above with a user count, and you can add them with one click. Click Save custom attributes when you're done, or Reset to defaults to go back to extensionAttribute1 to 15.

Limits and rules:

• At most 50 attributes
• Names must be valid LDAP display names: a letter first, then letters, digits, or hyphens
• Credentials, security descriptors, SIDs, certificates, and photos can never be added, even if you type the name. That includes password attributes and LAPS passwords. If you try, the save goes through without them and tells you which names were skipped.
• Values longer than 4,096 characters are cut off
• Custom attributes are read-only. Adcyma syncs them from AD but doesn't write them back.

Changes reach the agent on its next heartbeat, and values appear after the sync that follows.

OU scope and moved users

The agent only reads and changes objects inside its OU scope. Adcyma support sets the scope, either for your whole tenant or for a single agent; an agent-level scope takes priority. If no scope is set, the agent works from the root of the domain.

When the scope changes, the agent checks straight away that the service account can actually read each OU. If it can't, the agent reports a warning to the portal and the card shows the agent as Offline until it's fixed.

How moves are handled:

• A user moved between OUs inside the scope stays the same person in Adcyma. Users are tracked by objectGUID, not by their distinguished name, so the next sync just updates the location.
• A user moved out of the scope looks to the agent like a deleted user, and Adcyma removes them from its view on the next sync. In Hybrid mode, the Entra ID side of that person stays.
• Narrowing the scope can make many objects disappear at once. A large drop is caught by the directory cleanup approval step, so check the numbers before you approve.

Adcyma's lifecycle workflows don't move users between OUs themselves. Moves you make in AD are picked up on the next sync.

What the agent does in your directory

Workflows, access requests, and role templates turn into commands for the agent. It can:

• Create users. The account is created first; profile attributes, manager, and the user's managed group follow once the agent confirms the account exists. New accounts get a random 24-character password.
• Update user attributes: first name, surname, display name, job title, department, company, office, street address, city, state, postal code, country, phone, mobile, email, employee ID, preferred language, description, proxy addresses, and manager. Nothing else can be written. Security-sensitive attributes such as userAccountControl, sAMAccountName, objectSid, and memberOf are blocked.
• Disable and enable accounts
• Delete users. A delete from a workflow is a permanent delete in AD, the same as on the Entra ID side.
• Reset passwords. The user has to change the password at next sign-in.
• Add and remove group memberships, in batches. See Bulk group membership changes.

A manager can only be set in AD if that manager is also synced from AD, because AD stores the manager as a distinguished name. Picking a cloud-only manager for an AD user fails with a message that says so.

If the agent hasn't confirmed a command within 30 minutes, for example because the server is off, Adcyma marks the command expired and the task fails into the normal retry handling. Group removals are only marked complete once the agent confirms them, so access removed through Adcyma never shows as gone before AD actually changed.

Sync status

The agent card shows each agent's reported version and Last seen time. An agent counts as Online while its heartbeats arrive within two sync intervals of each other and it reports itself healthy.

There's no "sync now" button for customers. The agent already reports changes every cycle, so you rarely need one. If you do want a fresh full sync, for example after fixing permissions, contact support.

The Test Connection button on the Identity Provider page tests the Entra ID connection, not the agent. It's hidden in Active Directory mode. In Hybrid mode it only tells you about the Entra side.

Updates

The installer sets up a separate updater service next to the agent. It checks Adcyma for new agent versions and installs them, so you don't need to reinstall for upgrades. Before installing, it checks that the update is code-signed by Adcyma, and it refuses anything that isn't.

Adcyma can release an update to every agent at once, or to a single agent first. The version each agent runs is shown on its row on the agent card.

Keys and rotation

Each agent has three secrets of its own:

Downloading the installer again reuses all three, so it never breaks a running agent.

Rotation is done by Adcyma support. Ask for it if an installer may have leaked or the server was compromised. Rotation issues a new API key, signing secret, and encryption key at once. The running agent stops working the moment it happens, and any commands queued under the old key can no longer be decrypted. Download a fresh installer and reinstall on the server to recover.

How the agent is protected

The agent talks to Adcyma over HTTPS, and every request also has to pass checks of its own:

• API key. Each request carries the agent's own key. A key belongs to one agent and one tenant.
• Request signing. The agent signs each request with HMAC-SHA256, using its signing secret. The signature covers a timestamp, the HTTP method, a SHA-256 hash of the request body, and a one-time nonce. Changing any of them breaks the signature.
• Timestamp window. A signed request older or newer than five minutes is refused. That's why the server clock matters.
• Replay protection. Each nonce can be used once. A captured request can't be sent again, even within the five-minute window.
• Encrypted commands. Commands are encrypted with AES-256-GCM under the agent's own key before they're queued. The agent can tell if one has been tampered with.
• State checks come last. Whether an agent is suspended or revoked is only revealed to a request that has already passed the key and signature checks.

Adcyma can require signatures per agent. Once required, an unsigned request from that agent is refused even if the API key is right.

Troubleshooting

The agent never leaves "Waiting for first contact" Check that both Adcyma services are running on the server and that outbound HTTPS to portal.adcyma.com is allowed through your firewall and any proxy.

The agent shows Offline but the service is running The agent is checking in but reporting a problem. The usual causes are that it can't bind to Active Directory (wrong service-account password, account locked or disabled, no domain controller reachable) or that the service account can't read one of the OUs in its scope. Fix the account or its permissions; the status flips back to Online on the next healthy heartbeat.

The agent stops right after a server change or reboot Check the server clock. Signed requests more than five minutes out are refused.

The agent stopped working after a key rotation That's expected. Download a fresh installer from the agent card and reinstall on the server.

AD operations fail even though the agent is online Check that the service account has rights on the affected users and OUs, and that the target is inside the agent's OU scope. Password resets, disables, deletes, and group changes all need matching rights on the target objects. The failure reason is in the task history.

Setting a manager fails The manager has to be synced from AD. A cloud-only Entra user can't be set as manager on an AD account.

The agent shows Suspended An administrator paused it. Click Reactivate on the agent card.