OBSERVE. ANALYZE. ACT.
Support Login

System Management · Version 26.4

LDAP Server

Configure one LDAP login domain with a primary server and optional backups, then test sign-in and verify the failover order.

At a glance
LDAP backup 1 enabled at 192.0.2.11 on port 636, with controls for changing its priority or removing it.
LDAP backup 1 enabled at 192.0.2.11 on port 636, with controls for changing its priority or removing it.
UI Path: System Settings > LDAP Server ID: config_system_auth_ldap
Workflow
  1. Name the login domain and configure its primary server.
  2. Add backup servers in the order the appliance should try them.
  3. Test the enabled endpoints and sign in using the domain name.

All servers in this configuration share one Server Name on the login screen. Each login starts at the primary. If it times out or the appliance cannot reach it, the appliance tries the enabled backups in order. A rejected password ends the attempt. The next login starts at the primary again.

Configure the primary

  1. Sign in as a local administrator and open System Settings → LDAP Server. Keep a local administrator session available while testing.
  2. Turn on Enable LDAP Server and enter Server Name, for example corp_ldap. To add redundancy to an existing domain, keep its current name.
  3. Enter the primary address, select LDAP Service Protocol, and set LDAP or LDAPS Service Port. Use port 389 for LDAP or LDAP with StartTLS, or 636 for LDAPS, unless your directory uses a different port. Changing the protocol leaves the port value in place. For TLS, enable Verify Server Certificate to check the server identity and trust chain on every connection.
  4. Set Base DN, the username attribute (for example, uid), and the group ID attribute (for example, gidNumber). Configure the corresponding local group mapping. To assign a fallback when the directory supplies no numeric group ID, turn on Enable Default Group and choose Default User Group Name.

Add and test backup servers

  1. Under Backup Servers, select Add backup server. Enter the backup address and confirm its port. A new backup is enabled and starts with the primary’s port. The replica shares the primary’s LDAP protocol, certificate verification, base DN, username attributes, and group mapping.
  2. Add any additional backups. Backup 1 is the first choice after the primary. Use Move up or Move down to change the order. Turn off Enable backup 1 to skip that entry while retaining its settings and position. Remove deletes the selected backup.
  3. Under Auth. Server Test, enter a test username and password, then select Test and Apply. With the domain enabled, the appliance tests the primary and each enabled backup independently. It saves the settings when every tested endpoint accepts the credentials. Test credentials are used once and are cleared afterward. Leave the test username empty to save without a login test.
  4. Open a fresh login session, select the same Server Name, and sign in. Use the same login name format that the directory accepts. For example, if Base DN is dc=example,dc=org, an account can sign in as uid=9ops.infra,ou=people,dc=example,dc=org. With uid as the username attribute, its session name is 9ops.infra.

Configure from the CLI

This example sets 192.0.2.10 as primary and 192.0.2.11 as the first backup. For this LDAPS example, substitute your directory base DN and use server addresses covered by the certificates. The example assumes a local group mapping for the directory GID.

config system auth ldap enable true name corp_ldap ip 192.0.2.10 port 636 protocol ldaps verify_server_certificate true base_dn dc=example,dc=org username_attr uid gid_attr gidNumber
config system auth ldap backup 1 ip 192.0.2.11 port 636 enable true
show system auth ldap
show system auth ldap backup

Use the next consecutive position to add a backup. Editing an existing position preserves omitted fields. For example, to pause and later re-enable backup 1 during maintenance, run the first command before maintenance and the second afterward.

config system auth ldap backup 1 enable false
config system auth ldap backup 1 enable true
Task Command
List domain settings and available fields config system auth ldap ?
List the available backup fields config system auth ldap backup 1 ?
Change only the first backup’s address config system auth ldap backup 1 ip 192.0.2.12
Move an existing second backup ahead of the first config system auth ldap backup 2 move 1
Remove the backup currently in position 2 config system auth ldap backup 2 remove
Disable the whole login domain and retain its settings config system auth ldap enable false

Moving or removing an entry renumbers the list. Check show system auth ldap backup before making another numbered edit. Before changing an endpoint, record its address, port, position, and the shared directory and TLS settings.

Field reference

CLI Field UI Field Type Or Values Notes
enable Enable LDAP Server Boolean Enables or disables LDAP authentication.
name Server Name String Domain name users select at login.
ip Server IP Address IP address or host string LDAP server address.
port LDAP or LDAPS Service Port Integer from 1 to 65535 Common values are 389 for LDAP and StartTLS, 636 for LDAPS.
protocol LDAP Service Protocol ldap, ldap_with_starttls, or ldaps Selects plain LDAP, StartTLS, or LDAPS.
verify_server_certificate Verify Server Certificate Boolean Verify the TLS certificate and server identity against trusted CAs.
base_dn Base DN String Directory search base, such as DC=example,DC=com.
username_attr Attr. Name for POSIX User Name String Attribute list used to identify the user name.
gid_attr Attr. Name for User Group ID String Attribute list used to identify the LDAP group ID.
default_group_enable Enable Default Group Boolean Allows fallback to a local group.
default_group_name Default User Group Name Existing local user group Used when LDAP group ID mapping does not find a local group.
backup Backup Servers Ordered list Numbered from 1 in failover order.
test_username Username for Test (Empty to skip) String Used only for this test.
test_password Password for Test User Password string Used only for this test.

Troubleshooting

  • An endpoint fails Test and Apply. Check the address and port reported for that endpoint. Verify its directory settings and test the same user DN and password on that replica.
  • A login stops at the primary. Check whether the primary rejected the credentials. Failover handles connection failures and timeouts. All enabled endpoints share a ten-second login deadline. A certificate verification error also ends an LDAP login. Check the certificate name and trust chain on the affected replica.
  • Login succeeds with unexpected permissions. Check the directory group ID and its mapping to a local group. If no numeric ID is available, review the default-group setting.