# On-Premise Active Directory Agent

## Table of contents

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

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

The question should be specific, self-contained, and written in natural language.
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.