HAProxy Enterprise Documentation 12.5

LDAP Authentication

Historically, the ALOHA has only two built-in users: admin and monitor.

  • The admin user has access to administration and maintenance operations

  • The monitor user can only view the ALOHA configuration and metrics, but is not allowed to make any modification.

With the LDAP authentication feature, you can authenticate users against a remote LDAP server as opposed to a local password database, with the following benefits when compared to traditional Unix authentication:

  • Simple and more centralized user management

  • the admin or monitor passwords no longer have to be shared between several users; each user can have their own set of rights and password

  • Two different admin users can be differentiated in the logs

  • Users can be allowed or denied depending on multiple rules and criteria such as requested service, user group, etc.

  • In the WUI, you are able to see which user is logged in and if the user was remapped

  • In the shell, several environment variables will be set: ALOHA_USER, ALOHA_USER_INFO, ALOHA_USER_MAPPED_AS

However, there are a few inconveniences to take into account:

  • The LDAP server can become a single point of failure, if only LDAP users are enabled to log in

  • Increased risk of lockout

Enabling LDAP authentication


Be sure to follow the procedures precisely: a mistake can lock you out of the ALOHA and require a recovery. We recommend that you keep a root shell open in order to do repairs in case of error.

Configure and enable PAM service


  1. In the Services tab, select "advanced mode" (at the bottom of the page).

  2. Go to the pam line and click setup_icon.

  3. Enable ldap_auth and autostart.

  4. Optional: You can also add debug 1 to add more information to the logs for troubleshooting.

  5. Restart the pam service by clicking on restart_icon.

In the command line

  1. Enter the following commands in your terminal:

    $ sudo config set pam ldap_auth 1
    $ sudo config set pam autostart
    $ sudo service pam restart

Configure and enable the LDAP service


  1. In the Services tab, select "advanced mode" (at the bottom of the page).

  2. Go to the nslcd line and click setup_icon.

  3. Enable autostart.

  4. Go to the nslcd line and click edit_icon.

  5. Adapt the nslcd configuration to your LDAP context. Each LDAP context can be specific, but you can apply the following template for a standard LDAP deployment:

    Example of an Active Directory with a schema level from 2008 to 2016:

    uid nobody
    gid nobody
    log syslog
    nss_initgroups_ignoreusers ALLLOCAL
    # use ldaps prefix for LDAP over SSL
    uri ldap://MYDOMAIN.COM/
    base dc=mydomain,dc=com
    filter passwd (objectClass=posixAccount)
    filter group (objectClass=posixGroup)
    # Example : binddn cn=Bind User,ou=ALOHA,dc=mydomain,dc=com
    # The space character don't need to be escaped
    binddn BIND_USER_DN
    # In order to use LDAP over SSL (first, you have to import your CA file through the Web UI)
    tls_cacertfile /etc/ssl/frontends/AD2008/crt.pem
    pagesize 1000
    referrals off
    idle_timelimit 800
    filter passwd (&(objectClass=user)(objectClass=person)(!(objectClass=computer)))
    map passwd uid sAMAccountName
    map passwd uidNumber objectSid:DOMAIN_SID
    map passwd gidNumber objectSid:DOMAIN_SID
    map passwd homeDirectory "/home/$sAMAccountName"
    map passwd gecos displayName
    map passwd loginShell "/bin/bash"
    filter group (|(objectClass=group)(objectClass=person))
    map group gidNumber objectSid:DOMAIN_SID
    # The DOMAIN_SID can be found by runing the following on the domain controler in a PowerShell terminal: Get-ADDomain
  6. Once the configuration is complete, start the service.

In the command line

  1. Edit the file /etc/nslcd.conf according to your LDAP server configuration (see above for details).

  2. Set up the service to start at boot, and then start it:

    $ sudo config set nslcd autostart
    $ sudo service nslcd start

Enable login for LDAP users

The file /etc/security/users.conf allows you to define users and assign allowed actions.

  1. In the Services tab, select "advanced mode" (at the bottom of the page).

  2. Go to the pam line and click edit_icon to edit the users.conf file using the options described below.

  3. If using the command line, edit the file /etc/security/users.conf.

Each line in the users.conf file contains the following:

  • Multiple filters and actions can be on the same line, and must be separated by a space.

  • You can match filters with multiple values separated by commas. Example: user=user1,user2

  • When the user=*, it matches everything.

  • When there is no filter at all, it will also match everything.

Possible filters

  • user: a user name

  • group: a group name

  • auth_type: defines a specific authentication type. We currently support local or ldap.

  • service: defines a specific PAM service

Possible values for service

  • login: local keyboard or serial login

  • sshd: login via sshd

  • wui: login via WUI (web interface)

ALOHA stops evaluating the rules as soon as a line is matched, and applies the corresponding actions.

Possible actions

  • allow: grants access to the user

  • deny: forbids access to the user

  • map_to_user <NEW_USER>: maps the user to another user

We recommend that you remap users to monitor or admin, but you can remap them to any user present on the ALOHA.

Set up login for LDAP users

In the WUI

  1. In the Services tab, go to the system line and click setup_icon.

  2. Add "dns_domain YOUR_DOMAIN_NAME".

  3. Add "dns_servers DNS_SERVER_IP".

In the command line

  1. Check that your DNS resolution works correctly on the ALOHA. If not, run the commands below:

    $ sudo config set system dns_domain MYDOMAIN
    $ sudo config set system dns_servers xx.xx.xx.xx
    $ sudo save-etc
    $ sudo reboot
  2. Check that the ALOHA can communicate with the LDAP server. You can do a test query using ldapsearch. If there is no communication, check your network configuration.

  3. Enable PAM and LDAP authentication (see above).

  4. Configure nslcd (nss-pam-ldap daemon). For complete nslcd documentation, see https://arthurdejong.org/nss-pam-ldapd/.

  5. Reload the service:

    $ sudo service nslcd restart
  6. Reload the service:

    $ sudo service pam restart
  7. Optionally, you can launch nslcd in debug mode to add information for troubleshooting:

    nslcd -d -n
  8. For better reliability, we recommend the following options:

    • Set log syslog to log nslcd actions to syslog

    • Specify explicitly base dc=exemple,dc=org (according to your LDAP server configuration) to ensure that nslcd does not fail at startup, when the LDAP server is down.

    • Set nss_initgroups_ignoreusers root,admin,monitor to prevent lags when one of these users uses sudo and when the LDAP server is offline.


If nslcd is working correctly, you can see the following:

  • LDAP users: getent passwd

  • Users' LDAP groups (mapped as active directory primary groups): getent group

If these steps fail, please consult the https://arthurdejong.org/nss-pam-ldapd/ documentation.

Now that your LDAP users are known by the system, you can allow them to log in.

Testing your configuration

Before you allow your LDAP users to log in, you should test a PAM configuration before you apply it.

Test a PAM configuration

  1. In your shell, edit a draft file (example: /temp/users.conf).

  2. Check that your configuration is parsed correctly:

    $ sudo test_pam_user_map check_config -f /tmp/users.conf
  3. Simulate a user logging in (example: a local user with a local UNIX account on the ALOHA called 'user1' logging in using the keyboard or the console.)

    $ sudo test_pam_user_map check_pam_auth -f /tmp/users.conf -u user1 -s login -t local
  4. Simulate another local user ('user2') logging in using ssh:

    $ sudo test_pam_user_map check_pam_auth -f /tmp/users.conf check_config -u user2 -s sshd -t ldap
    .. Output::

Test with LDAP users

After you are satisfied with the results, you can now test your LDAP configuration with a real user and a real password:

$ sudo test_pam_user_map check_login_pass -f /tmp/users.conf  -u user3 -p mypassword -s sshd -t ldap


Make sure you wipe your history after running this command.

This command has the same effect as when entering a user login/password with the specified authentication type and service.

Once your checks match your expectations, you can rename /tmp/users.conf to /etc/security/users.conf.


  • When using SCP, user remapping does not work.

  • When using SSH keys, user remapping does not work (but key-based authentication does).

  • You cannot change the password of a LDAP user using the ALOHA. If you need to do so, use the tools provided with your LDAP server.


If you encounter the error message # access denied using ssh, allowed when using login, check the following:

  • You do not have the AllowGroups directive in the file /ect/ssh/sshd_config. If you do, check that your users' groups are allowed using getent group.

  • UsePAM is set to yes