Introduction
By default, users log in to the Nemo GUI with a username and password stored in the Nemo database. Nemo can instead delegate password verification to an LDAP directory, such as OpenLDAP or Microsoft Active Directory, so that users log in with their corporate credentials.
This document describes how to install, configure, test and troubleshoot the LDAP authentication plugin.
INFO
This document applies to Nemo 4.1 and later. The plugin and its configuration parameters are identical across these versions.
The content is organized as follows:
- How LDAP authentication works
- Prerequisites
- Installation
- Configuration
- Configuration examples
- Nemo user accounts
- Testing
- Troubleshooting
- Security considerations
How LDAP authentication works
LDAP is only used to verify the password. Roles and access rights (elements, pages, charts, ...) are still managed in Nemo, so every LDAP user must also exist as a user in Nemo.
When a user submits the login form, the following steps take place:
- Bind DN computation: the username typed by the user is transformed into an LDAP bind DN (the identity presented to the LDAP server) using a regular expression. For example,
johnbecomesuid=john,ou=People,dc=example,dc=com. - LDAP bind: Nemo connects to the LDAP server and authenticates (binds) with this DN and the password typed by the user.
- Optional search filter: if configured, Nemo performs an LDAP search, using the user's own credentials, to check an additional condition, typically membership of a group. The login is accepted only if the search returns an entry.
- Nemo user lookup: if the LDAP steps succeed, Nemo looks for an active Nemo user whose username is exactly the username typed at login (not the transformed bind DN). This user's role and privileges are applied to the session.
- Fallback to local authentication: if any LDAP step fails, or if no matching active Nemo user is found, Nemo verifies the typed password against the password stored in the Nemo database.
WARNING
The fallback to local authentication is always active. A user can always log in with the password stored in Nemo, including the default administrator account. Read the Security considerations section before going to production.
Other login controls configured in Nemo (multi-factor authentication, maximum number of failed attempts, session timeouts) continue to apply to users authenticated through LDAP.
Prerequisites
- Network connectivity from every Nemo central server running the GUI to the LDAP server, on TCP port 389 (
ldap://) or 636 (ldaps://). - For
ldaps://, the certificate of the CA that signed the LDAP server certificate. See Using ldaps. - The structure of the directory: where user entries are located, which attribute identifies the users (
uid,sAMAccountName,mail, ...) and, if access must be restricted, the DN of the authorized group. - A test LDAP account, ideally both a member and a non-member of the authorized group.
Installation
Perform the following steps with root privileges on every central server running the Nemo GUI.
- Install the OpenLDAP libraries and client tools. The client tools provide
ldapsearch, used for testing.
dnf install -y openldap openldap-clients- Find the Nemo
guipackage directory. The exact path depends on the Python version embedded in Nemo:
/opt/nemo/bin/python -c "import os, nemo; print(os.path.join(os.path.dirname(nemo.__file__), 'gui'))"Example output:
/opt/nemo/lib/python3.9/site-packages/nemo/gui- Copy the file
AuthenticationBackEndPlugin.pyinto this directory, and make sure it is readable by the user running the Nemo processes:
cp AuthenticationBackEndPlugin.py /opt/nemo/lib/python3.9/site-packages/nemo/gui/
chmod 644 /opt/nemo/lib/python3.9/site-packages/nemo/gui/AuthenticationBackEndPlugin.pyAdd the
[GUI.LDAP]section to/opt/nemo/etc/global.conf, as described in Configuration.Restart Nemo so that the GUI loads the plugin:
systemctl restart nemoINFO
The plugin is only loaded when the GUI starts, so installing or replacing the file requires a restart. The parameters of the [GUI.LDAP] section, on the other hand, are read again at every login attempt: changing them does not require a restart.
WARNING
The plugin file is not part of the Nemo package. After every Nemo upgrade, check that the file is still present in the gui directory (whose path changes if the embedded Python version changes) and copy it again if needed.
Configuration
The plugin is configured in the section [GUI.LDAP] of /opt/nemo/etc/global.conf on every central server running the GUI.
Parameters
| Parameter | Required | Description |
|---|---|---|
| urlLDAP | yes | URL of the LDAP server, in the format scheme://host[:port], where scheme is ldap or ldaps. Several URLs separated by a space can be given for redundancy; they are tried in order. |
| usernameMatch | no | Regular expression applied to the username typed at login, to compute the bind DN. |
| usernameSubstitution | no | Replacement string producing the bind DN. Groups captured by usernameMatch are referenced with \1, \2, ... |
| usernameFilterBaseDN | no | Base DN from which the optional search is performed (the whole subtree is searched). |
| usernameFilterMatch | no | Regular expression applied to the username typed at login, to compute the search filter. |
| usernameFilterSubstitution | no | Replacement string producing the LDAP search filter. Groups captured by usernameFilterMatch are referenced with \1, \2, ... |
Parameters work in groups:
- If
urlLDAPis missing, LDAP authentication is skipped and only local authentication is used. usernameMatchandusernameSubstitutionmust be set together. If they are missing, the username typed at login is sent as-is as bind DN. This works with Active Directory if users type their fulluser@domainname.usernameFilterBaseDN,usernameFilterMatchandusernameFilterSubstitutionmust be set together. If they are missing, a successful bind is enough to accept the login.
Writing regular expressions
The bind DN is computed by replacing the part of the username matched by usernameMatch with usernameSubstitution. The search filter is computed the same way, with usernameFilterMatch and usernameFilterSubstitution.
WARNING
Always anchor the regular expressions with ^ and $. Depending on the Python version embedded in Nemo, the unanchored expression (.*) can match twice and produce an invalid result such as uid=john,ou=People,dc=example,dc=comuid=,ou=People,dc=example,dc=com. Use ^(.*)$ instead.
If the username does not match the expression, it is used unchanged. This can be used to accept only a specific format: for example, with usernameMatch=^([^@]+)@example\.com$, a username that is not an @example.com address is sent unchanged as bind DN and the bind fails.
Syntax rules for global.conf
- Write filters with a plain
&character, for example(&(uid=\1)(memberOf=...)). Do not use the HTML entity&: it would be sent literally to the LDAP server and the filter would be invalid. - Write back-references as
\1, without extra escaping. - The
%character has a special meaning inglobal.conf. If a value contains%, write it as%%. - Do not put quotes around values: they would be part of the value.
Using ldaps
ldaps:// is strongly recommended, because with ldap:// the passwords are sent in clear text over the network. StartTLS on port 389 is not supported by the plugin.
With ldaps://, the server certificate is verified using the OpenLDAP client configuration of the operating system. To trust the CA that signed the LDAP server certificate:
- Copy the CA certificate (PEM format) and add it to the system trust store:
cp ldap-ca.pem /etc/pki/ca-trust/source/anchors/
update-ca-trust- Make sure
/etc/openldap/ldap.confpoints to the system CA bundle:
TLS_CACERT /etc/pki/tls/certs/ca-bundle.crtVerify with
ldapsearch, as described in Testing. Nemo uses the same OpenLDAP libraries: ifldapsearchworks overldaps://, Nemo will too.Restart Nemo (
systemctl restart nemo) so that the GUI picks up the new OpenLDAP configuration.
TIP
By default, there is no timeout on the connection to the LDAP server: if the server is unreachable, the login page waits until the operating system gives up. To fail faster, and move to the next server when several URLs are configured, add a timeout in seconds to /etc/openldap/ldap.conf, then restart Nemo:
NETWORK_TIMEOUT 5Configuration examples
The examples below use example.com placeholders. Adapt the host names, DNs, attribute names and group names to the target directory.
OpenLDAP, login with uid
Users log in with their uid (for example john); any user with valid credentials is accepted.
[GUI.LDAP]
urlLDAP=ldaps://ldap.example.com
usernameMatch=^(.*)$
usernameSubstitution=uid=\1,ou=People,dc=example,dc=comLogin john → bind DN uid=john,ou=People,dc=example,dc=com.
OpenLDAP, restricted to a group
Same as above, but only members of the group nemo-users are accepted.
[GUI.LDAP]
urlLDAP=ldaps://ldap.example.com
usernameMatch=^(.*)$
usernameSubstitution=uid=\1,ou=People,dc=example,dc=com
usernameFilterBaseDN=ou=People,dc=example,dc=com
usernameFilterMatch=^(.*)$
usernameFilterSubstitution=(&(uid=\1)(memberOf=cn=nemo-users,ou=Groups,dc=example,dc=com))INFO
On OpenLDAP, the memberOf attribute is only available if the memberof overlay is enabled on the server. The users must also have read access to their own entry, including the memberOf attribute, because the search is performed with their own credentials.
Active Directory, login with short username, restricted to a group
Users log in with their short account name (for example john); Active Directory accepts the user principal name john@corp.example.com as bind DN. Only members of the group Nemo Users are accepted.
[GUI.LDAP]
urlLDAP=ldaps://dc01.corp.example.com ldaps://dc02.corp.example.com
usernameMatch=^(.*)$
usernameSubstitution=\1@corp.example.com
usernameFilterBaseDN=OU=Staff,DC=corp,DC=example,DC=com
usernameFilterMatch=^(.*)$
usernameFilterSubstitution=(&(sAMAccountName=\1)(memberOf=CN=Nemo Users,OU=Groups,DC=corp,DC=example,DC=com))TIP
- In Active Directory,
memberOfonly lists direct group memberships. To also accept members of nested groups, use the matching ruleLDAP_MATCHING_RULE_IN_CHAIN:(&(sAMAccountName=\1)(memberOf:1.2.840.113556.1.4.1941:=CN=Nemo Users,OU=Groups,DC=corp,DC=example,DC=com)). - Use the narrowest possible
usernameFilterBaseDN(the OU containing the users) rather than the domain root, to avoid referrals to other partitions of the directory.
Login with an e-mail address
Users log in with their e-mail address (for example john@example.com), while the directory identifies them by uid (john). Only @example.com addresses are transformed.
[GUI.LDAP]
urlLDAP=ldaps://ldap.example.com
usernameMatch=^([^@]+)@example\.com$
usernameSubstitution=uid=\1,ou=People,dc=example,dc=comLogin john@example.com → bind DN uid=john,ou=People,dc=example,dc=com. The corresponding Nemo user must be named john@example.com, which is the username typed at login.
Nemo user accounts
For each LDAP user allowed to log in, create a user in Nemo (see Settings Module > Users in the User Guide), with the following settings:
- Username: exactly the username the user types at login, not the bind DN. The comparison is case-sensitive:
Johnandjohnare different users. - Role: the role granting the required access rights.
- Password: a long random password that is not communicated to the user. Because of the fallback to local authentication, this password also allows logging in, so it must not be guessable. Do not ask LDAP users to change their password in Nemo: this would only change the local fallback password, not the LDAP one.
- Active: inactive users cannot log in, neither through LDAP nor locally.
To revoke access of a user, deactivate or delete the user in Nemo. Disabling the account in LDAP only is not sufficient if the local password is known.
Testing
Test in the order below: each step isolates a different layer, which makes troubleshooting easier.
Step 1: test the directory with ldapsearch
From the Nemo central server, bind with the test user's bind DN and run the same search as the one configured in Nemo. Replace the values with the ones from the configuration; -W prompts for the password.
ldapsearch -H ldaps://ldap.example.com -x \
-D "uid=john,ou=People,dc=example,dc=com" -W \
-b "ou=People,dc=example,dc=com" \
"(&(uid=john)(memberOf=cn=nemo-users,ou=Groups,dc=example,dc=com))" dnA successful test returns the DN of the user entry, for example dn: uid=john,ou=People,dc=example,dc=com. An empty result means that the user does not match the filter, for example because they are not a member of the group.
Step 2: test the plugin from the command line
The plugin can be run directly. It reads the [GUI.LDAP] section of global.conf and prints each step. To avoid leaving the password in the shell history, read it into a variable first:
read -rs LDAPPW
/opt/nemo/bin/python /opt/nemo/lib/python3.9/site-packages/nemo/gui/AuthenticationBackEndPlugin.py john "$LDAPPW"
unset LDAPPWExample output for a successful test:
LDAP authentication: username john -> bind DN uid=john,ou=People,dc=example,dc=com
LDAP authentication to ldaps://ldap.example.com - bind with uid=john,ou=People,dc=example,dc=com for username john attempted
LDAP authentication to ldaps://ldap.example.com - bind with uid=john,ou=People,dc=example,dc=com for username john successful
LDAP authentication to ldaps://ldap.example.com - filter (&(uid=john)(memberOf=cn=nemo-users,ou=Groups,dc=example,dc=com)) on base DN ou=People,dc=example,dc=com for username john attempted
LDAP authentication to ldaps://ldap.example.com - filter (&(uid=john)(memberOf=cn=nemo-users,ou=Groups,dc=example,dc=com)) on base DN ou=People,dc=example,dc=com for username john result: successful
result: Trueresult: False means that the LDAP authentication failed; the lines above it, followed by an error trace, show at which step.
Step 3: test the login in the GUI
- Make sure the GUI log level is set to
10(debug), in the GUI settings (see Configure the GUI in the User Guide). - Follow the GUI log on the central server:
tail -f /var/log/nemo/gui.log | grep AUTHBE- Log in to the GUI with the test user and their LDAP password. The log shows the same messages as in step 2, prefixed with
[AUTHBE], followed by the Nemo user lookup:
2026-11-19 10:15:02,118-29455-DEBUG-[AUTHBE] LDAP authentication to ldaps://ldap.example.com - bind with uid=john,ou=People,dc=example,dc=com for username john successful
...
2026-11-19 10:15:02,131-29455-DEBUG-[AUTHBE] user found: {'username': 'john', ...}- Repeat with a user who is not a member of the authorized group, and check that the login is refused.
- Set the log level back to its previous value: debug logs contain usernames and directory information.
Troubleshooting
| Symptom | Probable cause and resolution |
|---|---|
No LDAP message at all in gui.log | The plugin is not installed in the right directory, Nemo was not restarted after installing it, or the GUI log level is higher than 10. |
LDAP parameters missing from configuration | The [GUI.LDAP] section or the urlLDAP parameter is missing or misspelled. Section names are case-sensitive. |
The bind DN shown in the log looks duplicated, for example ...dc=comuid=,ou=People,... | Unanchored regular expression. Use ^(.*)$ instead of (.*). See Writing regular expressions. |
INVALID_CREDENTIALS in the error trace | Wrong password, or wrong bind DN. Check the username ... -> bind DN ... line and compare it with the DN of the user in the directory, using ldapsearch. |
SERVER_DOWN / Can't contact LDAP server | Network or firewall issue, wrong host or port, or, with ldaps://, the server certificate is not trusted (the trace then mentions the certificate). See Using ldaps. |
FILTER_ERROR / Bad search filter | Invalid filter syntax: unbalanced parentheses, or & instead of &. |
Filter result: failed | The user does not match the filter: not a member of the group, memberOf not available on the server, or the user is not allowed to read their own entry. Run the same search with ldapsearch. |
| LDAP authentication successful, but login refused | No active Nemo user with exactly the username typed at login. See Nemo user accounts. |
| Login refused with an error page right after the bind DN computation | Invalid regular expression in usernameMatch or usernameFilterMatch. Test it with the command-line test. |
| Login page very slow before failing | The LDAP server is unreachable. Configure NETWORK_TIMEOUT (see Using ldaps) and check connectivity. |
| User can log in with a wrong LDAP password | The typed password matches the local password stored in Nemo (fallback to local authentication). Set a long random local password. |
Security considerations
- Local fallback: local passwords always remain valid. Change the passwords of all built-in and local accounts, including the default administrator account, to strong values. Keep at least one local administrator account with a strong password: it is the only way to access Nemo if the LDAP server is unavailable.
- Revocation: removing a user from LDAP, or from the authorized group, prevents LDAP logins but not logins with the local password. Deactivate the user in Nemo as well.
- Encryption: use
ldaps://. Withldap://, passwords are sent in clear text between Nemo and the LDAP server. - Access restriction: without a search filter, every account in the directory that can bind successfully and has a matching Nemo user can log in. Use a group filter to restrict access explicitly.
- Logs: at debug level,
gui.logcontains usernames, bind DNs and search filters. Lower the log level once the configuration has been validated.
