Skip to main content

LDAP Agent deployment guide

Workspace scope

The LDAP Agent is shared infrastructure used by all Active Directory connections in SecureAuth Connect. Deployment is the same for Workforce, B2B, enterprise, and partner workspaces. For workspace-specific connection setup, see Active Directory (Workforce) (Workforce workspace) or Active Directory (CIAM) (B2B, enterprise, partner workspaces).

Shared with Arculix

The LDAP Agent is the same binary for SecureAuth Connect and Arculix deployments. This deployment guide applies to both products.

The LDAP Agent connects your Active Directory with SecureAuth for authentication and user synchronization. This guide covers installation and configuration.

Architecture overview​

SecureAuth Connect handles authentication for your organization, but it needs a secure connection to your Active Directory to verify user credentials and retrieve user information. The LDAP Agent provides this connection by running on a server within your network that can communicate with both:

  • Your Active Directory: Through LDAP/LDAPS protocols for user authentication and directory queries
  • SecureAuth Connect: Through secure WebSocket connections for authentication requests

System requirements​

These requirements apply to the on-premises or cloud server where you install the LDAP Agent.

Supported operating systems​

Windows

  • Windows Server 2016 or later

Linux

  • Red Hat Enterprise Linux 8/9
  • Rocky Linux 8/9
  • Ubuntu 18.04 LTS
  • Ubuntu 20.04 LTS

Minimum hardware requirements​

  • CPU: 2 cores minimum
  • Memory: 2-4 GB RAM
  • Storage: 16-32 GB SSD storage
  • Network: Reliable network connectivity to domain controllers and SecureAuth
note

Windows Server environments typically require resources at the higher end of these ranges, while Linux installations generally operate efficiently with the minimum specifications.

High availability recommendations​

We recommend deploying two or more LDAP Agent instances to provide high availability. For authentication and directory queries, the LDAP Agent is stateless and scales horizontally without limitation. The system can also operate with a single instance if high availability is not required.

If you enable Active Directory Sync, enable it on only one instance. See Running multiple agent instances.

Any virtualization platform capable of hosting Linux or Windows servers is suitable, including:

  • On-premises: VMware ESXi, Microsoft Hyper-V
  • Cloud environments: Amazon EC2, Microsoft Azure

Network requirements​

All communication with the LDAP Agent uses HTTPS with additional security layers that provide authenticity beyond HTTPS certificates by signing all communication.

Outbound access​

The LDAP Agent requires outbound access to these external services:

ServiceProtocolPortHost
SecureAuth SwitchboardWSS (WebSocket Secure)443Environment-specific (see Cloud Server Environments)

Additional outbound access for Docker deployments:

ServiceProtocolPortHost
Docker updatesTCP80, 443download.docker.com
Docker Compose downloadTCP80, 443github.com

Internal network access​

The LDAP Agent requires access to these internal services:

ServiceProtocolPortDescription
LDAPSTCP636Secure LDAP service (recommended)
LDAPTCP389Non-secure LDAP service
DNSUDP53DNS server
caution

Use of non-secure LDAP (port 389) is not recommended. Only use when you can guarantee protection of data in transit through other means such as physical security controls.

Active Directory requirements​

The LDAP Agent communicates with your Active Directory using the LDAP protocol. Before deployment, prepare the following information and ensure proper account provisioning.

Required configuration​

ParameterRequiredDescription
LDAP URLYesThe LDAP URL for performing directory queries.

Must begin with ldap:// or ldaps:// and may include an optional port number (default: 389 for ldap, 636 for ldaps).

Examples:
• ldaps://dc1.company.com/
• ldaps://ad1.example.org:5000/
Bind UserLinux onlyThe user account for binding to the LDAP server (SIMPLE authentication).

Not required on Windows, where the agent uses Kerberos/SSPI with the service account.

Format options:
• Distinguished Name: CN=SecureAuthService,OU=Service Accounts,DC=company,DC=com
• User Principal Name: secureauth-svc@company.com

Important: Create a dedicated service account with read-only access to the directory.
Bind PasswordLinux onlyPassword for the bind user account. Not required on Windows (Kerberos/SSPI).
Base DNYesStarting point for LDAP queries. All relevant users and groups must be descendants of this DN.

Example: DC=company,DC=com
TLS Trusted CAsNoPEM format certificates representing trusted certificate authorities for verifying the LDAP server's certificate.

Include enterprise CA certificates or the LDAP server certificate itself.

Warning: If specified, the operating system's default trusted CAs will not be used.

Service account requirements​

Basic permissions:

  • Read access to all user and group objects in the directory
  • Password reset permissions (required only if enabling password reset functionality)
warning

The SecureAuth integration will stop functioning if the service account is disabled, its password is changed, or its privileges are revoked.

Pre-installation checklist​

Use this checklist to prepare for installation:

  • Required servers or virtual machines are provisioned
  • Required firewall rules are in place
  • Active Directory read-only service account has been created
  • Active Directory LDAP service is reachable from LDAP Agent hosts
  • Optional: If using LDAPS (port 636), certificate or certificate chain is available for server verification

Get connector information for LDAP Agent​

Before installation, obtain the Agent ID and Shared Secret from your Active Directory connection in SecureAuth Connect. The location depends on the workspace type.

Arculix administrators

If you're deploying the LDAP Agent for Arculix, retrieve the Agent ID and Shared Secret from the Arculix admin console: User Directories > your Active Directory configuration. Skip the SecureAuth Connect steps below.

Workforce workspaces​

  1. Go to Authentication > User Stores.

  2. Edit your Microsoft Active Directory connection.

  3. Expand Search Lookup and Password Permission.

  4. Copy the Agent ID and Shared Secret.

    Agent ID and Shared Secret in Workforce User Stores configuration

B2B, enterprise, and partner workspaces​

  1. Go to Authentication > Providers.

  2. Open your Active Directory identity provider.

  3. On the Configuration tab, expand Active Directory Settings.

  4. Click Copy to copy the Agent ID, then click Click to Reveal to display the Shared Secret.

    Active Directory Settings section with agent credentials and login attributes

Installation​

Choose your platform:

Windows install and configuration

For Active Directory environments, installing the LDAP Agent on a domain-joined Windows Server is the recommended approach. It enables Kerberos/SSPI authentication, so you don't store service account passwords in configuration files.

Prerequisites​

  • Windows Server 2016 or later, domain-joined.
  • A domain service account to run the LDAP Agent service. The account needs read access to the directory for LDAP queries, password reset permissions if you enable password reset, and the "Replicating Directory Changes" permission if you enable AD Sync.
  • Outbound HTTPS (port 443) access to SecureAuth cloud services and LDAPS (port 636) access to your domain controllers.
  • Agent ID and Shared Secret from SecureAuth. See Get connector information for LDAP Agent.

Install the service​

Use the installer for a standard deployment:

  1. Download the Windows installer package. If you haven't already downloaded it while adding Active Directory in SecureAuth Connect, see Connect Active Directory for download instructions.
  2. Run the installer as an administrator.
  3. Set the service to run under your domain service account so it can authenticate with Kerberos.
  4. Configure the agent using the YAML configuration file (shown below).

Alternatively, install and manage the service from the command line. Run PowerShell as an administrator:

# Test connectivity before installing (requires --config)
.\ldap-agent.exe --config config.yaml --test

# Run in the foreground for testing (requires --config; Ctrl+C to stop)
.\ldap-agent.exe --config config.yaml --foreground

# Install the Windows service (requires --config; embeds the path in the service)
.\ldap-agent.exe --config config.yaml --install

# Start the service
.\ldap-agent.exe --start

# Stop the service
.\ldap-agent.exe --stop

# Uninstall the service
.\ldap-agent.exe --remove

Only --install, --test, and --foreground require the --config argument. The --start, --stop, and --remove commands manage the service by name and don't need a configuration file.

Check status and view logs with:

# Check service status
Get-Service "Acceptto LDAP Agent"

# View recent service logs in Event Viewer
Get-EventLog -LogName Application -Source "Acceptto LDAP Agent" -Newest 20

Windows configuration​

On Windows, the agent automatically uses Kerberos/SSPI authentication when you don't provide bind credentials. This is the recommended configuration:

AgentID: ldap:v1:your-agent-id
SharedSecret: your-base64-shared-secret

# LDAP configuration - no credentials needed on Windows
LDAPURLs:
    - ldaps://dc.company.com:636/
LDAPBaseDN: dc=company,dc=com

# LDAPBindUser and LDAPBindPass are not required on Windows.
# The agent uses the Windows service account credentials automatically.

# Optional: trust your enterprise CA certificate
LDAPTLSTrustedCAs: |
    -----BEGIN CERTIFICATE-----
    ... your CA certificate ...
    -----END CERTIFICATE-----

Running under a domain service account with Kerberos/SSPI keeps passwords out of configuration files, lets Windows manage the credentials, and allows password reset and AD Sync to work automatically with the service account's permissions.

Linux RPM installation

The LDAP Agent RPM package is named acceptto-ldap-agent-X.Y.Z-1.x86_64.rpm, where X.Y.Z is the version number.

Installation process​

When installed via RPM, the agent integrates with systemd for service management, including automatic launch at boot and logging through syslog. Agent logs are written to /var/log/messages by default (locations may vary based on your infrastructure).

Installation steps​

  1. Download the RPM package. If you haven't already downloaded it while adding Active Directory in SecureAuth Connect, see Connect Active Directory for download instructions.

  2. Install the package:

    sudo rpm -ivh acceptto-ldap-agent-X.Y.Z-1.x86_64.rpm

  3. Configure the agent by editing the YAML configuration file:

    sudo vi /etc/acceptto/ldap-agent.conf

  4. Test the agent connectivity (optional but recommended):

    ldap-agent -config /etc/acceptto/ldap-agent.conf -test

  5. Enable and start the service:

    sudo systemctl enable acceptto-ldap-agent
    sudo systemctl start acceptto-ldap-agent

Service management​

# Start the service
sudo systemctl start acceptto-ldap-agent

# Stop the service
sudo systemctl stop acceptto-ldap-agent

# Restart the service
sudo systemctl restart acceptto-ldap-agent

# Check service status
sudo systemctl status acceptto-ldap-agent

# View logs
sudo journalctl -u acceptto-ldap-agent -f
note

If an ldap-agent.env file is present in /etc/acceptto/, it will be used instead of the YAML ldap-agent.conf file for backwards compatibility. SecureAuth recommends using the YAML configuration for new RPM deployments.

Linux install (Docker)

On Linux, the LDAP Agent runs as a Docker container. Kerberos/SSPI is not available on Linux, so you must provide bind credentials (LDAPBindUser and LDAPBindPass) for SIMPLE authentication.

Prerequisites​

  • An x86-64 Linux server capable of running Docker. The agent is lightweight: a dedicated host with 2 GB RAM and 16 GB storage is sufficient. Physical and virtual servers are both supported. The supplied installation scripts support:
    • Red Hat Enterprise Linux 8 or 9
    • Rocky Linux 8 or 9
    • Ubuntu 18.04 LTS or 20.04 LTS
  • Docker 19.3.0 or higher and Docker Compose 1.26 or higher. The bundled install-docker.sh script can install these if they aren't already present.
  • Incoming network access from SecureAuth cloud services on the configured HTTPS port (typically 443).
  • Outgoing access to your LDAP directory server on port 389 (LDAP) or 636 (LDAPS).

Package contents​

The agent is distributed as an archive named ldap-agent-X.Y.Z.tar.xz, where X.Y.Z is the release version. It contains:

  • docker-compose.yml – Docker Compose configuration for launching the agent.
  • install-docker.sh – Helper script to install Docker on the host.
  • install.sh – The LDAP Agent installation script.
  • ldap-agent-image.tar – The LDAP Agent Docker image.
  • manifest.json – Release metadata, provided for informational purposes only.

First-time installation​

  1. Download the installation package ldap-agent-X.Y.Z.tar.xz and upload it to the server. If you haven't already downloaded it while adding Active Directory in SecureAuth Connect, see Connect Active Directory for download instructions.
  2. Extract the archive and change into the directory: 
    tar -xvJ -f ldap-agent-X.Y.Z.tar.xz
    cd ldap-agent-X.Y.Z
  3. Install Docker if it isn't already present: 
    sudo ./install-docker.sh
  4. Create the configuration file. Add an ldap-agent-config.env file to the ldap-agent-X.Y.Z directory with your Active Directory and SecureAuth connection values. See LDAP Agent configuration for the available settings.
  5. Install the agent: 
    sudo ./install.sh
  6. Test connectivity to Active Directory: 
    docker compose exec ldap-agent ./ldap-agent -test

Upgrade​

  1. Upload the new installation package ldap-agent-X.Y.Z.tar.xz to the server.
  2. Extract it and change into the directory: 
    tar -xvJ -f ldap-agent-X.Y.Z.tar.xz
    cd ldap-agent-X.Y.Z
  3. Run the installation script: 
    sudo ./install.sh

LDAP Agent configuration​

Authentication methods​

The LDAP Agent supports two methods for authenticating to Active Directory:

MethodPlatformConfiguration
Kerberos/SSPI (recommended)Windows onlyLeave LDAPBindUser and LDAPBindPass empty. The agent uses the Windows service account credentials, so no passwords are stored in configuration files.
SIMPLE (username and password)All platformsProvide LDAPBindUser and LDAPBindPass. Credentials are stored in the configuration.

On Windows, when LDAPBindUser and LDAPBindPass are empty, the agent automatically uses Kerberos/SSPI with the Windows service account. This is the recommended configuration for Windows deployments.

On Linux, Kerberos/SSPI is not available. Provide LDAPBindUser and LDAPBindPass for SIMPLE authentication.

Configuration file locations​

Windows

  • Configuration: C:\Program Files\SecureAuth\LDAP Agent\config\config.yaml (YAML format)
  • Logs: C:\Program Files\SecureAuth\LDAP Agent\logs\

Linux (RPM installation)

  • Configuration: /etc/acceptto/ldap-agent.conf (YAML format)
  • Alternative: /etc/acceptto/ldap-agent.env (environment variables)
  • Logs: /var/log/messages

Linux (Docker)

  • Configuration: ldap-agent-config.env in the agent install directory (environment variables)
  • Logs: docker compose logs ldap-agent
# Get Agent ID and Shared Secret from your user store connection settings in SecureAuth Connect
AgentID: your-agent-id-from-secureauth
SharedSecret: your-shared-secret-from-secureauth

# The LDAP parameters used to reach a user store, like Active Directory
LDAPURLs:
    - ldaps://dc1.company.com/
    - ldaps://dc2.company.com/
LDAPBindUser: CN=SecureAuthService,OU=Service Accounts,DC=company,DC=com
LDAPBindPass: your-service-account-password
LDAPBaseDN: DC=company,DC=com

# Optional: Password reset functionality (requires LDAPS)
# LDAPResetPasswordBindUser: CN=SecureAuthResetService,OU=Service Accounts,DC=company,DC=com
# LDAPResetPasswordBindPass: your-reset-service-account-password

# Optional: If using LDAPS and the LDAP server's certificate is not issued by a public
# certificate authority, provide a trusted root CA or the LDAPS certificate itself
# LDAPTLSTrustedCAs: |
#     -----BEGIN CERTIFICATE-----
#     MIIFdzCCA1+gAwIBAgIUPhmZ5ytNQDJ1gqIYtPWXsFSXbm8wDQYJKoZIhvcNAQEL
#     BQAwYzELMAkGA1UEBhMCVVMxDzANBgNVBAgMBk9yZWdvbjERMA8GA1UEBwwIUG9y
#     ...
#     nRFv5H77DMo15HfFgGsy7zCt7OrIHl/G/PVLce4/4T+cLjahHDbn5J6Cz9DWNYYq
#     jRgO45686HIchzfyTpPRbdt+S7TA+1ToUX5nlnCFhsgcCwBuPqCozNBvTbYN7xdq
#     fkATtpM5lE4Ip7Y=
#     -----END CERTIFICATE-----

# Optional: Additional configuration
# LogLevel: info
# AuthenticationTimeout: 5s
# RequestTimeout: 5s
# RequestWorkers: 500

Environment variable format (alternative)​

# SecureAuth connection
ALA_AGENT_ID=your-agent-id-from-secureauth
ALA_SHARED_SECRET=your-shared-secret-from-secureauth

# The LDAP parameters used to reach your user store like Active Directory
ALA_LDAP_URLS='ldaps://dc1.company.com/,ldaps://dc2.company.com/'
ALA_LDAP_BIND_USER='CN=SecureAuthService,OU=Service Accounts,DC=company,DC=com'
ALA_LDAP_BIND_PASS='your-service-account-password'
ALA_LDAP_BASE_DN='DC=company,DC=com'

# Optional: Password reset functionality (requires LDAPS)
# ALA_LDAP_RESET_PASSWORD_BIND_USER='CN=SecureAuthResetService,OU=Service Accounts,DC=company,DC=com'
# ALA_LDAP_RESET_PASSWORD_BIND_PASS='your-reset-service-account-password'

# Optional: TLS certificate configuration
# ALA_LDAP_TLS_TRUSTED_CAS='
# -----BEGIN CERTIFICATE-----
# MIIFdzCCA1+gAwIBAgIUPhmZ5ytNQDJ1gqIYtPWXsFSXbm8wDQYJKoZIhvcNAQEL
# BQAwYzELMAkGA1UEBhMCVVMxDzANBgNVBAgMBk9yZWdvbjERMA8GA1UEBwwIUG9y
# ...
# nRFv5H77DMo15HfFgGsy7zCt7OrIHl/G/PVLce4/4T+cLjahHDbn5J6Cz9DWNYYq
# jRgO45686HIchzfyTpPRbdt+S7TA+1ToUX5nlnCFhsgcCwBuPqCozNBvTbYN7xdq
# fkATtpM5lE4Ip7Y=
# -----END CERTIFICATE-----

# Optional: Additional configuration
# ALA_LOG_LEVEL=info
# ALA_AUTHENTICATION_TIMEOUT=5s
# ALA_REQUEST_TIMEOUT=5s
# ALA_REQUEST_WORKERS=500

Required configuration parameters​

ParameterYAML FormatEnvironment FormatDescription
Agent IDAgentIDALA_AGENT_IDUnique identifier from SecureAuth Connect
Shared SecretSharedSecretALA_SHARED_SECRETAuthentication token from SecureAuth Connect
LDAP URLsLDAPURLsALA_LDAP_URLSArray/comma-separated list of domain controller URLs
Bind UserLDAPBindUserALA_LDAP_BIND_USERService account for directory binding. Required on Linux (SIMPLE auth); leave empty on Windows to use Kerberos/SSPI.
Bind PasswordLDAPBindPassALA_LDAP_BIND_PASSPassword for the bind user. Required on Linux; leave empty on Windows (Kerberos/SSPI).
Base DNLDAPBaseDNALA_LDAP_BASE_DNStarting point for directory searches

Optional configuration parameters​

ParameterYAML FormatEnvironment FormatDescription
TLS Trusted CAsLDAPTLSTrustedCAsALA_LDAP_TLS_TRUSTED_CASPEM certificates representing trusted certificate authorities for verifying the LDAP server's certificate. Warning: If specified, the operating system's default trusted CAs will not be used.
TLS Server NamesLDAPTLSServerNamesALA_LDAP_TLS_SERVER_NAMESHostname expected in the LDAP server's certificate if different from the URL hostname. Provide one per LDAP URL in the same order.
TLS Disable VerificationLDAPTLSDisableVerificationALA_LDAP_TLS_DISABLE_VERIFICATIONDisable server certificate verification. Warning: Only for development/debugging - vulnerable to man-in-the-middle attacks. Default: false
Log LevelLogLevelALA_LOG_LEVELLogging level: panic, fatal, error, warn, info, debug, or trace. Default: info
Switchboard URLSwitchboardURLALA_SWITCHBOARD_URLURL for the SecureAuth Switchboard service. Use the URL for your environment (see Cloud Server Environments). Default: https://switchboard.acceptto.com (Acceptto Legacy).
Authentication TimeoutAuthenticationTimeoutALA_AUTHENTICATION_TIMEOUTHow long to wait for authentication completion. Format: {number}{unit} (e.g. 5s, 1m). Default: 5s
Request TimeoutRequestTimeoutALA_REQUEST_TIMEOUTTimeout for LDAP connection requests. Format: {number}{unit}. Default: 5s
Request WorkersRequestWorkersALA_REQUEST_WORKERSNumber of concurrent workers for processing requests and LDAP lookups. Default: 500
HTTP ProxyHTTPProxyALA_HTTP_PROXYURL of proxy server for outbound HTTP/HTTPS traffic.
Reset Password Bind UserLDAPResetPasswordBindUserALA_LDAP_RESET_PASSWORD_BIND_USERService account for password reset operations. Required on Linux for password reset; optional on Windows (uses the service account via Kerberos).
Reset Password Bind PassLDAPResetPasswordBindPassALA_LDAP_RESET_PASSWORD_BIND_PASSPassword for the reset password bind user. Required on Linux; not needed on Windows (Kerberos).
note

Password change and password reset are only supported over LDAPS (LDAP over SSL) connections.

Cloud Server Environments​

SecureAuth operates multiple cloud environments. Configure the agent to connect to the environment for your deployment. The Switchboard URL and, if you enable sync, the sync endpoints must all point to the same environment.

EnvironmentSwitchboard URLBase API URL
CIAM UShttps://switchboard.services.us.connect.secureauth.comhttps://workforce.services.us.connect.secureauth.com
CIAM EUhttps://switchboard.services.eu.connect.secureauth.comhttps://workforce.services.eu.connect.secureauth.com
Acceptto Legacyhttps://switchboard.acceptto.comhttps://mfa.acceptto.com
Developmenthttps://switchboard.eguardian.iohttps://dev.eguardian.io

For example, to connect the agent to the CIAM US environment:

ALA_SWITCHBOARD_URL=https://switchboard.services.us.connect.secureauth.com

When you enable sync, configure the sync endpoints for the same environment. See Active Directory Sync configuration.

Accessing LDAPS servers via a load balancer​

Some deployments place a pool of LDAPS servers behind a load balancer. The agent connects to a single URL (the load balancer), but each backend server may present a certificate with a different hostname, which can cause certificate verification to fail.

To resolve this, use one of the following approaches:

  • Terminate TLS at the load balancer so the agent always sees a single certificate. The certificate's subject must match either the load balancer's address or the configured entry in LDAPTLSServerNames.
  • Use the same certificate name on each backend server and set that name in LDAPTLSServerNames if it isn't the load balancer address.
  • Add a Subject Alternative Name (SAN) for the load balancer's address to each backend server's certificate, if the servers need distinct certificates.
Service management

Windows

# Start the service
net start "Acceptto LDAP Agent"

# Stop the service
net stop "Acceptto LDAP Agent"

# Restart the service
net stop "Acceptto LDAP Agent" && net start "Acceptto LDAP Agent"

Linux

# Start the service
sudo systemctl start acceptto-ldap-agent

# Stop the service
sudo systemctl stop acceptto-ldap-agent

# Restart the service
sudo systemctl restart acceptto-ldap-agent

# Check service status
sudo systemctl status acceptto-ldap-agent

Active Directory Sync configuration​

The LDAP Agent can synchronize users and groups from Active Directory into the SecureAuth cloud directory, so you don't have to provision users manually. Sync uses Microsoft's DirSync control to track changes (creates, updates, and deletes) efficiently and send them to the cloud. Sync is optional and disabled by default.

Sync prerequisites​

Before you enable sync, confirm the following:

  • Replicating Directory Changes permission – The account used for sync must have the "Replicating Directory Changes" permission on the domain partition. On Windows with Kerberos/SSPI, this is the service account; on Linux, it's the bind account. Grant it with PowerShell:

    dsacls "DC=company,DC=com" /G "DOMAIN\SyncServiceAccount:CA;Replicating Directory Changes"

    To verify which accounts already have it:

    dsacls "DC=company,DC=com" | Select-String "Replicating Directory Changes"

  • Direct domain controller access – Point sync at a specific domain controller, such as ldaps://dc1.company.com:636, not a load-balanced URL. The DirSync cookie is specific to one domain controller, and switching controllers can cause duplicate events or an unexpected full resync.

  • Partition root as the Base DN – The sync Base DN must be a partition root (for example, DC=company,DC=com), not an OU. DirSync cannot search from an OU.

Sync configuration reference​

All sync settings are optional when sync is disabled (the default). On Windows with Kerberos/SSPI, sync uses the Windows service account automatically, so no bind credentials are needed. On Linux, sync requires explicit bind credentials with the "Replicating Directory Changes" permission.

ParameterYAML FormatEnvironment FormatDescription
Enable syncSync.EnabledALA_SYNC_ENABLEDEnable Active Directory synchronization. Default: false.
Sync LDAP URLSync.LDAPURLALA_SYNC_LDAP_URLLDAP URL for sync operations. Use a specific domain controller, not a load balancer. Default: first URL from LDAPURLs.
Sync Bind UserSync.LDAPBindUserALA_SYNC_LDAP_BIND_USERBind user for sync. Optional on Windows. Must have the "Replicating Directory Changes" permission. Default: value of LDAPBindUser.
Sync Bind PasswordSync.LDAPBindPassALA_SYNC_LDAP_BIND_PASSPassword for the sync bind user. Optional on Windows. Default: value of LDAPBindPass.
Sync Base DNSync.LDAPBaseDNALA_SYNC_LDAP_BASE_DNBase DN for sync. Must be a partition root. Default: value of LDAPBaseDN.
Cookie File PathSync.CookieFilePathALA_SYNC_COOKIE_FILE_PATHFile path for persisting the sync cookie. Default: platform-specific config directory.
Poll IntervalSync.PollIntervalALA_SYNC_POLL_INTERVALInterval between sync operations when caught up. Default: 60s.
Catchup IntervalSync.CatchupIntervalALA_SYNC_CATCHUP_INTERVALInterval when more results are available from Active Directory. Default: 30s.
Token EndpointSync.TokenEndpointALA_SYNC_TOKEN_ENDPOINTOAuth token endpoint for sync authentication. Use the endpoint for your environment (see below).
Sync EndpointSync.SyncEndpointALA_SYNC_ENDPOINTEndpoint where sync data is sent. Use the endpoint for your environment (see below).

The token and sync endpoints must match the same environment as the agent's Switchboard URL:

EnvironmentToken endpointSync endpoint
CIAM UShttps://workforce.services.us.connect.secureauth.com/api/agent/v1/oauth/tokenhttps://workforce.services.us.connect.secureauth.com/api/agent/v1/sync
CIAM EUhttps://workforce.services.eu.connect.secureauth.com/api/agent/v1/oauth/tokenhttps://workforce.services.eu.connect.secureauth.com/api/agent/v1/sync
Acceptto Legacyhttps://mfa.acceptto.com/api/agent/v1/oauth/tokenhttps://mfa.acceptto.com/api/agent/v1/sync
Developmenthttps://dev.eguardian.io/api/agent/v1/oauth/tokenhttps://dev.eguardian.io/api/agent/v1/sync

Example sync configuration​

Windows (recommended)

On Windows with Kerberos/SSPI, sync configuration is minimal. Add the following to your YAML configuration file:

Sync:
  Enabled: true
  LDAPURL: ldaps://dc1.company.com:636  # Use a specific DC, not a load balancer
  # No credentials needed - uses the Windows service account automatically

  # Endpoints for your environment (example: CIAM US)
  TokenEndpoint: https://workforce.services.us.connect.secureauth.com/api/agent/v1/oauth/token
  SyncEndpoint: https://workforce.services.us.connect.secureauth.com/api/agent/v1/sync

Linux

Add the following to your ldap-agent-config.env file. This example uses the CIAM US environment:

# Enable sync
ALA_SYNC_ENABLED=true

# Use a specific domain controller (not a load balancer)
ALA_SYNC_LDAP_URL=ldaps://dc1.company.com:636

# Required on Linux: an account with "Replicating Directory Changes" permission
ALA_SYNC_LDAP_BIND_USER=sync-service@company.com
ALA_SYNC_LDAP_BIND_PASS=your-sync-password

# Endpoints for the CIAM US environment (must match ALA_SWITCHBOARD_URL)
ALA_SYNC_TOKEN_ENDPOINT=https://workforce.services.us.connect.secureauth.com/api/agent/v1/oauth/token
ALA_SYNC_ENDPOINT=https://workforce.services.us.connect.secureauth.com/api/agent/v1/sync

# Optional: persist the cookie to a mounted volume (see below)
ALA_SYNC_COOKIE_FILE_PATH=/data/dirsync-cookie.json

The sync cookie maintains state between agent restarts. If the cookie is lost, the server returns the correct state on the next sync request, but persisting it locally avoids an unnecessary round-trip on every restart.

When running with Docker, persist the cookie to a volume that survives container restarts. Add a volume mount to your docker-compose.yml:

services:
  ldap-agent:
    # ... existing configuration ...
    volumes:
      - ldap-agent-data:/data

volumes:
  ldap-agent-data:

Then set the cookie path to that volume:

ALA_SYNC_COOKIE_FILE_PATH=/data/dirsync-cookie.json

Running multiple agent instances​

When you deploy multiple LDAP Agent instances for high availability, enable sync on only one of them.

If more than one instance has sync enabled, the instances conflict: when one syncs and updates the cloud state, the others detect a state mismatch and are forced to resync. This causes no data loss, but it wastes resources and adds unnecessary round-trips to the cloud.

Recommended approach:

  • Run multiple instances for LDAP query redundancy.
  • Enable sync (Sync.Enabled: true or ALA_SYNC_ENABLED=true) on only one designated instance.
  • If that instance fails, enable sync on a standby instance.
Troubleshooting common issues

Agent cannot connect to SecureAuth

  • Verify Agent ID and Shared Secret are correct
  • Check network connectivity to SecureAuth Switchboard
  • Review firewall rules

Agent cannot connect to Active Directory

  • Verify LDAP URLs are accessible
  • Test service account credentials
  • Check domain controller availability

Authentication failures

  • Verify Base DN is correct
  • Check service account permissions in Active Directory
  • Review user account status

Check logs

  • Windows: Event Viewer and agent log files
  • Linux: sudo journalctl -u acceptto-ldap-agent -f

FAQ​

How many users can a single LDAP Agent serve?

Authentications are not compute intensive and a single LDAP Agent can generally serve thousands of users. We are able to provide more precise estimates after reviewing your specific needs.

Once the LDAP Agent requirements are met, what is the typical deployment and configuration effort to connect to Active Directory?

A typical remote or on-site deployment session takes our engineering team two hours start to finish. That is assuming all requirements are met and the team is ready to deploy and configure the agent.

Would we need dedicated VMs for development and staging as well?

Yes. While a single LDAP Agent instance can access development and staging directories stored in separate domains within an Active Directory forest (e.g. by using an Active Directory global catalog), we recommend using separate agent instances for development, staging, and production to maintain proper segregation between these deployments.

Does the LDAP Agent support multiple Active Directory domains and forests?

Yes. A single LDAP Agent may support multiple domains in a forest by using the Active Directory global catalog. Alternatively, multiple agents (or multiple load balanced agent groups) may be deployed -- each configured to serve users from specific domains. In this way, customers with multiple distinct forests may be easily accommodated.

What kind of information does the LDAP Agent send to SecureAuth?

The LDAP Agent acts as a worker waiting for commands from SecureAuth such as performing live user authentications, user lookups and checking the user group membership while enforcing SecureAuth group policies.

Next steps​

After deploying the LDAP Agent:

See also​