Active Directory and VaultPilot DC Agent Service

VaultPilot DC Agent Service runs near the domain controller and synchronizes directory metadata into VaultPilot. It does not send the AD bind password or AD user passwords to VaultPilot.

VaultPilot manages provider health, directory scope, login eligibility, credential-import scope and agent actions separately. A successful directory sync does not authorize every user or every credential workflow.

Service identity

Enrollment flow

1. Open VaultPilot: Integrations -> Active Directory.
2. Create an agent record.
3. Download vaultpilot-dc-agent.ps1 from the VaultPilot UI or the official release.
4. Run the install command on the agent machine from an Administrator PowerShell.

powershell -NoProfile -ExecutionPolicy Bypass -File "$env:USERPROFILE\Downloads\vaultpilot-dc-agent.ps1" -InstallService -PassManUrl "<VAULTPILOT_URL>" -AgentId "<AGENT_ID>" -PromptAgentToken -TrustPassManCertificate

Keep the option names -PassManUrl and -TrustPassManCertificate exactly as shown; they are kept from the product’s earlier name.

The script asks for:

• Domain controller IP or hostname.
• AD bind username.
• AD bind password through the local terminal prompt.

Passwords and the agent token are accepted only through the local secure PowerShell prompt. Never place the agent token on the command line, in terminal history, or in documentation. The AD bind password is not sent to VaultPilot, and secret values are not written to logs.

Version and readiness check

VaultPilot 3.0.3 ships DC Agent 1.2.27. In Status, both the service and the PowerShell worker should report 1.2.27 and ready. A successful directory sync does not upgrade the agent. Agents older than 1.2.20 can still sync, but unlock, require password change, random password assignment and account disable stay unavailable until you update. If VaultPilot cannot confirm the identity of a target account, these sensitive actions stay blocked.

The current package is vaultpilot-dc-agent.ps1. If your server still offers an older script, clear the browser cache and download it again; do not judge the service version from sync success.

Operations commands

powershell -ExecutionPolicy Bypass -File .\vaultpilot-dc-agent.ps1 -Status

powershell -ExecutionPolicy Bypass -File .\vaultpilot-dc-agent.ps1 -TailLog

powershell -ExecutionPolicy Bypass -File .\vaultpilot-dc-agent.ps1 -RepairService -PromptAgentToken

For an installed service, use Rotate token on the existing provider card. The generated repair command keeps the same Windows service and can keep or update the DC host and bind username.

Rotating the token invalidates the previous token immediately. Copy the replacement separately; the repair command must contain only -PromptAgentToken, and the token must be pasted only into the local secure prompt.

powershell -ExecutionPolicy Bypass -File .\vaultpilot-dc-agent.ps1 -UninstallService

What appears in VaultPilot

After sync, the Active Directory tab shows:

• Provider status and last sync.
• Domain controller, domain, base DN and agent version.
• OU, group and user tree with search.
• Separate checkbox scopes for login access and credential import.
• Import action for selected credential candidates.

Data and action boundary

The agent collects only OU, group, and user metadata. It never reads or sends AD passwords, password hashes, Kerberos tickets, vault keys, or plaintext secrets.

A ready agent at 1.2.20 or newer can unlock an account, require a password change at next sign-in, assign a random password under the global password policy, and disable an account. Built-in identities and the agent’s own bind account are always protected. Automated rotation of a privileged account that is not built in also needs an explicit standing policy approval; a manual action asks for its own second confirmation.

Post-sync vault reconciliation

A successful agent sync refreshes the provider’s directory list. Encrypted records for users selected for vault import can then receive identity and AD-state updates while the matching writable vault is unlocked in an authorized browser. The server and agent cannot decrypt a vault record, so these updates complete only in that browser.

Reconciliation never replaces an existing password with blank AD data. A user missing from the directory or removed from selection does not silently delete the encrypted record. Provider sync and vault update are separate outcomes; inspect failed entries in a partial batch before retrying.

Hardening notes

• Prefer DOMAIN\username or username@domain.local for bind users.
• Use a delegated account with the narrowest read scope that meets the sync need.
• Keep the agent on a controlled Windows host close to the DC.
• Rotate the agent token if the setup command was copied into an unsafe channel.
• Use the VaultPilot UI to revoke or recreate the agent record when rebuilding the agent machine.

Troubleshooting

Back to Documentation →