Overview

Imper.ai enables secure Active Directory password reset and account unlock operations by connecting to your Domain Controllers over LDAPS using a Linux VM that runs the Twingate Connector, deployed within your network.

No software or agent is installed on your Domain Controllers.

All connectivity is initiated from Imper.ai through the encrypted Twingate network to a Linux VM you provision that runs the Twingate Connector, which then communicates with your Domain Controllers over LDAPS.

---

Traffic Flow

Imper.ai service → Twingate secure network → Domain Controller(s) over LDAPS → Active Directory

This design ensures:

• No inbound access into your network

• Communication limited to your Domain Controllers

• Encrypted directory communication via LDAPS

• Minimal infrastructure changes required

---

Prerequisites

Make sure the following are in place before you start the setup:

• A connected identity provider - for example, Google Workspace or Entra - must already be connected.

• A dedicated Linux virtual machine. Ubuntu 22.04 LTS or Red Hat Enterprise Linux 8+, with 2 vCPU, 2 GB RAM, and 20 GB disk, on a network that can reach your Domain Controllers.

• Access to your Domain Controllers. Know the address of each Domain Controller you plan to manage (one per domain) and make sure it is reachable over LDAPS. For a multi-domain forest, have an address ready for each domain. See Choosing Your Domain Controllers.

• An Active Directory service account with the delegated permissions described in Service Account and Required Permissions.

• Firewall rules for the Linux VM, following the connectivity tables in Step 2.

• A cloud password-sync mechanism (if your users sign in through a cloud identity provider with their AD password). Without it, a reset updates only the on-premises password and never reaches cloud sign-in. See Cloud Password Sync.

• The CA certificate that issued your Domain Controllers' LDAPS certificates (optional). Provide it if you want to enable certificate verification. See Step 4.

---

Choosing Your Domain Controllers

Imper.ai requires one Domain Controller address for each domain you want to manage. Each Domain Controller must be:

• Writable - password reset and unlock are write operations, so Read-Only Domain Controllers (RODCs) are not supported.

• Reachable over LDAPS (TCP 636) from the Linux VM.

The primary Domain Controller should also be a Global Catalog server - Imper.ai uses the Global Catalog (TCP 3269) on it for forest-wide user lookups.

You can change Domain Controller addresses later from the integration menu (Configure Domain Controllers).

NOTE

Using Microsoft Entra with Password Hash Synchronization? The DC you pick affects how fast a reset reaches cloud sign-in - see Cloud Password Sync.

NOTE

Multi-domain forest? A few extra rules apply - see Multi-Domain Forests.

---

Service Account and Required Permissions

Create a dedicated Active Directory service account for Imper.ai. Do not reuse an existing administrative account.

Required permissions

Grant the delegations below at the domain root, on the CN=Users container, or on the top-level Organizational Units (OUs) that contain the managed users. Delegations at the domain root with inheritance enabled cover all users automatically.

Capability	Required delegation
Look up and read user accounts	Read all properties on user objects
Reset passwords	Reset Password extended right and Write pwdLastSet on user objects
Unlock locked accounts	Write lockoutTime on user objects

NOTE

Both permissions in the reset row are required: every password reset updates pwdLastSet together with the password.

Granting the permissions

Grant all the permissions on the Security tab.

IMPORTANT

In a multi-domain forest, you must grant these permissions in every domain you manage. A permission entry applies only to the domain where you set it and does not carry across domains, so repeat these steps once per domain.

1. In Active Directory Users and Computers, enable View -> Advanced Features.

2. Right-click the domain root or the OU that contains your managed users, select Properties, open the Security tab, and click Advanced.

3. Click Add, then Select a principal and choose the Imper.ai service account.

4. Set Applies to to Descendant User objects.

   

5. In the permission list, check each of the following:

   • Read all properties
   • Reset password
   • Read pwdLastSet
   • Write pwdLastSet
   • Read lockoutTime
   • Write lockoutTime
   

6. Click OK to apply.

NOTE

Protected accounts (members of AdminSDHolder-protected groups such as Domain Admins) do not inherit delegated permissions, so they cannot be managed through this integration.

After you connect, Imper.ai runs a permissions verification against every configured domain and reports exactly which grant is missing, if any.

NOTE

A newly granted permission can take a few minutes to appear in the permissions check while Active Directory replicates the change - for example, a permission granted in a child domain. If the Permissions step reports a grant as missing right after you set it, wait for replication and run the check again.

---

Deployment Steps

Step 1 - Integrate with imper

1. Login to imper.ai admin console

2. Navigate to the Integrations page

3. click connect on the Active Directory integration

   

4. Choose Install AD Connector

   

---

Step 2 - Provision a Dedicated Linux VM

Deploy a Linux virtual machine to run the Twingate Connector.

Recommended VM configuration

Parameter	Value
Operating System	Ubuntu 22.04 LTS or Red Hat Enterprise Linux 8+
CPU	2 vCPU
Memory	2 GB RAM
Disk	20 GB

Allow Required Network Connectivity to Domain Controllers

Ensure the Linux VM can reach your Domain Controllers:

source	destination	port	purpose
Linux VM	Domain Controllers	TCP 636	LDAPS - directory reads and writes
Linux VM	Primary Domain Controller	TCP 3269	Global Catalog over SSL - forest-wide user lookup

Make sure the virtual machine (VM) is on a network that can communicate with your Active Directory Domain Controllers.

Allow Required Outbound Internet Connectivity

The Linux VM must reach Twingate's infrastructure so the connector can be installed, enrolled, and stay connected. Verify your firewall permits the following outbound access before continuing:

destination	port	purpose
*.twingate.com	TCP 443	Twingate controller - enrollment and control channel
pubsub.pubnub.com, ps.pndsn.com, h2.pubnubapi.com	TCP 443	Real-time signaling
Twingate Relay - Google Cloud external IP ranges and 167.254.176.0/21	TCP 30000-31000	Twingate Relay - carries the encrypted tunnel traffic
binaries.twingate.com, packages.twingate.com	TCP 443	Installer script and connector packages (install and upgrade time)

NOTE

The PubNub hostnames are part of Twingate's official allowlist and are not covered by a *.twingate.com rule - add them explicitly.

IMPORTANT

The relay IP block 167.254.176.0/21 is required by Twingate starting July 10, 2026. Make sure it is in your allowlist.

Outbound UDP is not required - connections to Imper.ai are carried over Twingate's TCP relay.

---

Step 3 - Install & Authenticate Twingate

Click Copy and run the command on the Linux VM.

The command will download, install and then activate Twingate Connector with the credentials we provide. Packages are installed from Twingate's official repository (packages.twingate.com).

Important security note about the credentials

The setup command embeds a secret Twingate OAuth key that enrolls this VM into your tenant's Twingate network. Treat it like private key material - do not:

• Commit it to source control

• Upload it to shared documentation systems

• Send it through unsecured channels

• Reuse it outside the specific Linux VM it was issued for

The key is used only to enroll this VM.

Local validation after the installation completes

After the script finishes, validate from the Linux VM that local LDAPS connectivity to your Domain Controller works, for example:

timeout 3 bash -c '</dev/tcp/YOUR_DC_ADDRESS/636' && echo "LDAPS reachable"
timeout 3 bash -c '</dev/tcp/YOUR_PRIMARY_DC_ADDRESS/3269' && echo "Global Catalog reachable"

NOTE

Note: This check only verifies local connectivity from the router VM to your DC. imper.ai will validate the Twingate path from our side after the route is approved.

---

Step 4 - Enter Credentials and Connect

Make sure the service account from Service Account and Required Permissions already exists, then continue through the remaining steps of the setup dialog in the imper.ai console.

Credentials. Enter:

• Primary Domain Controller IP - see Choosing Your Domain Controllers

• Service Account Username - UPN preferred, for example svc-imper-ad-reset@contoso.com

• Service Account Password

• CA certificate (optional) - upload the certificate that issued your Domain Controller's LDAPS certificate to enable certificate verification. If omitted, verification is disabled. To export the certificate, see Exporting the CA Certificate below.

Configure Domains. imper.ai lists the domains discovered in your forest. Confirm or enter one Domain Controller address for each domain you want to manage, then press Connect.

Permissions. imper.ai checks the service account across every configured domain and shows, per domain, whether Reset passwords and Unlock accounts are granted. If anything is missing, grant it in Active Directory, run the check again, then press Done. You can re-run this check later from the integration menu.

---

Exporting the CA Certificate

Optional, and only needed if you want to upload a CA certificate in the Credentials step to enable TLS certificate verification. Export the certificate of the CA that issued your Domain Controller's LDAPS certificate. The uploaded file must be Base-64 (PEM) encoded.

Option 1 - GUI

Run certlm.msc and locate the issuing CA certificate (for example contoso-ad-EC2AMAZ-LSQPDGV-CA):

• On a Domain Controller (which is also your issuing CA): under Personal -> Certificates.

• On a domain-joined Windows machine that is not the Domain Controller: under Trusted Root Certification Authorities -> Certificates for a root CA, or Intermediate Certification Authorities -> Certificates for a subordinate CA.

Then:

1. Right-click the certificate

2. Select All Tasks -> Export

3. In the wizard, select No, do not export the private key

4. Select Base-64 encoded X.509 (.CER)

Upload the exported .CER file in the Credentials step.

Option 2 - PowerShell export by thumbprint

If you know the CA certificate thumbprint:

Export-Certificate -Cert (Get-Item "Cert:\LocalMachine\CA\CA_THUMBPRINT_HERE") -FilePath C:\ca-der.cer
certutil -encode C:\ca-der.cer C:\ldaps-issuing-ca.cer

Cert:\LocalMachine\CA is the Intermediate store - use Cert:\LocalMachine\Root for a root CA. Then upload C:\ldaps-issuing-ca.cer in the Credentials step.

---

Multi-Domain Forests

If your Active Directory is a multi-domain forest:

• After the connector activates, Imper.ai discovers every domain in the forest and lists them in the Configure Domains step.

• Provide one Domain Controller address per domain whose users you want to manage. Domains without a configured DC are not managed. A second DC that resolves to an already-configured domain is ignored.

• The domain where the service account lives must have a configured DC, otherwise the setup verification cannot complete.

• User lookups run forest-wide through the Global Catalog on the primary DC. Each reset or unlock is then performed against the user's home-domain DC over LDAPS.

---

Cloud Password Sync

The AD Connector changes the password in on-premises Active Directory. If your users sign in through a cloud identity provider with that password, your tenant needs a way to carry the change to the cloud:

• Microsoft Entra ID / Microsoft 365 - Password Hash Synchronization, Pass-Through Authentication, or federation.

• Google Workspace - a password-sync solution such as Google Password Sync. Google Cloud Directory Sync syncs users and groups, not passwords.

Without one of these, a reset changes only the on-premises password and cloud sign-in is unaffected. Account unlock is always an on-premises operation and never depends on cloud sync.

Sign-in Delay with Password Hash Synchronization

Applies only to Password Hash Synchronization. Pass-Through Authentication and federation validate on-premises, so a reset takes effect immediately.

Password Hash Synchronization reads changes from one Domain Controller and pushes them to Entra every few minutes (about 2 minutes for Entra Connect, 2–5 for Cloud Sync). A reset reaches the cloud only once it is on the DC the sync agent reads.

Point Imper.ai at a Domain Controller in the same Active Directory site as your sync agent, ideally the same DC. Replication within a site is near-immediate. Your AD team can tell you which DC the sync agent uses.

If the DC is in a different site, the reset must replicate across sites first. Inter-site replication is scheduled by default (Microsoft default 3 hours, 15-minute minimum), so cloud sign-in can lag a reset by 15 minutes to a few hours. Your AD team can enable replication change notification (the USE_NOTIFY option on the site link) to make inter-site replication near-immediate.

NOTE

This delay affects cloud sign-in only. On-premises sign-in works right away - a reset replicates immediately to the PDC emulator, and a DC checks the PDC before rejecting a sign-in.

---

What Imper.ai Will Configure Next

After receiving the required information, Imper.ai will:

• Add a resource for each of your Domain Controllers in your tenant's Twingate network

• Grant access to those resources only to your tenant's dedicated connector - no other tenant or system can reach them

• Configure the Imper.ai connector to:

  • Connect using LDAPS (TCP 636) and the Global Catalog (TCP 3269)

  • Verify the Domain Controller certificate chain against your CA certificate (if provided)

  • Authenticate using the provided service account

  • Perform password resets or account unlock using LDAP operations

• Run a permissions verification against every configured domain and surface any missing delegation

---

Twingate Auth Key and VM Rebuilds

The Twingate authentication key is saved and used by the router VM to authenticate with the Twingate network.

No further action is required unless one of the following occurs:

• The Linux VM is rebuilt or replaced

• Twingate is uninstalled

• The node is removed from the Twingate network

If any of these events occur, contact Imper.ai to obtain a new authentication key, and reintegrate.

---

Troubleshooting

Reset Twingate Connection State (Clean Re-enrollment)

If the Twingate connector on the router VM is in a bad state (for example, the node does not re-register, or you need to fully start over), reset the local state and re-run the setup script.

1. Uninstall the Twingate service.

On Ubuntu:


sudo apt purge twingate-connector 

On Red Hat Enterprise Linux:


sudo dnf remove twingate-connector 

2. Re-run the setup command provided by imper.ai.
   The node will register as a new connector device.

After re-enrollment, proceed normally through the imper.ai admin portal.

---

Common Issues

1. No CA certificate provided

   1. TLS certificate chain verification is skipped.

   2. The connection still works but with reduced security guarantees.

2. Missing AD permissions

   1. Password reset or account unlock operations fail because the service account lacks the required delegated rights.

   2. The permissions verification in the imper.ai console shows which delegation is missing and in which domain - re-run it after fixing the delegation.

3. "Service account domain not yet configured"

   1. The service account lives in a child domain that has no Domain Controller configured. Add a DC address for that domain in Configure Domain Controllers.

4. Unlock fails for a disabled account

   1. Accounts that are administratively disabled cannot be unlocked through the integration - unlocking only clears the lockout state, it does not enable a disabled account.

5. User not found

   1. Users are matched by their identity provider email against the on-premises userPrincipalName (UPN). If a user's email does not match their UPN, the lookup fails - align the UPN or contact Imper.ai support.

6. Protected admin accounts

   1. Members of protected groups (Domain Admins, etc.) do not inherit delegated permissions (AdminSDHolder) and cannot be managed through this integration.

7. Firewall or egress rules block the connector

   1. The Linux VM cannot enroll or stay online if its outbound access to Twingate is blocked. Confirm the egress allowlist from Step 2.

8. Password reset succeeds on-premises but cloud sign-in still fails

   1. With Password Hash Synchronization or Google Password Sync, a reset updates the on-premises password immediately but reaches cloud sign-in only after the change synchronizes. If the Domain Controller Imper.ai writes to is in a different Active Directory site from the one that feeds sync, this can lag from 15 minutes to a few hours. See Cloud Password Sync.

---