Bridge Configuration & Multi-Domain Management

Configure Active Directory domains, sync schedules, and certificates for Identity Bridge agents directly from the GraphnAI SaaS interface — no config files required on the on-premises VM.

Requires role: Admin (write), Operator (read) Related: Identity Bridge, Domain Auto-Discovery, Hardware Sizing, Attribute Sync Configuration

Overview

The Identity Bridge agent runs on your on-premises network and collects identity data from Active Directory. All configuration — domain credentials, domain controller addresses, sync schedules, and certificate trust — is managed centrally from the GraphnAI platform. You never need to edit files or environment variables on the bridge VM to change settings.

Key capabilities of the bridge configuration system:

• Multi-domain support: A single bridge can query multiple Active Directory domains or forests simultaneously. Each domain has its own credentials, controllers, and TLS settings, and can be added, edited, or removed independently.
• Zero-touch credentials: Passwords entered in the platform are encrypted immediately and never written to disk on the bridge VM. The bridge holds credentials in memory only, and re-fetches them automatically if it restarts.
• Live configuration updates: Changes you save in the platform take effect on the running bridge without a process restart. If the bridge is temporarily offline when you save, it receives the updated configuration the next time it reconnects.
• Pre-save connection testing: Use the Test Connection feature to verify that domain credentials and controller addresses are correct before saving the configuration.

Prerequisites

• Role: Admin role is required to add or modify bridge configurations. Operators can view configuration and sync status but cannot make changes.
• Bridge agent installed: The bridge binary must already be running on your on-premises VM and connected to the platform. The bridge self-registers when it connects. See the Identity Bridge guide for deployment instructions.
• Service account: Each Active Directory domain you configure requires a dedicated service account (a standard domain user is sufficient for read-only sync). The account needs read access to the directory objects you want to sync.

Navigating to Bridge Configuration

1. Log in to GraphnAI with an Admin account
2. Navigate to Bridges in the sidebar
3. The page shows all registered bridges in the left sidebar, each with a connection status indicator
4. Click a bridge to view and edit its configuration

Adding a New Bridge

When the bridge agent starts for the first time, it connects to the platform and self-registers using its bridge ID. No action is required in the UI to register the bridge — it appears automatically in the bridge list once connected.

If you need to provision a new bridge or download the configuration bundle (which contains the bridge ID and server connection settings):

1. Navigate to Bridges in the sidebar
2. Click Add Bridge or Generate Config
3. The platform generates a unique bridge ID and a configuration bundle
4. Download the configuration bundle to the bridge VM
5. Start the bridge agent — it reads the bundle to establish its identity and connect to the platform

After the bridge connects, it appears in the sidebar. You can then configure its domains, sync schedule, and certificates.

Configuring Domains

Adding a Domain

To connect the bridge to an Active Directory domain:

1. Navigate to Bridges in the sidebar and select the bridge
2. Click Add Domain in the Domains section
3. Fill in the domain form:

Field	Description	Example
Domain Name	Fully qualified domain name (FQDN) of the AD domain	corp.example.com
Domain Controllers	Comma-separated list of controller addresses with optional port	dc01.corp.example.com:636, dc02.corp.example.com:636
Service Account Username	Username of the service account for LDAP binding	svc_graphnai
Password	Password for the service account	(enter password)
Use TLS	Enable LDAPS (port 636) for encrypted LDAP connections	Enabled (recommended)

4. Click Test Connection to verify the credentials and controller addresses before saving (see Test Connection below)
5. Click Save to add the domain

Port guidance: LDAPS (TLS) uses port 636 by default. Standard LDAP uses port 389. Use LDAPS in production environments. If you use a non-standard port, include it explicitly (e.g., dc01.corp.example.com:3269 for Global Catalog over SSL).

Editing a Domain

1. Navigate to Bridges in the sidebar and select the bridge
2. Locate the domain in the Domains list
3. Click the edit (pencil) icon next to the domain name
4. Modify the fields as needed
   • To update the password, type the new password in the Password field. If you leave the field blank, the existing saved password is preserved.
   • To change the domain name while keeping the same credentials, edit the Domain Name field — the platform preserves the credential association automatically via a stable domain identifier
5. Click Test Connection to verify the changes before saving
6. Click Save

Removing a Domain

1. Locate the domain in the Domains list
2. Click the delete (trash) icon next to the domain
3. Confirm the deletion in the confirmation dialog
4. Click Save to apply the removal

Removing a domain stops the bridge from querying that domain on future syncs. Existing identity data already collected from the domain remains in the graph until the next reconciliation cycle marks it as tombstoned.

Multi-Domain Setup

A single bridge can manage multiple Active Directory domains — for example, a parent domain and child domains in the same forest, or completely separate forests.

To set up multiple domains:

1. Navigate to Bridges in the sidebar and select the bridge
2. Add each domain using the steps above
3. Each domain is configured independently with its own service account, controllers, and TLS setting
4. Click Save after adding all domains

When the configuration is saved, the bridge receives all domain configurations simultaneously and validates each connection before activating them. If any domain fails validation, the entire reconfiguration is rejected — the bridge continues using the previous working configuration until the issue is resolved. This prevents the bridge from entering a partially configured state.

During syncs, the bridge queries all configured domains concurrently and aggregates the results into a single unified dataset for ingestion.

Test Connection

Before saving a domain configuration, use Test Connection to verify that the bridge can successfully authenticate with the domain controller using the credentials you provided.

How it works:

1. The platform sends the domain configuration (with credentials) to the connected bridge over an encrypted channel
2. The bridge attempts an LDAP bind using the provided service account and password
3. The bridge returns the result — success or a specific error message — within 60 seconds
4. The result is displayed in the UI before you commit to saving

To run a test:

1. Fill in all domain fields (Domain Name, Controllers, Username, Password, TLS setting)
2. Click Test Connection (available in the Add Domain and Edit Domain forms)
3. Wait for the result (typically 2-10 seconds on a healthy connection)
4. If the test succeeds, click Save to commit the configuration
5. If the test fails, review the error message and correct the configuration before retrying

What Test Connection validates:

• The bridge is currently online and reachable
• The domain controller address is reachable from the bridge VM
• The TLS handshake succeeds (if Use TLS is enabled)
• The service account credentials are correct and the account can bind to the directory

Test Connection does not save the configuration. You must click Save after a successful test to persist the changes.

If the bridge is offline (not connected to the platform), Test Connection will fail immediately with a "Bridge is NOT connected" error. Start the bridge agent and wait for it to appear as connected before testing.

Credential Security

GraphnAI handles service account credentials with a zero-trust approach: the platform itself acts as a secure vault, and the bridge VM never holds credentials on disk.

How credentials are protected:

Stage	What happens
Entry	You type a password in the browser. It is transmitted to the platform server over HTTPS (TLS).
Storage	The platform immediately encrypts the password using AES-256-GCM with a unique random nonce. The ciphertext is stored in the database. The plaintext is never written anywhere.
UI display	When you view a bridge configuration in the UI, passwords always appear as ******. The actual ciphertext is never returned.
Config push to bridge	When configuration is saved or the bridge reconnects, the platform decrypts credentials server-side and transmits them to the bridge over TLS 1.3. The bridge receives the plaintext credential in memory only.
Bridge storage	The bridge stores credentials in RAM, never on disk. If the bridge process restarts, it reconnects to the platform and receives a fresh configuration push automatically.

What this means for operations:

• A compromised bridge VM does not expose saved credentials — there are no credential files to steal
• A database backup does not expose credentials — stored ciphertext cannot be decrypted without the platform's tenant key
• Rotating a service account password requires only editing the domain in the platform UI and saving — no changes on the bridge VM

Sync Scheduling

The bridge runs two types of syncs on a configurable schedule:

Sync Type	Purpose	Default
Delta sync	Collects only changes since the last sync (new, modified, and deleted objects) using AD's change tracking mechanism	Every 1 hour
Full sync (reconciliation)	Performs a complete re-read of all directory objects and rebuilds the graph, catching any objects that may have been missed by delta tracking	Every 24 hours

Configuring the Sync Schedule

1. Navigate to Bridges in the sidebar and select the bridge
2. Click Sync Configuration or open the sync settings modal
3. Set the following fields:

Field	Description	Example
Sync Start Time	Time of day (24-hour clock) when the daily full sync begins	02:00 (2:00 AM)
Delta Sync Interval	How often delta syncs run between full syncs	1h (every hour)
Reconciliation Interval	How often full syncs run	24h (once per day)

4. Click Save

The bridge applies the new schedule immediately (without restart). Valid interval formats are Go duration strings: 30m, 1h, 4h, 24h, etc.

Recommendation: Schedule full syncs during off-peak hours (late night or early morning) to minimize load on your domain controllers. Delta syncs are lightweight and can run frequently without significant impact.

Triggering a Manual Sync

To run an immediate sync without waiting for the schedule:

1. Navigate to Bridges in the sidebar and select the bridge
2. Click Trigger Sync
3. Choose the sync type:
   • Full Sync: Re-reads all directory objects (takes longer, typically 5-30 minutes depending on directory size)
   • Delta Sync: Collects only recent changes (typically 30 seconds to a few minutes)
4. The sync status updates in real time in the Sync History panel

Stopping a Sync

To cancel an in-progress sync:

1. Click Stop Sync (visible while a sync is running)
2. The current sync operation is cancelled. The next scheduled sync will run at the configured interval.

Certificate Management

When using LDAPS (TLS) connections to domain controllers, the bridge must trust the domain controller's TLS certificate or its issuing certificate authority. In many environments, domain controllers use certificates issued by an internal Active Directory Certificate Services (AD CS) CA that is not trusted by default.

The Certificate Management feature lets you fetch the certificate chain from a domain controller and add it to the bridge's trust store — all from the platform UI.

Fetching a Domain Controller's Certificate

1. Navigate to Bridges in the sidebar and select the bridge
2. Locate the Certificate Management section
3. In the Fetch Certificates field, enter the domain controller address including port: dc01.corp.example.com:636
4. Click Fetch
5. The bridge connects to the specified address, retrieves the TLS certificate chain, and returns it to the UI

The UI displays each certificate in the chain with:

• Subject: The entity the certificate was issued to
• Issuer: The certificate authority that signed it
• Valid From / Valid To: The certificate's validity period
• Fingerprint: The SHA-256 fingerprint for verification

Trusting a Certificate

To add a certificate to the bridge's trust store:

1. After fetching the certificate chain, locate the certificate you want to trust (typically the root CA at the top of the chain)
2. Click Trust This Certificate next to the certificate
3. The platform sends the certificate to the bridge, which adds it to its in-memory trust store
4. Future LDAPS connections to domain controllers signed by this CA will succeed

Trust the CA certificate, not the domain controller's leaf certificate. The CA certificate covers all domain controllers issued by that CA.

Certificate trust is held in the bridge's memory and is re-established automatically each time the bridge receives a configuration push. No manual re-trust is needed after a bridge restart.

Common Certificate Scenarios

Internal AD CS (most common): Domain controllers in an Active Directory domain are typically issued certificates by the domain's built-in certificate authority. Fetch the certificate from any domain controller, then trust the root CA certificate shown at the top of the chain.

Third-party CA: If domain controllers use certificates from a commercial CA (e.g., DigiCert, Sectigo), the CA certificate is likely already trusted by the operating system. LDAPS should work without additional trust configuration.

Self-signed certificates: Some environments use self-signed certificates on domain controllers. Fetch and trust the certificate directly (it will appear as both issuer and subject).

Per-Domain Status

The Domains section of the bridge configuration page shows a status indicator for each configured domain:

Status	Meaning
Connected	The bridge successfully authenticated and can query this domain
AuthFailed	The domain is reachable but the service account credentials were rejected. Update the password and save the configuration.
Unreachable	The bridge cannot reach the domain controllers. Check network connectivity, firewall rules, and the controller addresses in the configuration.
Unknown	The bridge has not yet attempted a connection to this domain since the last configuration push or restart.

Status is reported by the bridge via its periodic heartbeat and updates in the UI automatically. The Last Check timestamp shown in the status tooltip indicates when the bridge last validated connectivity for that domain.

Per-domain status reflects the result of the connection test that runs when the bridge applies configuration. It does not update continuously between configuration pushes — trigger a sync or save a configuration change to force a re-check.

Config Push Retry

When you save a bridge configuration, the platform immediately attempts to push the updated settings to the bridge over its active connection. If the bridge is offline at the moment you save:

• The configuration is saved to the platform database normally
• The push to the bridge is marked as pending
• When the bridge next reconnects, the platform automatically delivers the pending configuration before any sync can begin

You do not need to take any action to recover from a missed push — the bridge will receive its latest configuration on reconnect. The platform logs a warning when a push fails due to the bridge being offline.

Sync History

The Sync History panel shows a log of recent sync operations for the selected bridge:

• Sync type: Full or Delta
• Start time and duration: When the sync began and how long it took
• Objects collected: Node and edge counts broken down by identity type (Users, Groups, Computers, etc.)
• Status: Success or error, with error details if the sync failed
• Domain: Which domain the sync targeted (for per-domain delta syncs)

To view sync history:

1. Navigate to Bridges in the sidebar and select the bridge
2. Scroll to the Sync History panel at the bottom of the page

Bridge Metrics

The Bridge Metrics panel provides a snapshot of the current data collected for the selected bridge:

• Node counts by type: How many Users, Groups, Computers, Service Accounts, etc. have been synced
• Edge counts by type: How many relationships have been mapped (MemberOf, ContainedIn, ACL permissions, etc.)

Metrics are updated after each sync completes. Use this panel to confirm that a sync collected the expected volume of data, or to compare before and after a configuration change.

Troubleshooting

Bridge appears as disconnected in the sidebar

Possible causes:

• The bridge process is not running on the on-premises VM
• Network or firewall rules are blocking the bridge's outbound connection to the platform server (default port 8443)
• The bridge configuration bundle contains an incorrect server address

Steps to resolve:

1. SSH into the bridge VM and confirm the bridge process is running (ps aux | grep graphnai-bridge or check the service status)
2. Check the bridge agent logs for connection error messages
3. Verify the platform's bridge listener address and port are reachable from the bridge VM — confirm connectivity to port 8443 on the platform server
4. Confirm outbound traffic to port 8443 is permitted by the VM's firewall and any intermediate network appliances

Test Connection fails: "Bridge is NOT connected"

The bridge agent must be running and connected before Test Connection can work. The test is relayed through the live bridge, not the platform server.

Steps to resolve:

1. Confirm the bridge appears as connected in the sidebar (green indicator)
2. If the bridge is offline, start the bridge agent and wait for it to reconnect (typically a few seconds)
3. Retry Test Connection once the bridge shows as connected

Test Connection fails: "invalid credentials" or "LDAP bind failed"

Possible causes:

• The service account username or password is incorrect
• The account is locked or disabled in Active Directory
• The account does not have read permission on the directory

Steps to resolve:

1. Verify the service account can log in interactively or perform an LDAP bind using a tool like ldp.exe or ldapsearch
2. Check the AD account status — confirm it is not locked, expired, or disabled
3. Verify the account has the necessary read permissions (standard domain user is sufficient in default AD configurations)
4. Confirm the username format matches what the domain expects (e.g., svc_graphnai vs. CORP\svc_graphnai vs. [email protected])

Test Connection fails: "connection refused" or "no route to host"

Possible causes:

• The domain controller address or port is incorrect
• The domain controller's LDAP/LDAPS port is blocked by a firewall between the bridge VM and the domain controller
• The domain controller is offline

Steps to resolve:

1. Confirm the domain controller is reachable from the bridge VM: Test-NetConnection dc01.corp.example.com -Port 636 (PowerShell) or nc -zv dc01.corp.example.com 636 (Linux)
2. Check that the port matches the TLS setting: port 636 for LDAPS (Use TLS = enabled), port 389 for plain LDAP
3. If using a non-standard port, confirm the port is included in the controller address (e.g., dc01.corp.example.com:3269)
4. Review firewall rules between the bridge VM and the domain controller subnet

LDAPS connection fails with "certificate verify failed" or "x509 error"

Cause: The bridge does not trust the certificate presented by the domain controller, typically because the domain uses an internal certificate authority.

Steps to resolve:

1. Navigate to the Bridge detail page, then click "Edit" on a domain
2. Enter the domain controller address (e.g., dc01.corp.example.com:636) and click Fetch
3. Review the certificate chain displayed
4. Click Trust This Certificate on the root CA certificate (the top entry in the chain)
5. Retry the LDAPS connection or click Test Connection again

A domain shows "AuthFailed" status after configuration was working

Possible causes:

• The service account password was changed or the account was locked
• The service account was disabled or deleted in Active Directory
• The domain controller certificate expired (for LDAPS connections)

Steps to resolve:

1. Check the domain status tooltip for the specific error message
2. Verify the service account status in Active Directory Users and Computers or via PowerShell (Get-ADUser svc_graphnai -Properties LockedOut, Enabled)
3. If the password was rotated, edit the domain configuration, enter the new password, test the connection, and save
4. If the certificate expired, fetch and trust the renewed certificate via Certificate Management

Configuration saved but bridge is still using old settings

Cause: The bridge may have been offline when the configuration was saved.

Steps to resolve:

1. Check the bridge connection status in the sidebar
2. If the bridge is now connected, the pending configuration push is delivered automatically — no action needed
3. To force an immediate update, save the configuration again while the bridge is connected
4. Check the server logs if the issue persists: search for "Marked bridge for config re-push on reconnect" to confirm the retry was queued

"Bridge ID mismatch" error

Cause: The bridge ID in the configuration does not match the registered bridge identifier.

Resolution: Ensure the bridge ID shown in the platform UI matches the bridge identifier in your configuration bundle. If the mismatch persists, regenerate the configuration bundle from Bridges in the sidebar, then click Generate Config.

Related Documentation

• Attribute Sync Configuration — Configure which AD attributes the bridge collects during sync
• Stale Identity Detection — Use synced data to find dormant accounts