Microsoft Active Directory

Community Platform

runZero integrates with Microsoft Active Directory (AD) via LDAP to allow you to sync and enrich your asset inventory, as well as gain visibility into domain users and groups. Adding your AD data to runZero makes it easier to find assets that are not part of your domain.

Getting started

To set up the Active Directory integration, you’ll need to:

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

Requirements

Before you can set up the LDAP integration, make sure you have credentials for an LDAP account.

Step 1: Add the LDAP credential to runZero

  1. Go to the Add credential page in runZero. Provide a name for the credentials, like LDAP.
  2. Choose LDAP Username & Password from the list of credential types.
  3. Provide the following information:
    • LDAP username - The username you want to use with the LDAP integration. The account used for this integration does not require any special permissions. The following username formats are accepted:
      • Distinguished Name (DN): CN=[username],CN=Users,DC=[domain],DC=[tld]
      • User Principle Name (UPN): [username]@[domain].[tld]
      • Domain\Username: [domain]\[username]
    • LDAP password - The password for the username to be used with the LDAP integration.
    • LDAP base DN - The base distinguished name for LDAP searches. This field requires distinguished name format: DC=[domain],DC=[tld]. Note that only entities underneath the specified base DN will be imported into runZero.
    • LDAP URL - The URL for your LDAP server. This field supports IP[:port] notation as well as hostname.domain.tld[:port]. This field requires that the URL entered begins 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 if you want to attempt authentication without a verified thumbprint. By default, runZero will attempt to connect with LDAPS but will fall back to LDAP+StartTLS then LDAP. LDAP without StartTLS will only work if this toggle is set to Yes.
    • LDAP thumbprints (optional) - A set of IP[:port]=SHA256:B64HASH or hostname.domain.tld=SHA256:B64HASH pairs to trust for authentication.
      • You will need to scan your LDAP server with runZero in order to obtain the TLS thumbprint. The TLS fingerprints service attribute report lists all previously seen fingerprints. The TLS thumbprints used for self-signed certificates will only work with LDAPS. If you want to use LDAP+StartTLS with a self-signed certificate, you will need to set the Insecure option to Yes.
      • If LDAP insecure is set to No and no thumbprints are provided:
        • With a self-signed certificate, the connection will fail because the certificate chain cannot be verified.
        • With a valid certificate from a public CA, the connection will work without thumbprints.
  4. If you want all other organizations to be able to use this credential, select the Make this a global credential option. Otherwise, you can configure access on a per-organization basis.
  5. Save the credential. You’re now ready to set up and activate the connection to bring in data from LDAP.

Step 2: Choose how to configure the Active Directory integration

The Active Directory integration can be configured as either a scan probe or a connector task. Scan probes gather data from integrations during scan tasks. Connector tasks run independently from either the cloud or one of your Explorers, only performing the integration sync.

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

After you add your Active Directory credential, you’ll need to set up a connector task or scan probe to sync your data.

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

After you add your LDAP credential, you’ll need to set up a connection to sync your data from LDAP. A connection requires you to set a schedule and choose a site. The schedule determines when the sync occurs, and the site determines where any new LDAP-only assets are created.

  1. Activate a connection to Active Directory. You can access all available third-party connections from the integrations page, your inventory, or the tasks page.
  2. Choose the credentials you added earlier. If you don’t see the credentials listed, make sure the credentials have access to the organization you are currently in.
  3. Enter a name for the task, like LDAP sync.
  4. Schedule the sync. A sync can be set to run on a recurring schedule or run once. The schedule will start on the date and time you have set.
  5. Under Task configuration, choose the site you want to add your assets to.
  6. If you want to exclude assets that have not been scanned by runZero from your integration import, switch the Exclude unknown assets toggle to Yes. By default, the integration will include assets that have not been scanned by runZero.
  7. Activate the connection when you are done. The sync will run on the defined schedule. You can always check the Scheduled tasks to see 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 based on any additional requirements.
  3. On the Probes and SNMP tab, choose which additional probes to include, set the LDAP toggle to Yes, and change any of the default options if needed.
  4. On the Credentials tab, set the LDAP toggle for the credential you wish to use to Yes.
  5. Click Initialize scan to save the scan task and have it run immediately or at the scheduled time.

Step 4: View Active Directory assets

After a successful sync, you can go to your inventory to view your LDAP assets. These assets will have an Active Directory icon listed in the Source column.

To filter by LDAP assets, consider running the following queries:

Click into each asset to see its individual attributes. runZero will show you the attributes returned by LDAP.

Community Platform

The LDAP integration provides details about users and groups in addition to enriching asset inventory data. Go to Inventory > Users or Inventory > Groups to view the data provided by LDAP.

Troubleshooting

If you are having trouble using this integration, the questions and answers below may assist in your troubleshooting.

Why is the Microsoft Active Directory integration unable to connect?

  1. Are you getting any data from the Microsoft Active Directory integration?
    • Make sure to query the inventory rather than look at the task details to review all the data available from this integration.
    • In some cases, integrations have a configuration set that limits the amount of data that comes into the runZero console.
  2. Some integrations require very specific actions that are easy to overlook. If a step is missed when setting up the intergration, it may not work correctly. Please review this documentation and follow the steps exactly.
  3. If the Microsoft Active Directory integration is unable to connect be sure to check the task log for errors. Some 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 you are running the integration task from an Explorer with access to the Microsoft Active Directory host.
Updated