Skip to main content
Workforce

LDAP Agent deployment guide

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

Architecture overview​

SecureAuth Workforce IAM 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 Workforce IAM: 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 2012 or later

Linux

  • Red Hat Enterprise Linux 8/9
  • Rocky Linux 8/9
  • Amazon Linux 2
  • Ubuntu 22.04 LTS
  • Ubuntu 24.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. The LDAP Agent is a stateless service with no limitations for horizontal scaling. However, the system can operate with a single instance if high availability is not required.

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)443switchboard.acceptto.com

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 UserYesThe user account for binding to the LDAP server.

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 PasswordYesPassword for the bind user account.
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, you need to obtain the Agent ID and Shared Secret from your Active Directory connection in SecureAuth IAM.

  1. In your Workforce workspace, go to User Directories.
  2. Edit a Microsoft Active Directory connection.
  3. Expand Search Lookup and Password Permission section and copy the Agent ID and Shared Secret for use during installation. Copy Agent ID and Shared Secret

Installation​

Choose your platform:

Windows install and configuration

The LDAP Agent for Windows is provided as a self-installing executable: LDAP-Agent-X.Y.Z.exe.

Prerequisites​

  • Windows Server that can reach your Active Directory domain controllers
  • Administrative privileges on the server
  • Agent ID and Shared Secret from SecureAuth (see above)

Installation steps​

  1. Download the latest LDAP Agent installer. If you haven't already downloaded it while adding Active Directory in SecureAuth IAM, see Connect Active Directory for download instructions.

  2. Login to Windows Server with administrative privileges.

  3. Run the installer by double-clicking the executable file.

  4. Follow the installation wizard prompts to install the agent.

  5. Configure the agent by entering the required AD connection details on the General tab: LDAP Agent General Settings

    User Name
    Service account in user@domain format (e.g., secureauth-svc@company.com)

    Password
    Password for the service account

    Base DN
    Starting point for directory searches (e.g., DC=company,DC=com)

    URL
    Domain controller URL with ldaps:// or ldap:// (e.g., ldaps://dc1.company.com)

    Agent ID
    Unique identifier from SecureAuth IAM. See Get connector information for LDAP Agent

    Shared Secret Key
    Authentication token from SecureAuth IAM. See Get connector information for LDAP Agent

    Log Level
    Logging severity level (recommended: info)

  6. After configuration is complete, click Finish. Next, you need to modify LDAP settings

Modify LDAP settings​

  1. Open Notepad as an Administrator and go to the configuration file path for the LDAP Agent.
  2. Open the ldap-agent.conf file.
  3. At the top of the configuration block, paste the Switchboard URL.
  4. Save your changes.

Restart the LDAP Agent service​

  1. Go to Windows Services and restart the LDAP Agent.
  2. Return to SecureAuth IAM and check the status of the Active Directory connection. Check Active Directory status in list Check Active Directory status in edit mode
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 IAM, 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.

Docker installation

  1. Pull the Docker image:

    docker pull secureauth/ldap-agent:latest

  2. Run the container:

    docker run -d \
      --name secureauth-ldap-agent \
      --restart unless-stopped \
      -v /path/to/config:/etc/secureauth/ldap-agent \
      secureauth/ldap-agent:latest

LDAP Agent configuration​

Configuration file locations​

Windows

  • Configuration: C:\Program Files\SecureAuth\LDAP Agent\config\agent.conf
  • 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
# Get Agent ID and Shared Secret from your user store connection settings in SecureAuth IAM
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 IAM
Shared SecretSharedSecretALA_SHARED_SECRETAuthentication token from SecureAuth IAM
LDAP URLsLDAPURLsALA_LDAP_URLSArray/comma-separated list of domain controller URLs
Bind UserLDAPBindUserALA_LDAP_BIND_USERService account for directory binding
Bind PasswordLDAPBindPassALA_LDAP_BIND_PASSPassword for the bind user
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 SecureAuth Switchboard service. Default: https://switchboard.acceptto.com
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 for password reset functionality.
Reset Password Bind PassLDAPResetPasswordBindPassALA_LDAP_RESET_PASSWORD_BIND_PASSPassword for the reset password bind user. Required for password reset functionality.
Service management

Windows

# Start the service
net start "SecureAuth LDAP Agent"

# Stop the service
net stop "SecureAuth LDAP Agent"

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

Linux

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

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

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

# Check service status
sudo systemctl status secureauth-ldap-agent
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 secureauth-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: