Skip to main content

Microsoft Active Directory

Visualize Microsoft Active Directory users, groups, and devices, and monitor changes through queries and alerts.

Installation​

To use this integration, you must create a Microsoft Active Directory account capable of executing Active Directory read queries (It is strongly recommended to create a new account that is used strictly for this integration and not over-provisioned), and open the LDAP port on your server to allow queries to be executed.

info

You can find additional information on managing Active Directory accounts on Microsoft's documentation, here. Additionally, information on LDAP configuration can be found, here.

Configuration in JupiterOne​

To install the Microsoft Active Directory integration in JupiterOne, navigate to the Integrations tab in JupiterOne and select Microsoft Active Directory. Click New Instance to begin configuring your integration.

  1. Create an Active Directory user capable of executing read queries. It is strongly recommended to create a new account that is used strictly for this integration and not over-provisioned.
  2. Obtain the following information:
    • Client Username - the username created in previous step, such as user@corp.example.com.
    • Client Password - the password for the Client Username.
    • LDAP URL - the URL of the LDAP server, such as ldaps://dc01.corp.example.com for LDAP over TLS or ldap://dc01.corp.example.com for unencrypted LDAP. Use the fully qualified domain name of the domain controller rather than an IP address, for the reasons described in LDAP over TLS (LDAPS).
    • Base DN - The base Distinguished Name of the subtree to be used in authentication and searches, such as dc=corp,dc=example,dc=com.

  • The Account Name used to identify the Microsoft Active Directory account in JupiterOne. Ingested entities will have this value stored in tag.AccountName when the AccountName toggle is enabled.

  • Description to assist in identifying the integration instance, if desired.

  • Polling Interval that you feel is sufficient for your monitoring needs. You may leave this as DISABLED and manually execute the integration.

  • Microsoft Active Directry information (username, password, LDAP URL, base DN) obtained in the previous section.

Click Create once all values are provided to finalize the integration.

LDAP over TLS (LDAPS)​

LDAP traffic is unencrypted over port 389. LDAPS wraps the same protocol in TLS over port 636, which keeps the bind credentials and directory queries from crossing the network in the clear. Microsoft's LDAPS certificate documentation describes how to install a certificate on the domain controller.

To use LDAPS, set the LDAP URL to ldaps://dc01.corp.example.com. The port defaults to 636 and does not need to be included.

Two requirements of the domain controller's certificate decide whether the connection succeeds, and both are checked by the client, which in this case is your integration collector:

  • The host in the LDAP URL must match the certificate. Microsoft requires the domain controller's Active Directory fully qualified domain name to appear either in the certificate's Subject common name or as a DNS entry in its Subject Alternative Name extension. Because certificates issued from the Domain Controller template identify the domain controller by name and not by address, an LDAP URL that uses an IP address fails this check even when the address is correct.
  • The collector must trust the certificate authority that issued it. Certificates issued by a public authority are trusted automatically. Certificates issued by your own enterprise or internal authority are not, and must be supplied to the integration.

Trusting an internal certificate authority​

If the domain controller's certificate was issued by an internal certificate authority, upload that authority's certificate in the Certificate Authority Certificate field, under TLS Configuration.

Provide the issuing authority's certificate together with every certificate above it in its chain, up to and including the root, concatenated into a single PEM file:

-----BEGIN CERTIFICATE-----
(the authority that issued the domain controller certificate)
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
(each authority above it, ending with the root)
-----END CERTIFICATE-----

The full chain matters because a domain controller usually presents only its own certificate and leaves the client to supply the rest. Uploading only part of the chain leaves the collector unable to verify the certificate, and the integration fails in the same way as uploading nothing at all.

To read the chain the domain controller presents, run the following from the host where your collector is installed:

openssl s_client -connect dc01.corp.example.com:636 -showcerts
caution

Only supply a certificate authority when the LDAP URL uses ldaps://. Uploading one alongside an ldap:// URL makes the integration attempt a TLS handshake against port 389, where the domain controller is not expecting one, and the connection fails.

Mutual TLS​

If your domain controller requires the client to present its own certificate, upload it in Client Certificate and its private key in Client Certificate Private Key, both under TLS Configuration. Most deployments do not require this.

Troubleshooting LDAPS connections​

Message in the job eventCause and resolution
The LDAPS server certificate could not be verifiedThe collector cannot build a trust chain to the certificate. Upload the issuing certificate authority and the certificates above it in Certificate Authority Certificate.
The LDAPS server certificate does not identify the host used in the LDAP URLThe LDAP URL uses a name or address that is absent from the certificate. Use the fully qualified domain name that appears in its Subject or Subject Alternative Name.
The server did not complete a TLS handshakeThe scheme and the port disagree. Use ldaps:// for port 636 and ldap:// for port 389, and remove any uploaded certificate authority when connecting over ldap://.
The server refused the connectionPort 636 is not reachable from the collector. Open it inbound on the domain controller.
The server requires the session to be protected before it accepts these credentialsThe domain controller declines simple binds over an unprotected connection. Connect over ldaps://.
The server rejected the credentialsActive Directory rejected the bind. The diagnostic that accompanies the message identifies the reason, where data 52e is an incorrect password, data 525 an unknown user, data 532 an expired password, data 533 a disabled account and data 775 a locked-out account.

Data Volume Configuration​

The Microsoft Active Directory integration provides configuration options to control the volume and scope of data ingested into JupiterOne:

FieldDescriptionDefaultOptions
Page SizeControls the number of records returned per page from the Microsoft Active Directory LDAP server. This setting should be set below the server's maximum response size limit to avoid errors. Lower values reduce memory usage but may increase query time.100Any positive integer below your server's max response size limit
User Extension AttributesSpecifies which user extension attributes should be included on the ad_user entity. This allows you to selectively ingest custom Active Directory attributes that are relevant to your organization.NoneComma-separated list of extension attribute names (e.g., 'extensionAttribute1,extensionAttribute2')

Next steps​

Now that your integration instance has been configured, it will begin running on the polling interval you provided, populating data within JupiterOne. Continue on to our Instance management guide to learn more about working with and editing integration instances.