Active Directory

The Active Directory import agent for Elimity Insights queries your on-premise Active Directory servers and uploads the results to your Elimity Insights server. You configure the Active Directory connections, the queries to execute and the connection with your Elimity Insights server. The import agent will then connect to your Active Directory servers, execute the configured queries, transform the results to a format compatible with Elimity Insights and send the transformed data to your Elimity Insights server.

Installation

The import agent is available as a Docker image for Linux and Windows. Refer to the dedicated knowledge base article for all details about working with agents and gateways. Visit https://console.cloud.google.com/artifacts/docker/elimity-general/europe-west1/docker/ad-import-agent to get a list of available image tags for this specific agent.

Step-by-step deployment guide

The following sections will explain the different steps you'll need to take to deploy the Active Directory agent for Elimity Insights.

1. Creating an Active Directory source in Elimity Insights

Firstly create a new Active Directory source in Elimity Insights, but do not enable automatic imports. Instead, generate API credentials for this source and note down the resulting identifier and token.

2. Configuring the agent

To configure your import agent, mount a JSON configuration file at `/app/config/config.json` with the properties listed below. You can find an example in the attachments at the bottom of this page.

This example configuration will simply import all users, groups, computers and foreign security principals from an Active Directory server. Edit the following properties in this file to configure the import agent to your needs:

• `adDomain`: domain for NTLM authentication with the Active Directory server, omit if not applicable
• `adPassword`: password for authentication with the Active Directory server
• `adSearchRequests`: list of LDAP search requests that determine which entries the agent should import
  • `baseDn`: specifies the base of the subtree in which the search is to be constrained
  • `filter`: specifies criteria to use to identify which entries within the scope should be returned
• `adUrl`: URL of your Active Directory server, e.g. `ldap://my-host:389` or `ldaps://my-secure-host:636`
• `adUsername`: username for authentication with the Active Directory server
• `cronPattern`: optional CRON pattern describing when the import agent should run (refer to https://crontab.guru for example patterns); omit if you just want to run the agent once
• `insightsSourceId`: source identifier you noted down in step 1
• `insightsSourceToken`: source token you noted down in step 1
• `insightsUrl`: URL of your Elimity Insights server

Additionally, you can mount a PEM-encoded SSL certificate at `/app/config/cert.pem` to override the import agent's trust store. This is especially useful if you want to set up LDAPS connections to internal hosts.

3. Deploying the agent

Having configured the agent and having created a source in Elimity Insights, you can now deploy the agent to regularly import data from your Active Directory server and upload it to Elimity Insights. Since we distribute the agent as a Docker image, our recommendation for deployment is to use your cloud provider’s dedicated job execution platform (e.g. Google Cloud Run, Azure Container Apps, …). If that's not an option, you can also manually deploy the image on e.g. Windows Server. Refer to the dedicated knowledge base article about installing import agents for additional details.

4. Following up on the import

The import agent outputs logs to indicate its progress, for a manual Windows Server deployment you can check these with `docker-compose logs ad-import-agent`.