LDAP authentication

This page applies to:

HAProxy ALOHA - all versions

System administrators can authenticate to HAProxy ALOHA with a user account defined in an external LDAP server, such as Active Directory Domain Services. You can give each user either administrative access (read/write access) or monitoring access (read-only).

ldap architecture

Caution

You’re about to modify how users can log in to HAProxy ALOHA. Before proceeding, connect to the HAProxy ALOHA appliance through SSH, or launch a terminal from the web UI’s Tools tab to avoid being locked out. If you become locked out, restart HAProxy ALOHA to reset your settings.

Prerequisites Jump to heading

Please check that you’ve met the following prerequisites:

You’re running Windows Server 2008 or later.
Your Windows Server has the Active Directory Domain Services role and has created an Active Directory forest. See the Windows Server guide Install Active Directory Domain Services.
Optional: If you plan to use Windows Server as a DNS server, add the DNS Server role. See the Windows Server guide Installing DNS Server.

Enable LDAP authentication Jump to heading

HAProxy ALOHA must be able to query the Active Directory DNS server. From the Services tab, click system setup.

Enter the name of your AD Domain, and the IP address of the corresponding DNS server.

Option	Description
`dns_domain`	Name of your AD Domain
`dns_servers`	IP address of the AD DNS

haproxy
service system
  hostname ALOHA1
  rtc utc
  dns_domain mydomain.com
  dns_servers 192.168.1.65

haproxy
service system
  hostname ALOHA1
  rtc utc
  dns_domain mydomain.com
  dns_servers 192.168.1.65

Click OK, then Close.

You can also launch the following commands from a terminal:

nix
sudo config set system dns_domain mydomain.com
sudo config set system dns_servers 192.168.1.65

nix
sudo config set system dns_domain mydomain.com
sudo config set system dns_servers 192.168.1.65

From the Setup tab, click Save. Then, click Reboot.
To verify that HAProxy ALOHA can communicate with the DNS server, launch a terminal from the web UI’s Tools tab or SSH to your HAProxy ALOHA appliance. Then, query for a DNS hostname within your domain. Here, we call nslookup to query for the DNS domain dc1.mydomain.com:
```
nix
nslookup dc1.mydomain.com
```
```
nix
nslookup dc1.mydomain.com
```
```
output
text
Server:  192.168.1.65
Address: 192.168.1.65:53
```
```
output
text
Server:  192.168.1.65
Address: 192.168.1.65:53
```
To add LDAP support, go to the Services tab and click pam setup.
Add ldap_auth 1 to the PAM service.
```
haproxy
service pam
  autostart
  ldap_auth 1
```
```
haproxy
service pam
  autostart
  ldap_auth 1
```
Tip

To get more verbose logs for easier troubleshooting, specify debug 1 as well.
Click OK, then Close.
Apply your changes to the PAM configuration.

Restart the PAM service.

restart service pam

You can also launch the following commands from a terminal:

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

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

Create a user account in Active Directory that HAProxy ALOHA will use to connect to the credentials store. If possible, this user should have a password that never expires to avoid any service disruptions. For example, create a user with the account name alohalogin.
The HAProxy ALOHA nslcd daemon queries LDAP based on the nslcd.conf configuration file. From the Services tab, click nslcd setup.
Allow the nslcd daemon to start automatically by adding autostart.
```
haproxy
service nslcd
  autostart
```
```
haproxy
service nslcd
  autostart
```
Click OK, then Close.

You can also invoke the following command from a terminal:
```
nix
sudo config set nslcd autostart
```
```
nix
sudo config set nslcd autostart
```
In the Services tab, click the [advanced mode] link, then edit the nslcd configuration.

The content of the /etc/nslcd.conf NTP configuration file displays.

Make the following changes:

Set the uri directive to the address of your LDAP server. For example:

nslcd.conf
text
uri ldap://dc1.mydomain.com/

nslcd.conf
text
uri ldap://dc1.mydomain.com/

Set the distinguished name of the search base. For example:

nslcd.conf
text
base dc=mydomain,dc=com

nslcd.conf
text
base dc=mydomain,dc=com

Set the distinguished name to bind to the server with. For example:

nslcd.conf
text
binddn cn=alohalogin,cn=Users,dc=mydomain,dc=com

nslcd.conf
text
binddn cn=alohalogin,cn=Users,dc=mydomain,dc=com

On Windows Server, you can use the dquery command to get the value:

powershell
PS C:\Users\admin> dsquery user -samid 'alohalogin'

powershell
PS C:\Users\admin> dsquery user -samid 'alohalogin'

output
text
"CN=alohalogin,CN=Users,DC=mydomain,DC=com"

output
text
"CN=alohalogin,CN=Users,DC=mydomain,DC=com"

Set the credentials to bind with. For example:

nslcd.conf
text
bindpw mypassword

nslcd.conf
text
bindpw mypassword

Uncomment the mappings section for your LDAP server. For Active Directory, it looks like the example below. Replace DOMAIN_SID with the DomainSID value you get from running the Get-ADDomain PowerShell command on your Windows Server.

nslcd.conf
text
# Alternative mappings for Active Directory
# (replace the SIDs in the objectSid mappings with the value for your domain)
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

nslcd.conf
text
# Alternative mappings for Active Directory
# (replace the SIDs in the objectSid mappings with the value for your domain)
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

Important

Enter a newline at the end of the configuration.

Tip

Other changes you can make to the nslcd.conf file:

To log nslcd actions to syslog, specify log syslog.
To ensure that nslcd doesn’t fail at startup when the LDAP server is down, specify the AD search base (for example, base dc=mydomain,dc=com).
To minimize latency when a user uses sudo and the LDAP server is offline, specify nss_initgroups_ignoreusers root,admin,monitor.

Apply your changes to the nslcd service. Then, restart the nslcd service.

Verify that HAProxy ALOHA can connect to the LDAP server by testing the connection with the ldapsearch command. This command will prompt you to enter the user’s password. Use these options:

Option	Description
`-x`	Use simple authentication.
`-h`	URI referring to the LDAP server.
`-D`	Distinguished Name used to bind to the LDAP directory.
`-W`	Prompt for password.
`-b`	AD search base.

nix
ldapsearch -x -H ldap://dc1.mydomain.com -D alohalogin@mydomain.com -W -b 'CN=Users,DC=mydomain,DC=com'

nix
ldapsearch -x -H ldap://dc1.mydomain.com -D alohalogin@mydomain.com -W -b 'CN=Users,DC=mydomain,DC=com'

output
text
# extended LDIF
#
# LDAPv3
# base <dc=mydomain,dc=com> with scope subtree
# filter: (objectclass=*)
# requesting: ALL
#
# mydomain.com
dn: DC=mydomain,DC=com
objectClass: top
objectClass: domain
objectClass: domainDNS
distinguishedName: DC=mydomain,DC=com
instanceType: 5
whenCreated: 20211202085814.0Z
...

output
text
# extended LDIF
#
# LDAPv3
# base <dc=mydomain,dc=com> with scope subtree
# filter: (objectclass=*)
# requesting: ALL
#
# mydomain.com
dn: DC=mydomain,DC=com
objectClass: top
objectClass: domain
objectClass: domainDNS
distinguishedName: DC=mydomain,DC=com
instanceType: 5
whenCreated: 20211202085814.0Z
...

If the ldapsearch command fails, check your network configuration.

To make your changes persistent after a reboot, click the Setup tab. Then click Save under Configuration.

The configuration was successfully saved message displays.

You can also launch the following command from a terminal:
```
nix
sudo config save
```
```
nix
sudo config save
```

Set access rights for users Jump to heading

Users can have either monitor (read-only) or admin (read/write) access. To set a user’s access rights:

From the Tools tab, use the file manager to edit the file /etc/security/users.conf. Add users that have an account on the LDAP server, specifying the following for each:

Option	Description
`user`	Set the Active Directory user account name.
`auth_type`	Set to `ldap`.
`service`	Set to one or more of these values: `wui` (web UI), `sshd` (SSH), or `login` (console). This restricts how a user can log in.
`allow` or `deny`	Enable or disable the user’s login.
`map_to_user`	Set `admin` for read/write access or `monitor` for read-only access.

Here are a few examples.

users.conf
user=bob    auth_type=ldap  service=wui,sshd : allow  map_to_user admin
user=carol  auth_type=ldap  service=wui      : allow  map_to_user admin
user=dave   auth_type=ldap  service=wui      : allow  map_to_user monitor

:deny

users.conf
user=bob    auth_type=ldap  service=wui,sshd : allow  map_to_user admin
user=carol  auth_type=ldap  service=wui      : allow  map_to_user admin
user=dave   auth_type=ldap  service=wui      : allow  map_to_user monitor

:deny

You can also allow access to all users in an AD group. Here, we give admin access to all users in the AD group aloha-admins. We give monitor access to all users in the AD group aloha-readonly.

users.conf
text
group=aloha-admins    auth_type=ldap  : allow map_to_user admin
group=aloha-readonly  auth_type=ldap  : allow map_to_user monitor
:deny

users.conf
text
group=aloha-admins    auth_type=ldap  : allow map_to_user admin
group=aloha-readonly  auth_type=ldap  : allow map_to_user monitor
:deny

Set :deny as the last entry in the file. HAProxy ALOHA evaluates entries from top to bottom. All entries after :deny will be ignored.

To make your changes persistent after a reboot, click the Setup tab. Then click Save under Configuration.

The configuration was successfully saved message displays.

You can also launch the following command from a terminal:
```
nix
sudo config save
```
```
nix
sudo config save
```
You can now sign in to HAProxy ALOHA with your Active Directory credentials. For example, with username bob and password bobs-password.

Test your configuration Jump to heading

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

Check that your configuration is parsed correctly:

nix
sudo test_pam_user_map check_config -f /etc/security/users.conf

nix
sudo test_pam_user_map check_config -f /etc/security/users.conf

output
Checking config file /etc/security/users.conf
Config file /etc/security/users.conf parsed successfully

output
Checking config file /etc/security/users.conf
Config file /etc/security/users.conf parsed successfully

Simulate a local user logging in through ssh:

nix
sudo test_pam_user_map check_pam_auth -f /etc/security/users.conf check_config -u bob -s sshd -t ldap

nix
sudo test_pam_user_map check_pam_auth -f /etc/security/users.conf check_config -u bob -s sshd -t ldap

output
text
Checking PAM access for user bob
Result: auth_type=ldap allow=1 matched=1 map_to_user=admin
PAM: access granted

output
text
Checking PAM access for user bob
Result: auth_type=ldap allow=1 matched=1 map_to_user=admin
PAM: access granted

Test your LDAP configuration with a real user and a real password:

nix
sudo test_pam_user_map check_login_pass -f /etc/security/users.conf -u bob -p bobs-password -s sshd -t ldap

nix
sudo test_pam_user_map check_login_pass -f /etc/security/users.conf -u bob -p bobs-password -s sshd -t ldap

output
text
Validating user=bob password=*** service=sshd
PAM user has been set to admin
user/password validated successfully

output
text
Validating user=bob password=*** service=sshd
PAM user has been set to admin
user/password validated successfully

To troubleshoot errors, launch nslcd in debug mode in an HAProxy ALOHA terminal:

nix
sudo service nslcd stop
sudo nslcd -d -n

nix
sudo service nslcd stop
sudo nslcd -d -n

Then, in a separate terminal, try the failed command again.

Enable LDAP over SSL Jump to heading

You can enable LDAP over SSL (LDAPS) to secure the communication between the LDAP server and HAProxy ALOHA. You’ll need an SSL/TLS server certificate, which you can import into the LDAP server.

For information on how to export and import a certificate on Windows Server, see the guide Exporting the LDAPS Certificate and Importing for use with AD DS. We’ll outline the steps here. We assume you already have an SSL/TLS server certificate that has a common name (CN field) matching your Windows Server hostname.

Create a test certificate

For creating a test certificate, try minica. Then, to convert a .pem file to .pfx, use this openssl command:

nix
openssl pkcs12 -inkey key.pem -in cert.pem -export -out ldaps.pfx

nix
openssl pkcs12 -inkey key.pem -in cert.pem -export -out ldaps.pfx

On your Windows Server AD domain controller:

From a PowerShell terminal, run mmc. This opens a Management Console window.
In the Management Console window, click File > Add/Remove Snap-in.
Add Certificates. For the certificates to manage, select Service account.
Choose the computer to manage. If you’re on the Active Directory domain controller, choose the local computer.
For the service account to manage, select Active Directory Domain Services, then click Finish.
On the Add or Remove Snap-ins dialog box, click OK.
Expand Certificates - Services (Active Directory Domain Services), then click NTDS\Personal.
Right-click NTDS\Personal, click All Tasks, and then click Import.
Browse to and import your SSL/TLS server certificate and key file (.pfx) into the NTDS/Personal store.

Active Directory is now configured for LDAP over SSL.

On HAProxy ALOHA:

If your HAProxy ALOHA host is a virtual appliance instead of hardware, you need to create an additional partition large enough to contain the files.
- Attach a new hard disk to the virtual machine. It should be 30 GB or larger. See the documentation for your hypervisor or cloud service.
- Power on your HAProxy ALOHA Virtual Appliance.
- Log in to your HAProxy ALOHA web UI as an administrator. The web UI runs at port 4444.
- Select the Tools tab, then edit the file /etc/config.rc through the File Manager. Add the following directives at the end of the service system section, then click Save:
```
text
app_auto_mount
app_auto_format
app_device_size 30000000000
```
```
text
app_auto_mount
app_auto_format
app_device_size 30000000000
```
  where:
  - app_auto_mount automatically mounts the partition on /app.
  - app_auto_format automatically formats the /app partition, if needed.
  - app_device_size <Size in bytes> specifies the size in bytes of the /app partition. Here we set it to 30 GB.
- Select the Setup tab, then click Save to save your modifications.
- Restart HAProxy ALOHA by going to the Setup tab and clicking Reboot.
Launch a terminal from the web UI’s Tools tab.
Add the directory /app/ca and set its owner and group to nobody, which is the user account that the nslcd service runs as. Call chmod with g+s to set the setgid bit so that files added to the directory later will inherit the nobody group.
```
nix
sudo mkdir /app/ca
sudo chown -R nobody:nobody /app/ca
sudo chmod g+s /app/ca
```
```
nix
sudo mkdir /app/ca
sudo chown -R nobody:nobody /app/ca
sudo chmod g+s /app/ca
```
From the Tools tab, use the file explorer to upload the CA certificate file that corresponds to your SSL/TLS server certificate into the /app/ca directory. That will allow HAProxy ALOHA to trust the server certificate. If you’re using minica, this is minica.pem.
In the Services tab, click the [advanced mode] link, then edit the nslcd configuration.

The content of the /etc/nslcd.conf NTP configuration file displays.

Make the following changes:

Change the uri directive to use the ldaps:// scheme.

nslcd.conf
text
uri ldaps://dc1.mydomain.com/

nslcd.conf
text
uri ldaps://dc1.mydomain.com/

Set tls_cacertfile to the file path of your CA .pem file.

nslcd.conf
text
tls_cacertfile /app/ca/<your_CA_pem_file>.pem

nslcd.conf
text
tls_cacertfile /app/ca/<your_CA_pem_file>.pem

Apply your changes to the nslcd service. Then, restart the nslcd service.

Test your LDAP configuration with a real user and a real password:

nix
sudo test_pam_user_map check_login_pass -f /etc/security/users.conf -u bob -p bobs-password -s sshd -t ldap

nix
sudo test_pam_user_map check_login_pass -f /etc/security/users.conf -u bob -p bobs-password -s sshd -t ldap

output
text
Validating user=bob password=*** service=sshd
PAM user has been set to admin
user/password validated successfully

output
text
Validating user=bob password=*** service=sshd
PAM user has been set to admin
user/password validated successfully

To troubleshoot errors, launch nslcd in debug mode in an HAProxy ALOHA terminal:

nix
sudo service nslcd stop
sudo nslcd -d -n

nix
sudo service nslcd stop
sudo nslcd -d -n

Then, in a separate terminal, try the failed command again.

Troubleshooting Jump to heading

If the message # access denied using ssh, allowed when using login, displays, check the following:

The AllowGroups directive is commented out in /etc/ssh/sshd_config.

nix
sudo grep -i AllowGroups /etc/ssh/sshd_config

nix
sudo grep -i AllowGroups /etc/ssh/sshd_config

output
# AllowGroups adm users

output
# AllowGroups adm users

If this directive isn’t commented out, check that your users’ groups are allowed:

nix
sudo getent group

nix
sudo getent group

Check that UsePAM is set to yes in /etc/ssh/sshd_config.

nix
sudo grep UsePAM /etc/ssh/sshd_config

nix
sudo grep UsePAM /etc/ssh/sshd_config

output
UsePAM yes

output
UsePAM yes

Limitations Jump to heading

When using SCP, user remapping doesn’t work.
When using SSH keys, user remapping doesn’t work (but key-based authentication does).
You can’t change the password of an LDAP user using HAProxy ALOHA. If you need to do so, use the tools provided with your LDAP server.

Product Documentation

API Documentation

Configuration Documentation

Virtual appliance

LDAP authentication

Prerequisites Jump to heading

Enable LDAP authentication Jump to heading

Set access rights for users Jump to heading

Test your configuration Jump to heading

Enable LDAP over SSL Jump to heading

Troubleshooting Jump to heading

Limitations Jump to heading

See also Jump to heading

Virtual appliance

Product Documentation

API Documentation

Configuration Documentation

Prerequisites Jump to heading #

Enable LDAP authentication Jump to heading #

Set access rights for users Jump to heading #

Test your configuration Jump to heading #

Enable LDAP over SSL Jump to heading #

Troubleshooting Jump to heading #

Limitations Jump to heading #

See also Jump to heading #

Privacy Settings

Prerequisites Jump to heading

Enable LDAP authentication Jump to heading

Set access rights for users Jump to heading

Test your configuration Jump to heading

Enable LDAP over SSL Jump to heading

Troubleshooting Jump to heading

Limitations Jump to heading

See also Jump to heading