> 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-integration/on-premise-active-directory-agent/configuration.md).

# Configuration

### Initial Configuration <a href="#initial-configuration" id="initial-configuration"></a>

After installation, you need to configure the agent before it can connect to your Active Directory and BalkanID.

#### Configuration File Location <a href="#configuration-file-location" id="configuration-file-location"></a>

The configuration file is located at:

```
C:\ProgramData\BalkanID\ad-agent\config.yaml
```

#### Use the TUI (Terminal User Interface) for Configuration <a href="#using-the-tui-terminal-user-interface-for-configuration" id="using-the-tui-terminal-user-interface-for-configuration"></a>

The easiest way to configure the agent is using the built-in TUI:

1. **Stop the service** (if it's running):

   ```powershell
   Stop-Service -Name "BalkanIDADAgent" -Force
   ```
2. **Launch the configuration TUI**:

   ```powershell
   & "C:\Program Files\BalkanID\ad-agent\BalkanID AD Agent.exe" --configure
   ```

   This opens the configuration interface without starting the HTTP server.
3. **Navigate the TUI**:
   * Use **Arrow Keys** to navigate menus
   * Press **Enter** to select options
   * Press **Tab** to move between form fields
   * Press **Esc** or **Q** to go back/quit
4. **Configure Forest Domain** (First Time Setup):
   * The TUI will prompt you to configure your forest domain
     * Under Configuration > Manager Forest Configuration > Add new forest
   * Enter the following information:
     * **Forest Domain**: e.g., `corp.example.com`
     * **LDAP Host**: Domain controller hostname or IP (e.g., `corp.example.com`)
     * **LDAP Port**:
       * `636` for LDAPS (TLS/SSL) - **Recommended**
       * `389` for LDAP (non-encrypted)
     * **Base DN**: e.g., `DC=corp,DC=example,DC=com`
     * **Bind Username**: User account DN or Logon Name (e.g., `CN=ADAgent,CN=Users,DC=corp,DC=example,DC=com` or `CORP\ADAgent`)
     * **Bind Password**: Service account password
     * **Use TLS**: `true` for LDAPS, `false` for LDAP
5. **Save Configuration**:
   * After filling the form, select "Save" or press Enter
   * The configuration will be written to `config.yaml`
6. **Test LDAP Connection**:
   * From the Configuration Menu, select "Test LDAP Connection"
   * Verify the connection succeeds before proceeding

#### Multi-Domain Configuration <a href="#multi-domain--multi-forest-configuration" id="multi-domain--multi-forest-configuration"></a>

If you have multiple domains in your forest:

1. **Enable Global Configuration** for the forest under forest configuration
2. **Configure Child Domains**:

   **Using the TUI (recommended):**

   * Navigate to **"Manage Child Domains"**
   * Choose **"🔍 Auto-Discover Child Domains"** to automatically detect domains in the forest and pre-populate them in the config
   * Review the discovered domains and save
   * If you need additional domains or want to override details, you can also add them manually:
     * In the same screen, choose **"➕ Add New Child Domain"**
     * Enter domain details:
       * Domain Name: e.g., `na.corp.example.com`
       * Base DN: e.g., `DC=na,DC=corp,DC=example,DC=com`
       * Host: (optional, leave empty to use main host)
       * Port: (optional, 0 to use main port)

   **Or manually in `config.yaml`:**

   ```yaml
   ad:
     domains:
       - name: "na.corp.example.com"
         base_dn: "DC=na,DC=corp,DC=example,DC=com"
         host: ""
         port: 0
       - name: "eu.corp.example.com"
         base_dn: "DC=eu,DC=corp,DC=example,DC=com"
         host: ""
         port: 0
   ```
3. **UPN Suffixes** (Optional):

   ```yaml
   ad:
     upn_suffixes:
       - "@corp.example.com"
       - "@na.corp.example.com"
       - "@eu.corp.example.com"
   ```

   If not specified, UPN suffixes are automatically derived from configured domains.

***

### Configure extraction mode <a href="#configuration-modes" id="configuration-modes"></a>

The AD Agent supports multiple configuration options:

* [Heartbeat mode](#initial-configuration)
* [API-only mode (Recommended)](#general-configuration)

#### I. Heartbeat Mode <a href="#heartbeat-mode" id="heartbeat-mode"></a>

**Heartbeat Mode** enables automatic synchronization with the BalkanID platform. When enabled, the agent will:

* **Extract AD data** every 2 hours and upload to BalkanID
* **Fetch and process requests** from BalkanID every 10 minutes
* Automatically handle identity lifecycle operations:
  * Create identities
  * Update identities
  * Delete identities
  * Suspend identities
  * Reactivate identities
* Process access requests and manage group memberships

<div data-with-frame="true"><figure><img src="/files/b9SlrWgAd6ueqKHz3xdi" alt=""><figcaption><p>AD Agent Heartbeat Mode</p></figcaption></figure></div>

**Setting Up Heartbeat Mode**

1. **Setup on BalkanID application:**
   1. Login to the BalkanID application as an administrator in your tenant.
   2. Head to *Integrations* > **Add Integration**, select Active Director&#x79;**.**

      <figure><img src="/files/DoEMPtEJTi5EsgIKXdoG" alt=""><figcaption></figcaption></figure>

      <figure><img src="/files/hrGO33v025SHkgFCAuuE" alt=""><figcaption></figcaption></figure>
   3. Set up the *Primary Application owner (mandatory)* and the *Description*, if any. Set up Secondary Application Owner(s), if any.&#x20;

      <figure><img src="/files/DHinjJZ7H8LoHQyTq6xX" alt="" width="563"><figcaption></figcaption></figure>
   4. Leave all the other fields empty. If you see anything in the API URL field, ensure to clear it.&#x20;
   5. Click on next to move onto *Optional Configuration.*
   6. Configure your [fulfilment options](https://docs.balkan.id/getting-started/setting-up-your-tenant/application-integrations/fulfillment-options) as you see fit in this page. You can configure your [multi-review settings](https://docs.balkan.id/user-access-reviews/access-review-management/configuring-access-reviews-and-campaigns/configuring-integration-specific-multi-level-review-settings) here as well.

      <figure><img src="https://docs.balkan.id/~gitbook/image?url=https%3A%2F%2F2975852473-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FbVGYwk8aSk5yI1GDPEW9%252Fuploads%252Fa8ygNG6MgLiUMb7SIgFn%252Fimage.png%3Falt%3Dmedia%26token%3D419c91e2-7ac7-4ab3-82a9-dffc45bb5ed2&#x26;width=768&#x26;dpr=4&#x26;quality=100&#x26;sign=2bafde31&#x26;sv=2" alt="" width="563"><figcaption></figcaption></figure>
   7. Once done, click on the "*Save Changes*" button.
   8. Once all this is done, please reach out to the support team to give you the integration ID, tenant ID and the tenant API key and secret. This will be required while configuring the AD agent.
2. **Launch the TUI**:

   ```powershell
   & "C:\Program Files\BalkanID\ad-agent\BalkanID AD Agent.exe" --configure
   ```
3. **Navigate to Configuration Menu**:
   * Select "Edit Agent Configuration" to modify settings
4. **Configure Heartbeat Mode**:

   You need to configure the following in the `auth` section (contact the support team):

   * **Tenant ID**: Your BalkanID tenant identifier (e.g., `01xxx`)
   * **Tenant Key**: Your BalkanID tenant key
   * **Tenant Secret**: Your BalkanID tenant secret
   * **Integration ID**: Your BalkanID integration ID
5. **Enable Heartbeat Mode**:

   In the `server` section, set:

   * **Heartbeat Mode**: `true`
6. **Manual Configuration** (Alternative):

   If you prefer to edit the config file directly, open:

   ```
   C:\ProgramData\BalkanID\ad-agent\config.yaml
   ```

   And ensure it contains:

   ```yaml
   server:
     http_port: 5000
     https_port: 5001
     heartbeat_mode: true  # Enable heartbeat mode

   auth:
     tenant_id: "01xxx"                    # Your tenant ID
     tenant_key: "your-tenant-key"          # Your tenant key
     tenant_secret: "your-tenant-secret"   # Your tenant secret
     integration_id: "integration-uuid"   # Your integration ID
   ```
7. **Verify Network Access**:

   Ensure the machine can reach:

   * `api-integrators.app.balkan.id` (for GraphQL API)
   * `app.balkan.id` (for REST API)

#### II. API-only mode <a href="#general-configuration" id="general-configuration"></a>

For **non-heartbeat mode** (API-only mode), configure the agent to expose a REST API for manual AD operations.

**Basic Configuration**

1. **AD Connection Settings (please edit the `corp` field based on your configuration)**:

   ```yaml
   ad:
     host: "corp.example.com"
     port: 636                    # 636 for LDAPS, 389 for LDAP
     base_dn: "DC=corp,DC=example,DC=com"
     username: "CN=ADAgent,CN=Users,DC=corp,DC=example,DC=com"
     password: "your-service-account-password"
     use_tls: true                 # true for LDAPS
   ```
2. **Server Settings**:

   ```yaml
   server:
     http_port: 5000
     https_port: 5001
     heartbeat_mode: false         # Disable heartbeat mode
   ```
3. **Authentication**:

   ```yaml
   auth:
     api_key: "your-api-key"       # Generate via TUI or manually
   ```

<div data-with-frame="true"><figure><img src="/files/my6k6lBdlLQLa7Zqn69I" alt=""><figcaption><p>AD Agent API Mode</p></figcaption></figure></div>

**HTTPS/TLS Configuration**

To enable HTTPS for the REST API:

1. **Generate Self-Signed Certificate** (via TUI):
   * Navigate to "Generate Self-Signed TLS Certificate"
   * The TUI will create certificates and update the config automatically
2. **Or Use Your Own Certificates**:

   ```yaml
   server:
     tls_cert: "C:\ProgramData\BalkanID\ad-agent\cert.pem"
     tls_key: "C:\ProgramData\BalkanID\ad-agent\key.pem"
   ```

**Setup on BalkanID application:**

1. Login to the BalkanID application as an administrator in your tenant.
2. Head to *Integrations* > **Add Integration**, select Active Director&#x79;**.**

   <figure><img src="/files/er6qk2MTvUrlxa4g40Dt" alt=""><figcaption></figcaption></figure>

   <figure><img src="/files/1d5zrjg3nqC0YOhKAolY" alt=""><figcaption></figcaption></figure>
3. Set up the *Primary Application owner (mandatory)* and the *Description*, if any. Set up Secondary Application Owner(s), if any.&#x20;

   <figure><img src="/files/tgzoqOGpVTCuL6Vbt8Zz" alt="" width="563"><figcaption></figcaption></figure>
4. Provide the required configuration fields:
   * **API URL**\
     The URL of the web server or agent running on the target machine. This must be an externally accessible endpoint with an outbound IP address that is publicly reachable or accessible via the BalkanID proxy.
   * **Domain**\
     The Active Directory forest domain.\
     \&#xNAN;*Example:* `corp.example.com`
   * **API Key**\
     When the integration is configured for the first time, BalkanID generates an API key automatically. The API key can be regenerated later using the **Regenerate API Key** option in the configuration settings.
5. Click on next to move onto *Optional Configuration.*
6. Configure your [fulfilment options](https://docs.balkan.id/getting-started/setting-up-your-tenant/application-integrations/fulfillment-options) as you see fit in this page. You can configure your [multi-review settings](https://docs.balkan.id/user-access-reviews/access-review-management/configuring-access-reviews-and-campaigns/configuring-integration-specific-multi-level-review-settings) here as well.

   <figure><img src="https://docs.balkan.id/~gitbook/image?url=https%3A%2F%2F2975852473-files.gitbook.io%2F%7E%2Ffiles%2Fv0%2Fb%2Fgitbook-x-prod.appspot.com%2Fo%2Fspaces%252FbVGYwk8aSk5yI1GDPEW9%252Fuploads%252Fa8ygNG6MgLiUMb7SIgFn%252Fimage.png%3Falt%3Dmedia%26token%3D419c91e2-7ac7-4ab3-82a9-dffc45bb5ed2&#x26;width=768&#x26;dpr=4&#x26;quality=100&#x26;sign=2bafde31&#x26;sv=2" alt="" width="563"><figcaption></figcaption></figure>
7. Once done, click on the "*Save Changes*" button. Your integration will process and extract your data in a few minutes. You can track the status of your integration from the snackbar we provide as shown in the below images.

   <figure><img src="/files/qjAumXLZBZbgZl2ATYcB" alt="" width="375"><figcaption></figcaption></figure>
8. You can view your application entitlement data once the status of application integration is "*Connected*" and you see the "*Data Available*" message in the table.

### Integration Scopes <a href="#h_01j5r9r7pmaq7g0ck77yz4hxhm" id="h_01j5r9r7pmaq7g0ck77yz4hxhm"></a>

Right click on the Domain Controller, and go to Properties > Security > Advanced tab and Click add, and choose the Account as the Principal, that is configured for the AD Agent

| Read Only (Access Review) Scopes under Security Tab Type: Allow, Applies to: This object and all descendant objects | Lifecycle Management Scopes under Delegate Control |
| ------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| List Contents (Under Permissions Section)                                                                           | Create/Delete all child objects                    |
| Read all properties (Under Permissions Section)                                                                     | Modify permissions                                 |
| Read permissions (Under Permissions Section)                                                                        | Create/Delete InetOrgPerson objects                |
| Real all properties (Under Properties Section)                                                                      | Create/Delete Group objects                        |
|                                                                                                                     | Create/Delete Organization Unit Objects            |
|                                                                                                                     | Create/Delete User Objects                         |
|                                                                                                                     | Under Properties, Write name                       |
|                                                                                                                     | Under Properties, Write Name                       |
|                                                                                                                     | Under Properties, Write Description                |
|                                                                                                                     | Under Properties, Write msDS-PrincipalName         |

<br>


---

# 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.balkan.id/getting-started/setting-up-your-tenant/application-integrations/direct-application-integration/on-premise-active-directory-agent/configuration.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.