> For the complete documentation index, see [llms.txt](https://docs.elimity.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.elimity.com/import-agents-active-directory/step-by-step-deployment-guide.md).

# Step-by-step deployment guide

{% hint style="danger" %}
We highly recommend using [our LDAP gateway](/gateways-ldap/step-by-step-deployment-guide.md) instead of this import agent.
{% endhint %}

## 1. Creating a 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. Refer to the following attachment for a starting point:

{% file src="/files/zk7ODnVfDtWbQRiJUIPT" %}

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:

<table data-full-width="true"><thead><tr><th>Property</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td><code>adDomain</code></td><td><code>string</code></td><td>Domain for NTLM authentication; omit to use simple bind</td></tr><tr><td><code>adPassword</code></td><td><code>string</code></td><td>Password for NTLM / simple bind authentication</td></tr><tr><td><code>adSearchRequests</code></td><td><code>list[object]</code></td><td>LDAP search requests that determine which entries the agent should import</td></tr><tr><td><code>adSearchRequests[].baseDn</code></td><td><code>string</code></td><td>DN from which the LDAP subtree search should start</td></tr><tr><td><code>adSearchRequests[].filter</code></td><td><code>string</code></td><td>LDAP filter to limit which entries the agent should import</td></tr><tr><td><code>adUrl</code></td><td><code>string</code></td><td>LDAP URL of your Active Directory server, e.g. <code>ldap://my-host:389</code> or <code>ldaps://my-secure-host:636</code></td></tr><tr><td><code>adUsername</code></td><td><code>string</code></td><td>Username for NTLM / simple bind authentication</td></tr><tr><td><code>cronPattern</code></td><td><code>string</code></td><td>Optional CRON pattern describing when the import agent should run (refer to <a href="https://crontab.guru">https://crontab.guru</a> for example patterns); omit if you just want to run the agent once</td></tr><tr><td><code>insightsSourceId</code></td><td><code>number</code></td><td>Source identifier you noted down in step 1</td></tr><tr><td><code>insightsSourceToken</code></td><td><code>string</code></td><td>Source token you noted down in step 1</td></tr><tr><td><code>insightsUrl</code></td><td><code>string</code></td><td>URL of your Elimity Insights server</td></tr></tbody></table>

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 a CaaS solution like Google Cloud Run or Azure Container Apps. If that's not an option, you can also manually deploy the image on e.g. Windows Server. Refer to [our documentation about gateways and import agents](/technical-guides/gateways-and-import-agents.md) 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`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.elimity.com/import-agents-active-directory/step-by-step-deployment-guide.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.