Domain Auto-Discovery

Automatically locate Active Directory domains and domain controllers on the Bridge's network, eliminating the need to manually look up DC hostnames and ports before configuring a Bridge.

Requires role: Operator or higher (Admin required for deploying new Bridges) Related: Identity Bridge, Bridge Configuration, Attribute Sync Configuration, Entra ID Setup

Overview

Setting up a Bridge to sync Active Directory traditionally requires knowing the exact hostnames of domain controllers, which ports they accept connections on, and which domains are reachable from the Bridge's host. This information is readily available in your DNS infrastructure, but gathering it manually is error-prone and time-consuming — especially in environments with multiple domains or recently changed infrastructure.

Domain Auto-Discovery removes this friction. When a Bridge connects to GraphnAI for the first time with no domains configured, it automatically queries DNS to find Active Directory domain controllers on its local network, tests whether each controller is reachable, and reports the results back to the platform. You can then select discovered domains and configure them with a single click. The same discovery process can be re-run on demand at any time to detect changes to your domain controller topology.

For environments that sync to Entra ID (Azure AD), GraphnAI also detects on-premises domains automatically after your first Entra sync, and prompts you to deploy a Bridge for those domains — so hybrid environments are guided through the full setup without any cross-referencing of user properties.

Prerequisites

• Role: Operator or Admin
• Bridge deployed: At least one Bridge agent must be running and connected to the GraphnAI server. See the Bridge deployment documentation for installation steps.
• DNS access: The Bridge host must be able to resolve DNS names on your corporate network. If the Bridge runs in a container, the container's DNS resolver must point to a corporate DNS server, not a public resolver such as 8.8.8.8.
• For hybrid Entra detection: An Entra ID OIDC provider must be configured, and at least one initial Entra ID sync must have completed. See Entra ID Setup.

How Auto-Discovery Works

Discovery runs entirely on the Bridge host, using its DNS resolver and network position. The process has three stages:

1. Find DNS search domains. The Bridge reads the DNS suffix search list from its host configuration. On Linux and containers, this comes from /etc/resolv.conf (the search or domain directives). On Windows, it comes from the system DNS client settings. These suffixes identify which Active Directory forests the host is part of — for example, corp.local or dev.corp.local.

2. Look up domain controllers. For each DNS suffix, the Bridge performs a standard Active Directory DNS SRV lookup: _ldap._tcp.dc._msdcs.<suffix>. This is the same lookup that Windows clients use to locate domain controllers. The results include the hostname, port, priority, and weight of each controller. If the same controller hostname appears in multiple suffixes, it is counted only once.

3. Test connectivity. For each discovered controller, the Bridge attempts a TCP connection on port 636 (LDAPS, encrypted) and port 389 (LDAP, unencrypted), each with a 5-second timeout. Both tests run in parallel. The result for each controller indicates which protocols are available.

Discovery results are sent to the GraphnAI server and cached in memory. Results are not persisted to the database — they are ephemeral and reflect the network state at the time of the last run.

When Discovery Runs Automatically

Discovery runs automatically when a Bridge connects to the server and has no domains configured yet. This is the typical state for a newly deployed Bridge.

The sequence of events is:

1. You deploy the Bridge and it establishes its secure connection to the GraphnAI server.
2. The server sends the Bridge its current configuration. Because no domains have been added yet, the domain list is empty.
3. The Bridge detects the empty domain list and immediately starts discovery in the background.
4. Discovery results are sent back to the server over the same connection.
5. In the Bridge detail page, a banner appears indicating how many domains were discovered. Click View to open the discovery panel.

This happens automatically — you do not need to take any action to trigger the first discovery run.

Running Discovery Manually

To re-run discovery at any time — for example, after adding new domain controllers or decommissioning old ones:

1. Log in with an Operator or Admin account.
2. Navigate to Bridges in the sidebar and select the Bridge you want to scan.
3. In the domain list header, click Discover Domains.
4. The platform contacts the Bridge and runs a fresh discovery scan. This takes up to 30 seconds for most environments.
5. When the scan completes, the Domain Discovery panel opens automatically with the new results.

NOTE

The Bridge must be connected (online) for manual discovery to work. If the Bridge is offline, the button will return an error. Check the connection status indicator next to the Bridge name in the list.

Understanding Discovery Results

The Domain Discovery panel shows one card per discovered domain. Each card contains:

• Domain name — the Active Directory domain (e.g., corp.local)
• Reachable controllers — a table of domain controllers that responded to connectivity tests, shown with green row backgrounds
• Unreachable controllers — domain controllers found in DNS but that did not respond to either LDAP or LDAPS within 5 seconds, shown with red row backgrounds

For each controller, you can see:

Column	Description
Hostname	The fully qualified name of the domain controller
LDAPS	Indicates encrypted LDAP on port 636 is available (lock icon)
LDAP	Indicates unencrypted LDAP on port 389 is available
Priority	Lower numbers are preferred by Active Directory clients

Controllers that support LDAPS are pre-selected by default, since encrypted connections are strongly preferred for production environments. Controllers that support only LDAP are shown but not pre-selected.

Unreachable controllers are displayed in the panel for reference, but they cannot be selected for configuration. A yellow callout appears when unreachable controllers are present, suggesting that an additional Bridge deployment in a different network segment may be needed to reach those controllers.

Discovery errors — such as DNS suffixes that failed to resolve — appear in a collapsible warning section at the bottom of the panel. These are non-fatal: successfully discovered domains are still shown even if some suffixes failed.

Configuring Discovered Domains

After reviewing discovery results, select the domain controllers you want to use and choose how to provide credentials.

Selecting Domain Controllers

In each domain card, check the boxes next to the controllers you want to configure. Best practice is to select two or three controllers for redundancy. Controllers that support LDAPS are pre-selected; you can deselect any you do not want to include.

Credential Mode

The panel offers two credential modes:

Same credentials for all domains — enter one service account username and password in the panel. When you click Configure Selected, the platform uses these credentials for every selected domain. This is the fastest path when your service account has the same name and password across all domains.

Configure each domain separately — no credentials are entered in the panel. When you click Configure Selected, the domain configuration form opens pre-filled with the controller addresses, and you enter credentials individually for each domain.

Applying the Configuration

Click Configure Selected to proceed.

• If you chose same credentials and selected multiple domains, the platform tests each domain's connectivity using the credentials you provided. Domains that pass are saved automatically. Domains that fail show an inline error — check the credentials and try again for those domains individually.
• If you chose same credentials and selected a single domain, the domain configuration form opens pre-filled for final review before saving.
• If you chose per-domain credentials, the domain configuration form opens for the first selected domain, pre-filled with:
  • Domain name
  • Controller addresses (formatted as host:636 for LDAPS or host:389 for LDAP)
  • TLS setting (enabled if LDAPS was selected)

Complete and save that form, then repeat for any additional domains.

Entra Hybrid Detection

If your organization uses Entra ID with on-premises Active Directory synchronized via Entra Connect, GraphnAI can identify which on-premises domains your users belong to — without any manual cross-referencing.

During the initial Entra ID sync, GraphnAI collects the onPremisesDomainName property from each synced user. After the sync completes, the platform checks whether any users have on-premises domain names recorded and, if so, surfaces them for action.

The Hybrid Domain Prompt

After your first Entra ID sync completes (the progress indicator transitions from syncing to complete), the On-Premises Domains Detected modal appears automatically if hybrid users are found.

The modal lists each discovered on-premises domain along with the number of users synced from that domain — for example:

corp.local — 142 users dev.corp.local — 23 users

This information tells you which domains have a meaningful number of users in your Entra ID tenant, helping you prioritize which domains to configure first.

From the modal you have two options:

• Deploy Bridge — navigates directly to the Bridge detail page to add a Bridge for your on-premises environment. Once the Bridge connects and discovery runs, the on-premises domain names will match the discovered domains, making configuration straightforward.
• Skip for now — dismisses the modal. The on-premises domain information remains available if you want to retrieve it later.

NOTE

The hybrid domain prompt only appears after the initial Entra sync — not after subsequent delta syncs. If you dismiss the prompt and want to retrieve the on-premises domain list later, navigate to Bridges in the sidebar and deploy a Bridge manually, then use Discover Domains once the Bridge connects.

Troubleshooting

No domains discovered — the panel shows an empty state

The Bridge found no Active Directory domain controllers on its network. This typically means one of the following:

The Bridge host has no DNS search suffixes configured. The most common cause in containerized deployments. By default, Docker containers resolve DNS through the host, but they may not inherit the host's search domain list.

To fix this, pass the --dns-search option to Docker:

docker run ... --dns-search corp.local --dns-search dev.corp.local graphnai-bridge

Or add a dns_search entry to your docker-compose.yml:

services:
  bridge:
    image: ghcr.io/graphnai-security/bridge:latest
    dns_search:
      - corp.local
      - dev.corp.local

The Bridge host is not domain-joined and has no corporate DNS. If the Bridge is running on a host that points to a public DNS server (such as 8.8.8.8), SRV lookups for _ldap._tcp.dc._msdcs.corp.local will fail because public DNS does not have these records.

To fix this, configure the Bridge host or container to use your internal DNS server:

docker run ... --dns 10.1.1.10 graphnai-bridge

Replace 10.1.1.10 with your corporate DNS server's IP address.

There are no _ldap._tcp.dc._msdcs.* SRV records in your DNS. This is rare in standard Active Directory environments — AD registers these records automatically. If your environment uses split-brain DNS or a non-standard configuration, verify the SRV records exist:

nslookup -type=SRV _ldap._tcp.dc._msdcs.corp.local

Run this command from the Bridge host. If it returns no results, contact your DNS or Active Directory administrator.

Discovery errors appear in the panel

Non-fatal errors are shown in the collapsible warning section. Common error messages:

Error	Cause	Resolution
SRV lookup corp.local: no such host	DNS cannot resolve the SRV record for this suffix	Verify the suffix exists in DNS; check --dns-search config
no DNS suffixes found (tried /etc/resolv.conf and PowerShell)	The Bridge host has no DNS search list configured	Add dns_search entries to your container configuration
SRV lookup dev.corp.local: connection refused	DNS server is unreachable	Verify the Bridge host can reach the DNS server IP

Errors for one suffix do not prevent discovery of other suffixes.

Some domain controllers show as unreachable

A controller appearing as unreachable means the Bridge could not establish a TCP connection to port 636 or 389 within 5 seconds. Possible causes:

• Firewall rules block LDAP/LDAPS from the Bridge host's network segment. Check that ports 389 and 636 are open between the Bridge host and the domain controller IPs.
• The controller is offline or under maintenance. Verify the controller is operational from another host in the same network.
• The Bridge is in a DMZ or isolated network segment that does not have a route to the domain controller. In this case, deploy an additional Bridge closer to the domain controller.

Unreachable controllers are shown in the panel for visibility but cannot be selected for configuration.

The Hybrid Domain Prompt did not appear after Entra sync

The prompt only appears after the initial Entra ID sync (when identity data first populates). If the prompt was missed or dismissed:

• Navigate to Bridges in the sidebar and deploy a Bridge manually, then use Discover Domains once the Bridge connects

The prompt also does not appear for cloud-only Entra ID tenants (where onPremisesSyncEnabled is false at the tenant level), or if no users in the tenant have an onPremisesDomainName value.

"Bridge not connected" error when clicking Discover Domains

Manual discovery requires the Bridge to be online. Check:

1. The Bridge process is running on the host machine.
2. The Bridge has network connectivity to the GraphnAI server on the bridge listener port (default: 8443).
3. The connection status indicator next to the Bridge name in Bridges in the sidebar shows as connected (green).

If the Bridge is shown as disconnected, restart the Bridge agent and wait for it to reconnect before retrying discovery.

Discovery consistently times out

Discovery can take up to 60 seconds in large environments with many domain controllers. If the timeout is consistently hit:

• Limit the scan to specific domains by using the discovery panel options
• Check whether the Bridge host has network connectivity issues causing the 5-second DC connection attempts to all time out

If discovery consistently times out even for small environments, check the Bridge agent logs for error details.