Microsoft Active Directory

View as Markdown

Community Platform

runZero integrates with Microsoft Active Directory (AD) over LDAP to sync and enrich your asset inventory and to show you domain users and groups. With your AD data in runZero, assets that aren’t part of your domain are easier to find.

Getting started

To set up the Active Directory integration:

  1. Add the AD credential in runZero.
  2. Choose whether to run the integration as a scan probe or connector task.
  3. Activate the Active Directory integration to sync your data with runZero.

Requirements

You need credentials for an LDAP account.

Step 1: Add the LDAP credential to runZero

  1. Go to the Add credential page in runZero and name the credential, like LDAP.
  2. Choose LDAP Username & Password from the list of credential types.
  3. Provide the following information:
    • LDAP username: The username the integration uses to sign in. The account doesn’t need any special permissions. runZero accepts these username formats:
      • Distinguished Name (DN): CN=[username],CN=Users,DC=[domain],DC=[tld]
      • User Principal Name (UPN): [username]@[domain].[tld]
      • Domain\Username: [domain]\[username]
    • LDAP password: The password for that username.
    • LDAP base DN: The base distinguished name for LDAP searches, in distinguished name format: DC=[domain],DC=[tld]. runZero imports only entities underneath this base DN.
    • LDAP URL: The URL for your LDAP server, as IP[:port] or hostname.domain.tld[:port]. It must begin with ldap:// (for insecure LDAP connections) or ldaps:// (for secure LDAP connections). For example: ldaps://ad.example.com:636
    • LDAP insecure: Set this to Yes to attempt authentication without a verified thumbprint. By default, runZero tries LDAPS first, then falls back to LDAP+StartTLS, then LDAP. LDAP without StartTLS only works when this toggle is Yes.
    • LDAP thumbprints (optional): A set of IP[:port]=SHA256:B64HASH or hostname.domain.tld=SHA256:B64HASH pairs to trust for authentication.
      • To get the TLS thumbprint, scan your LDAP server with runZero. The TLS fingerprints service attribute report lists every fingerprint seen so far. Thumbprints for self-signed certificates only work with LDAPS. To use LDAP+StartTLS with a self-signed certificate, set the Insecure option to Yes.
      • If LDAP insecure is No and you provide no thumbprints:
        • With a self-signed certificate, the connection fails because the certificate chain can’t be verified.
        • With a valid certificate from a public CA, the connection works without thumbprints.
  4. To let all other organizations use this credential, select the Make this a global credential option. Otherwise, you can configure access per organization.
  5. Save the credential.

Step 2: Choose how to configure the Active Directory integration

You can run the Active Directory integration as either a scan probe or a connector task. A scan probe gathers integration data during a scan task. A connector task runs on its own, from the cloud or from one of your Explorers, and performs only the integration sync.

Step 3: Set up and activate the Active Directory integration to sync data

With your Active Directory credential saved, set up a connector task or a scan probe to sync your data.

Step 3a: Configure the Active Directory integration as a connector task

A connection needs a schedule and a site. The schedule sets when the sync runs, and the site is where runZero creates any new LDAP-only assets.

  1. Activate a connection to Active Directory. You can reach every third-party connection from the integrations page, your inventory, or the tasks page.
  2. Choose the credential you added earlier. If it isn’t listed, make sure it has access to the organization you’re currently in.
  3. Enter a name for the task, like LDAP sync.
  4. Schedule the sync to run once or on a recurring schedule. The schedule starts on the date and time you set.
  5. Under Task configuration, choose the site to add your assets to.
  6. To leave out assets that runZero has not scanned, switch the Exclude unknown assets toggle to Yes. By default, the integration includes them.
  7. Activate the connection. The sync runs on the schedule you defined, and the Scheduled tasks page shows when the next sync will occur.

Step 3b: Configure the Active Directory integration as a scan probe

  1. Create a new scan task or select a future or recurring scan task from your Tasks page.
  2. Add or update the scan parameters to fit any additional requirements.
  3. On the Probes and SNMP tab, choose any additional probes to include, set the LDAP toggle to Yes, and change any default options as needed.
  4. On the Credentials tab, set the LDAP toggle to Yes for the credential you want to use.
  5. Click Initialize scan to save the scan task. It runs immediately or at the scheduled time.

Step 4: View Active Directory assets

After a successful sync, go to your inventory to view your LDAP assets. They show an Active Directory icon in the Source column.

To filter for LDAP assets, try these queries:

Click into an asset to see the attributes LDAP returned. To write your own queries, start with the search query syntax.

Community Platform

The LDAP integration also imports details about users and groups. Go to Inventory > Users or Inventory > Groups to see them.

Troubleshooting

If the integration isn’t working, start with these checks.

Why is the Microsoft Active Directory integration unable to connect?

  1. Check whether the Microsoft Active Directory integration is returning any data.
    • Query the inventory rather than the task details to review all the data available from this integration.
    • In some cases, an integration’s configuration limits how much data reaches the runZero console.
  2. Some integrations require specific actions that are easy to overlook. If you miss a step during setup, the integration may not work correctly. Review this page and follow the steps exactly.
  3. If the Microsoft Active Directory integration can’t connect, check the task log for errors. Common errors include:
    • 500: server error, unable to connect to the endpoint
    • 404: hitting an unknown endpoint on the server
    • 403: not authorized, likely a credential issue
  4. Verify that the integration task runs from an Explorer with access to the Microsoft Active Directory host.
Updated