Configuration

Initial Configuration

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

Configuration File Location

The configuration file is located at:

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

Use the TUI (Terminal User Interface) for Configuration

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

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

   Stop-Service -Name "BalkanIDADAgent" -Force

2. Launch the configuration TUI:

   & "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

   • 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 (e.g., CN=ADAgent,CN=Users,DC=corp,DC=example,DC=com)

     • 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 / Multi-Forest Configuration

If you have multiple domains in your forest:

1. Enable Global Catalog:

   ad:
     use_global_catalog: true
     global_catalog_host: ""       # Empty = use main host
     global_catalog_port: 3268     # 3268 for GC, 3269 for GC with SSL
     forest_root_dn: "DC=corp,DC=example,DC=com"

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:

   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):

   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

The AD Agent supports multiple configuration options:

• Heartbeat mode

• API-only mode

I. Heartbeat Mode

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

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 Directory.

      

      
   3. Set up the Primary Application owner (mandatory) and the Description, if any. Set up Secondary Application Owner(s), if any.

      
   4. Leave all the other fields empty. If you see anything in the API URL field, ensure to clear it.

   5. Click on next to move onto Optional Configuration.

   6. Configure your fulfilment options as you see fit in this page. You can configure your multi-review settings here as well.

      
   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:

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

3. Navigate to Configuration Menu:

   • Select "Show Current Configuration" to view current settings

   • Or select "Edit Forest 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 UUID

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:

   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

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):

   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:

   server:
     http_port: 5000
     https_port: 5001
     heartbeat_mode: false         # Disable heartbeat mode

3. Authentication:

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

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:

   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 Directory.

   

   
3. Set up the Primary Application owner (mandatory) and the Description, if any. Set up Secondary Application Owner(s), if any.

   
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. 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 as you see fit in this page. You can configure your multi-review settings here as well.

   
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.

   

   

   
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.