> For the complete documentation index, see [llms.txt](https://docs.balkan.id/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.balkan.id/getting-started/setting-up-your-tenant/application-integrations/direct-application-integrations/on-premise-active-directory-agent.md).

# On-Premise Active Directory Agent

Integrate On-Prem AD agent

## Table of contents

1. [Overview](#overview-balkanid-active-directory-agent)
2. [Installation](https://docs.balkan.id/getting-started/setting-up-your-tenant/application-integrations/direct-application-integrations/on-premise-active-directory-agent/install-the-agent.md)
3. [Configuration](https://docs.balkan.id/getting-started/setting-up-your-tenant/application-integrations/direct-application-integrations/on-premise-active-directory-agent/configuration.md)
   * [Heartbeat Mode](https://docs.balkan.id/getting-started/setting-up-your-tenant/application-integrations/direct-application-integrations/on-premise-active-directory-agent.md)
   * [API-only mode](https://docs.balkan.id/getting-started/setting-up-your-tenant/application-integrations/direct-application-integrations/on-premise-active-directory-agent/configuration.md#general-configuration)
4. [Two ways to running the agent](https://docs.balkan.id/getting-started/setting-up-your-tenant/application-integrations/direct-application-integrations/on-premise-active-directory-agent/running-the-agent.md)
   * [Using TUI (Terminal User Interface)](https://docs.balkan.id/getting-started/setting-up-your-tenant/application-integrations/direct-application-integrations/on-premise-active-directory-agent/running-the-agent.md#using-tui-terminal-user-interface)
   * [Running as Windows Service (Headless)](https://docs.balkan.id/getting-started/setting-up-your-tenant/application-integrations/direct-application-integrations/on-premise-active-directory-agent/running-the-agent.md#running-as-windows-service-headless)
5. [Service management and troubleshooting](https://docs.balkan.id/getting-started/setting-up-your-tenant/application-integrations/direct-application-integrations/on-premise-active-directory-agent/service-management-and-troubleshooting.md)

***

### Overview: BalkanID Active Directory Agent

The BalkanID Active Directory (AD) Agent is a **high-performance, cross-platform service** designed to securely extract and manage identity data from **on-premises Active Directory environments**. Written in Go, the agent runs within the customer’s network and acts as a controlled bridge between on-prem AD and the BalkanID identity governance platform.

The agent exposes a **RESTful API** that enables BalkanID to query and manage Active Directory objects such as users, groups, group memberships, and related metadata—without requiring direct inbound access to the customer’s directory infrastructure.

***

### How the AD Agent Works

The AD Agent is deployed on a machine that has network access to the target Active Directory forest. Once configured, it communicates with BalkanID using one of two supported operating modes:

* **API-Only Mode (Recommended)**\
  In API-only mode, the agent runs as a standalone REST service. BalkanID can directly invoke the agent’s APIs to retrieve or manage Active Directory data. This mode is typically used in environments where inbound access is permitted or when the agent is leveraged for custom workflows.
* **Heartbeat Mode**\
  In this mode, the agent establishes an outbound connection to BalkanID at regular intervals (“heartbeats”). During each heartbeat, the agent:

  * Authenticates using the configured API key
  * Sends extracted data to BalkanID every 2 hours

  This mode is ideal for environments with strict firewall rules, as it requires **no inbound connectivity** to the on-prem network.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.balkan.id/getting-started/setting-up-your-tenant/application-integrations/direct-application-integrations/on-premise-active-directory-agent.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
