Active Directory (AD) Microsoft

Purpose

The integration enables AirMDR to:

Retrieve user identities, account status, and group memberships.
List directory users and groups for investigation.
Disable or administratively lock user accounts during incident response.
Restore account access using the Unlock skill.

Pre-requisites

An AD DS domain controller with LDAPS configured.
A dedicated service account with the required delegated permissions.
The domain controller hostname or IP address and directory Base DN.
An AirMDR Remote Agent that can reach the domain controller on TCP port 636.
Permission to create and manage integration connections in AirMDR.

Use an internal Remote Agent for private domain controllers. Do not expose a domain controller to the public internet to establish connectivity.

Supported Versions

According to the SME requirements, the integration supports:

Component	Supported configuration
Directory service	Microsoft Active Directory Domain Services
Windows Server	2012, 2016, 2019, 2022, and 2025
Deployment	On-premises AD DS
Authentication	Simple LDAP bind using username and password
Recommended connection	LDAPS on TCP port `636`

Unsupported configurations

Microsoft Entra ID through LDAP.
StartTLS upgrade on port 389.
SASL authentication with Kerberos/GSSAPI or NTLM sign-and-seal.
Integration compatibility does not establish whether a Windows Server version remains within Microsoft’s support lifecycle.

Authentication Method

AirMDR authenticates using a dedicated AD service account and a simple LDAP bind.Use LDAPS to encrypt the connection before sending the bind credentials.

Accepted username formats

Format	Example
User Principal Name — recommended	`airmdr-service@company.com`
Full distinguished name	`CN=AirMDR Service,CN=Users,DC=company,DC=com`

Do not enter a bare short username such as airmdr-service as the connection’s bind identity. Use the SME-supported UPN or full DN format.

LDAP ports: 389 vs 636

Most Active Directory connection failures come down to this choice, so it is worth understanding rather than copying.

Port 389 — plaintext LDAP

The traditional LDAP port. A simple bind sends the service account password with no encryption and no integrity protection.On a current, patched domain controller this is normally refused. Microsoft hardening — delivered through Windows Update and governed by the policy Domain controller: LDAP server signing requirements — makes the domain controller reject unsigned simple binds:

LDAPStrongerAuthRequiredResult - 8 - strongerAuthRequired
00002028: LdapErr: DSID-0C09033F, comment: The server requires binds to turn on
integrity checking if SSL\TLS are not already active on the connection, data 0

Read that message carefully: the domain controller is rejecting the connection, not the credentials. A completely correct username and password still produces this error on port 389.

This is the usual explanation when a previously working Active Directory integration stops authenticating after a patch cycle. Nothing about the service account changed — the domain controller’s policy did.

Port 636 — LDAPS

TLS is negotiated the moment the connection opens, before any LDAP is exchanged. By the time the bind is sent the channel is already encrypted, which satisfies the signing requirement. This is the configuration to use.

Use SSL and Port must agree

These are two independent fields, and setting one without the other produces errors that look unrelated to the real cause:

Use SSL	Port	Result
`true`	`636`	Correct. TLS handshake, then bind.
blank	`389`	Rejected with `strongerAuthRequired` when signing is required. Works only on an unhardened domain controller.
`true`	`389`	Fails. A TLS handshake is sent into a plaintext port. Appears as `UNEXPECTED_EOF_WHILE_READING` or `session terminated by server`.
blank	`636`	Fails. Plaintext LDAP is sent into a TLS port. Appears as `session terminated by server`.

If Port is left blank it defaults to 636 when Use SSL is true, and 389 when it is not. Setting both explicitly is clearer.

Certificate validation

The domain controller’s TLS certificate is not validated — neither the issuing chain nor the hostname. The connection is encrypted, but it is not authenticated against a trusted certificate authority.

Domain controllers are usually issued certificates by an internal CA that AirMDR does not hold, and the Server field is frequently an IP address. A self-signed or internal-CA certificate on the domain controller therefore works without any import or trust configuration on the AirMDR side.

Why LDAPS is effectively mandatory

The other supported way to satisfy a signing requirement on port 389 is SASL sign-and-seal (Kerberos/GSSAPI or NTLM), which this integration does not implement — it performs simple binds only. StartTLS is likewise not implemented. If a domain controller cannot offer LDAPS on port 636, this integration cannot connect to it.

Required permissions

Capability	Required access
Fetch users and groups	Read access to the relevant user and group objects within the search scope.
Disable User	Write access to `userAccountControl` on target user objects.
Lock Account	Write access to `userAccountControl` on target user objects.
Unlock Account	Write access to both `userAccountControl` and `lockoutTime` on target user objects.

Delegate write permissions only on OUs containing accounts approved for response actions. Domain Admin membership is not required.

Credential reference table

Field	Required	Example	Guidance
Server	Yes	`dc01.company.com` or `192.168.1.25`	Domain controller hostname or IP. A hostname must resolve from the Remote Agent’s network, not from AirMDR. If DNS is uncertain, an IP address is the safer choice.
Port	No	`636`	`636` for LDAPS, `389` for plaintext. Blank defaults to `636` when Use SSL is `true`, otherwise `389`. Set it explicitly.
Use SSL	No; set for LDAPS	`true`	The literal word `true`, case-insensitive. Must be paired with port `636`.
Username	Yes	`airmdr-service@company.com` or `CN=AirMDR Service,CN=Users,DC=company,DC=com`	The service account’s UPN or full DN. The UPN form is recommended.
Password	Yes	Service account password	The current password. An expired one returns `data 532`.
Base DN	Yes	`DC=company,DC=com`	Root scope for searches. Individual skills can narrow this per call with `search_base`.

Values that silently fail

Each of these is accepted by the form and then misbehaves, usually with an error that points somewhere else:

Field	Do not enter	What happens
Use SSL	`1`, `yes`, `on`, `enabled`, `True` with a trailing space	Read as false, with no warning. The connection attempts plaintext LDAP and fails as though the port or credentials were wrong. Enter `true`.
Username	`airmdr-service`	A bare `sAMAccountName` is not a bind identity. Returns `data 52e`, which is indistinguishable from a wrong password.
Username	`COMPANY\airmdr-service`	Not accepted as a bind identity by this integration. Use the UPN or full DN.
Username	`CN=AirMDR Service,OU=Users,DC=company,DC=com`	The built-in Users container is `CN=Users`, a container, not an OU. Use `OU=Users` only if a real OU with that name holds the account.
Server	`ldaps://dc01.company.com` or `dc01.company.com:636`	Enter the bare hostname or IP only. No scheme, no port suffix.
Base DN	`company.com`	Must be in DN form: `DC=company,DC=com`.

Use SSL and Port are the pair that most often goes wrong. See LDAP ports: 389 vs 636 for every combination and the error each one produces.

Setup Steps

Identify the LDAP Server (Domain Controller)

Obtain the domain controller hostname from your AD administrator.
Alternatively, run the following command from a domain-connected Windows machine:
nltest /dsgetdc:company.com
Record the returned domain controller hostname.
This command discovers a domain controller. It does not verify that LDAPS is listening on port 636.

Configure and test LDAPS

Ask the AD administrator to configure an appropriate domain controller certificate for LDAPS.
Ensure the certificate meets Microsoft’s LDAPS requirements, including the Server Authentication purpose.
From the Remote Agent host, or a Windows machine with equivalent network access, run:
Test-NetConnection -ComputerName dc01.company.com -Port 636
Confirm that the result includes:
TcpTestSucceeded : True
This confirms TCP connectivity only. It does not verify the LDAP bind, TLS certificate identity, or delegated permissions.

Create a dedicated service account

A dedicated service account should be created for the integration.

Navigate to open Server Manager → Tools → Active Directory Users and Computers.
Click on “Create a new user in the current container”.
Enter the required Field Values.
Field Value (Example)
First Name AirMDR
Last Name Service
User Logon Name airmdr-service
Click Next.
Configure password settings:
- Set a secure password
- Uncheck User must change password at next logon
- Enable Password never expires (recommended for service accounts)
Click Finish.

The service account will be used as the LDAP bind user.

Field	Value (Example)
First Name	`AirMDR`
Last Name	`Service`
User Logon Name	`airmdr-service`

Delegate the required permissions

Identify the OUs containing users that AirMDR may investigate or modify.
Have an AD administrator delegate read access for discovery skills.
Delegate write access to userAccountControl for Disable and Lock.
Delegate write access to userAccountControl and lockoutTime for Unlock.
Validate the delegation using an approved test account.
A successful LDAP bind does not confirm that the service account can modify user objects.

Retrieve the bind identity

Use the service account’s UPN, for example:

airmdr-service@company.com

To retrieve its full DN:

Open Active Directory Users and Computers.
Enable View → Advanced Features.
Open the service account’s Properties.
Select Attribute Editor.
Copy the value of distinguishedName.
Example:
CN=AirMDR Service,CN=Users,DC=company,DC=com
The default Users container is CN=Users. Use OU=Users only if the account actually resides in an OU with that name.

Retrieve the Base DN

For the domain company.com, the domain Base DN is:

DC=company,DC=com

To confirm it using the Active Directory PowerShell module:

Get-ADDomain | Select-Object -ExpandProperty DistinguishedName

Use a narrower OU DN when appropriate:

OU=Employees,DC=company,DC=com

Prepare the Remote Agent

Install and register an AirMDR Remote Agent using your approved deployment procedure.
Confirm the agent is online.
Confirm it can resolve the domain controller hostname.
Allow connectivity from the agent to the domain controller on TCP port 636.

Configure Active Directory in AirMDR Integrations Dashboard

Navigate to AirMDR, provide the credentials and click Login.
Navigate to the AirMDR Integrations Dashboard in the left navigation pane and select Integrations.
Use the search option, enter the keyword “Active Directory”, select the Connections tab, and click + Add New Connection.
Enter an unique name to the Instance (e.g., your org name-Active Directory) and brief Description to easily identify the user connection by AirMDR.

Use the following values in the AirMDR integration configuration screen:

Field	Example value
Server	`dc01.company.com`
Port	`636`
Use SSL	`true`
Username	`airmdr-service@company.com`
Password	Current service account password
Base DN	`DC=company,DC=com`

Expand Advanced Configuration if required. (Optional)

Setting	Configuration guidance
Remote Agent	Select the registered agent that can reach the domain controller. An online agent must also be explicitly linked to this connection.
Expiry	If displayed, configure according to your organization’s connection lifecycle policy. The SME file does not define its exact behavior; confirm whether expiry disables the connection or requires renewal before documenting that behavior.

Click Save.
Reopen the settings and confirm the Remote Agent is still selected.

Re-check the Remote Agent after every edit. Saving a change to the connection can clear the attached agent. The agent still reports as online, because agent health is tracked independently of whether any connection references it — so nothing in the UI indicates the link was lost. The connection then falls back to a direct connection attempt and fails after roughly 10 seconds with no remote agent is linked to this connection.

Skills Provided by this Integration

The Active Directory integration provides skills to retrieve user and group information, contain compromised accounts, and unlock user accounts. Every skill also accepts an optional Instance input naming which Active Directory connection to use; leave it blank when only one is configured.

User Discovery & Investigation

Skill	Inputs	Behavior
Fetch Active Directory (Onprem) User	Required: `username`	Retrieves one user by `sAMAccountName` — the short logon name, e.g. `jdoe`, not `COMPANY\jdoe` or `jdoe@company.com`. Exact-match and case-insensitive. Returns identity, contact, membership, account status and logon attributes.
Fetch Active Directory (Onprem) User Roster	Optional: `search_base`, `page_size`	Retrieves users through paged LDAP queries. Default page size: `500`; supported input range: `1–1000`. Returns fewer attributes than the single-user skill.

Group Discovery & Membership Investigation

Skill	Inputs	Behavior
Fetch Active Directory (Onprem) Groups	Optional: `search_base`	Lists groups without expanding membership.
Fetch Active Directory (Onprem) Group Details	Required: `group_name`	Retrieves group metadata and the complete list of direct member DNs.

Use the group’s sAMAccountName for group_name. Direct membership does not represent recursively expanded nested membership.

Account Containment & Response

Skill	Inputs	Behavior and result
Disable Active Directory (Onprem) User	Required: `username`	Sets `ACCOUNTDISABLE` (`0x0002`) in `userAccountControl`. Returns `disabled` or `already_disabled`.
Lock Active Directory (Onprem) Account	Required: `username`	Uses the same disabled flag as Disable. Returns `locked` or `already_locked`. Requires explicit restoration; there is no automatic expiry.

Lock is an administrative disable action. It does not create a native AD lockout by writing a non-zero lockoutTime.

Account Recovery

Skill	Inputs	Behavior and result
Unlock Active Directory (Onprem) Account	Required: `username`	Clears `ACCOUNTDISABLE` and resets `lockoutTime` to `0`. Returns `unlocked` or `already_unlocked`, with `cleared_admin_lock` and `cleared_ad_lockout` indicators.

Important: Unlock can re-enable an account previously disabled for administrative or security reasons. Confirm authorization before execution.

To view the details of Input Parameters and Output for the respective skills

Go to AirMDR → Active Directory Integration page.
Select the Skills tab and click on the required listed skills.

Validate Connectivity

Verify authentication and skills

Select Verify Authentication.
Confirm that the bind succeeds.
Run Fetch Active Directory (Onprem) User against a known test user.
Verify the returned identity and account attributes.
Test response skills only against an approved test account.
Fetch the user again to confirm the resulting account state.

Verify Authentication performs a bind only. It does not test the Base DN search scope or response permissions.

Configuration reference

The following JSON illustrates the configuration values. It is not a documented import or API payload:

{
  "Server": "dc01.company.com",
  "Port": 636,
  "Use SSL": "true",
  "Username": "airmdr-service@company.com",
  "Password": "<service-account-password>",
  "Base DN": "DC=company,DC=com"
}

Additional Information

🧰 Error Handling

The message shown when Verify Authentication fails identifies the cause precisely. Match it here rather than assuming a credential problem.

Message	Cause	Resolution
`the account exists but the credential was rejected` (`data 52e`)	Wrong password, or a bind DN that does not resolve.	Confirm the password. Check `CN=Users` against `OU=Users`, and that the CN matches the object’s real `cn` rather than its display name. The UPN form avoids both mistakes.
`The server requires binds to turn on integrity checking` (`strongerAuthRequired`)	Connecting on port `389` to a domain controller that requires signing. The credentials are fine.	Set Use SSL to `true` and Port to `636`.
`session terminated by server`	Use SSL and Port disagree, or nothing is serving LDAP at that address.	Make them agree (`true` + `636`, or blank + `389`). If they already agree, confirm Server points at a domain controller.
`UNEXPECTED_EOF_WHILE_READING`	A TLS handshake was attempted against a plaintext port.	Set Port to `636`.
`Could not open an LDAP connection directly to …`, after about 10 seconds	No Remote Agent is attached to this connection.	Attach the agent, and re-check after every save.
`Could not reach the remote agent gateway`	AirMDR could not reach its own agent gateway. The domain controller was never contacted.	Raise a support ticket; this is an AirMDR-side infrastructure issue.
`the account is locked out` (`data 775`)	The service account itself is locked out.	Unlock it in Active Directory.
`the account password has expired` (`data 532`) or `must reset its password` (`data 773`)	Service account password expired.	Reset it and enable Password never expires.
`the account is disabled` (`data 533`)	Service account disabled.	Re-enable it.
`the account does not exist in this directory` (`data 525`)	The bind DN does not resolve.	Correct Username; prefer the UPN form.
`Missing required keys: …`	A required field was left blank.	Supply Server, Username, Password and Base DN.

Use the response time as a signal. A real answer from a domain controller arrives in well under a second. A verification that takes about 10 seconds never reached your domain controller at all — that is the no-Remote-Agent timeout, not a credential failure.

If a fetch skill returns User 'x' not found in Active Directory, the lookup matched nothing: the skills match sAMAccountName exactly (case-insensitive), so check the short logon name and confirm the object sits within the Base DN or the supplied search_base.

🔄 Monitoring & Logs

Monitor skill executions and Active Directory logs to identify connection failures, investigate errors, and track account changes.Where to Review Logs

Log source	What to review
AirMDR skill execution details	Review the executed skill, input parameters, returned results, and errors associated with the investigation or playbook.
Domain controller Security log	Open Event Viewer → Windows Logs → Security to review account-management events. Enable the relevant audit policies to capture these events.
Domain controller Directory Service log	Review LDAP signing and channel-binding events when troubleshooting connection or authentication compatibility.
Remote Agent logs, if used	Review connectivity, DNS resolution, TLS certificate validation, and LDAP connection errors.

Account Events to Monitor

Enable Audit User Account Management on domain controllers and monitor these Windows events.

Event ID	Event	Monitoring purpose
4725	A user account was disabled.	Identify the affected account and the identity that performed the action.
4740	A user account was locked out.	Investigate account lockouts and correlate them with authentication activity.
4722	A user account was enabled.	Raised by the Unlock skill when it clears `ACCOUNTDISABLE`.
4767	A user account was unlocked.	Raised only when a real domain-controller lockout is cleared. Verify that unlock actions were authorized.

The Lock Account skill does not write lockoutTime and therefore does not raise 4740. Lock and Disable both set ACCOUNTDISABLE, so they surface as 4725; Unlock re-enables the account and surfaces as 4722, plus 4767 only when a genuine domain-controller lockout was also cleared. Validate the exact events in your own environment, and use the skill execution record together with the resulting account attributes to confirm the outcome.

Recommended Monitoring

Alert on repeated authentication failures, connection timeouts, and insufficient-access errors.
Investigate unexpected disable, lock, or unlock actions, especially those affecting privileged accounts.
Correlate account changes with the AirMDR case or playbook, execution time, target account, and integration account.
After a response action, use Fetch Active Directory (Onprem) User to verify the resulting account status.
Retain logs according to your organization’s security and audit requirements.

Logging GuidelinesUse INFO for routine execution summaries, WARNING for recoverable issues, and ERROR for failed operations, where configurable. Enable DEBUG temporarily during troubleshooting, then restore the normal level.Avoid logging passwords, connection secrets, or complete user attribute responses containing personal information.

🛑 Security & Access Best Practices

✅ Do’s

Use a dedicated integration account. Keep integration activity separate from personal administrator activity.
Apply least privilege. Grant directory read access for discovery skills and delegate only the permissions required for disable, lock, and unlock actions.
Scope access to approved OUs. Restrict delegated permissions to the intended objects. Use search_base to narrow supported queries; query filtering does not enforce authorization.
Encrypt directory connections. Use LDAPS on TCP port 636. StartTLS on port 389 is not supported by this integration, and AirMDR does not validate the domain controller’s certificate or hostname — treat the Remote Agent’s network path to the domain controller as part of your trust boundary. Microsoft Learn
Validate LDAP security compatibility. Test the integration against your domain’s LDAP signing and channel-binding requirements before enforcing policy changes. Microsoft Learn
Protect and rotate credentials. Store credentials in the integration’s credential configuration and update the connection after rotation.
Restrict response skills. Limit who can execute disable, lock, and unlock actions, and require approval where your response process demands it.
Review unlock requests. Confirm that the underlying security issue has been resolved before restoring access.
Audit access periodically. Review delegated permissions, integration account usage, and response activity.

❌ Don’t

Do not use Domain Admin or Enterprise Admin credentials for routine integration operations.
Do not grant write access across the entire directory when only specific OUs require response actions.
Do not send passwords through unencrypted LDAP simple binds or disable certificate validation to resolve connection errors.
Do not include credentials in screenshots, case notes, exported logs, or support tickets.
Do not automatically disable or lock privileged, service, or emergency access accounts without an approved response procedure.
Do not repeatedly retry authentication with invalid credentials; investigate the failure first.
Do not assume that unlocking an account re-enables a disabled account. Verify both account states separately.

👉 Support & Maintenance

📧 Contact AirMDR Support through your designated support channel.
🔁 Rotate credentials regularly in Microsoft Active Directory (AD).
🔄 If a domain controller changes:
- Update the LDAP Server hostname in the integration configuration.
🔄 Reconnect with AirMDR immediately when secrets are changed.

🛑 Data Flow & Security

Data Flow & SecurityData RetrievedThe integration typically queries:

User objects
Group memberships
Email addresses
Account state — userAccountControl, lockoutTime, badPwdCount, pwdLastSet, accountExpires
Logon timestamps — lastLogon, lastLogonTimestamp, whenCreated, whenChanged
Organizational unit placement, as implied by each object’s distinguishedName

objectSid and objectGUID are not requested or returned by any skill. Password material is never read.

Encryption

Layer	Method
In Transit	TLS (LDAPS)
At Rest	Encrypted credential storage in AirMDR

Network Ports

Port	Protocol	Use
636	LDAPS — TLS negotiated on connect	Use this. Required by any domain controller that enforces LDAP signing.
389	LDAP — plaintext simple bind	Legacy only. Refused with `strongerAuthRequired` on a patched domain controller.

Connectivity is outbound from the Remote Agent to the domain controller. No inbound connection to your network is required.

Getting Started

AirMDR Detections

Integrations

API Reference

AirMDR Product Suite

Active Directory (AD) Microsoft

Accepted username formats

Port 389 — plaintext LDAP

Port 636 — LDAPS

Use SSL and Port must agree

Certificate validation

Why LDAPS is effectively mandatory

Values that silently fail

Setup Steps

Configure Active Directory in AirMDR Integrations Dashboard

Skills Provided by this Integration

Validate Connectivity

Additional Information

Account Events to Monitor

Recommended Monitoring

​Accepted username formats

​Port 389 — plaintext LDAP

​Port 636 — LDAPS

​Use SSL and Port must agree

​Certificate validation

​Why LDAPS is effectively mandatory

​Values that silently fail

​Setup Steps

​Configure Active Directory in AirMDR Integrations Dashboard

​Skills Provided by this Integration

​Validate Connectivity

​Additional Information

​Account Events to Monitor

​Recommended Monitoring

Accepted username formats

Port 389 — plaintext LDAP

Port 636 — LDAPS

Use SSL and Port must agree

Certificate validation

Why LDAPS is effectively mandatory

Values that silently fail

Setup Steps

Configure Active Directory in AirMDR Integrations Dashboard

Skills Provided by this Integration

Validate Connectivity

Additional Information

Account Events to Monitor

Recommended Monitoring