LDAP Authentication
LDAP authentication
The LDAP authenticator lets people sign in to MQTT with the account they already have in OpenLDAP or Active Directory. It does two things and only two: it verifies the password against the directory, and it reads which directory groups the account belongs to. What those groups may publish or subscribe to is decided by XMQ, on thePermissions page — the directory never holds a topic policy.
The library is optional: it is built where OpenLDAP development headers are installed, and an installation that does not need it simply has no xmq_ldap entry in its extension configuration. Loading it, and the settings that go with it, is described on the Extensions page.
The library's companion .ui.json file organizes the form into connection, lookup, groups and cache sections. Choosing a directory profile fills its settings; account-state details are hidden when the check is disabled, without discarding their values. Nothing is saved until Apply. If the form description is unavailable or incompatible, the ordinary settings form remains usable.
Directory users and the ldap/ namespace
A client signs in as ldap/alice: the prefix, a slash, then the directory login. The prefix is a setting (username_prefix), it defaults toldap/, and it must not be empty.
The prefix exists so that a directory account and a local account can never be confused by accident. A local account named admin keeps working when the directory is unreachable — it is the way back in — while ldap/alice is only ever answered by the directory. A username without the prefix is not handled by this extension at all: the broker passes it to the remaining authenticators and finally to its own accounts, so a directory outage cannot lock out the local administrator.
Directory accounts are not copied into the accounts database. They do not appear on the Users page, they have no local password, and there is nothing to keep in sync. Reserve the prefix for the directory: do not create local accounts whose name starts with ldap/.
| Client sends | Answered by |
|---|---|
ldap/alice + directory password | The directory. Group membership is read here too. |
admin + local password | The broker's own accounts, as before. |
alice without a prefix | The broker's own accounts — so it fails unless such a local account exists. |
Directory groups to XMQ groups
Group membership is mapped explicitly, one directory group at a time, in the extension's group_mappings setting: the distinguished name of the directory group, then =>, then the name of an existing XMQ group.
group_mappings: cn=mqtt-publishers,ou=groups,dc=example,dc=org => Publishers cn=Server Monitoring,dc=example,dc=org => Server Monitoring
In the JSON configuration file each line is separated by \n. Create the XMQ group first, on the Groups page; the name must match exactly. Up to 64 mappings are allowed.
After the password has been verified, each mapped group is searched at its own distinguished name with group_filter. The default,(member={dn}), matches a groupOfNames entry holding the user's DN. Use (uniqueMember={dn}) forgroupOfUniqueNames, or (memberUid={username}) forposixGroup. Only direct membership is read: a group nested inside another group does not confer its rights.
A user may be mapped into several XMQ groups; all of their rules then apply, with the usual rule order and deny precedence. Local group membership of a local account with a similar name is never merged in.
Directory identities are an allow-list by construction: if a user is in no mapped group, or the mapped groups have no rule covering the topic, the answer is deny — even when the ordinary default-deny setting is off. Per-user subjects (user:<name>) do not apply to directory users today; write their policies on the mapped group, or as a pattern rule.
A worked example
Directory group cn=Server Monitoring,ou=groups,dc=example,dc=org holds Alice and Bob, and is mapped to the XMQ group Server Monitoring. On the Permissions page that group gets two rules:
| Action | Topic filter |
|---|---|
publish | brokers/thinker10 |
subscribe | brokers/thinker10 |
Bob connects as ldap/bob and subscribes tobrokers/thinker10; Alice connects as ldap/alice and publishes to it. Bob receives the message. A subscription to brokers/# is refused, because a filter wider than the rule is not covered by it — give the group a rule with that filter if the wider subscription is intended. A refusal is written to the broker's log, naming the username and the filter.
How soon XMQ sees a change
A verified login and the groups read for it are cached forcache_ttl_seconds (default 60), so a reconnect inside that window costs no directory round trip. Refusals are cached separately and only fornegative_cache_ttl_seconds (default 10). Set the positive lifetime to0 to check the directory on every CONNECT; that is the setting to choose when a revoked password must stop working immediately.
| Change | Reaches clients |
|---|---|
| Password changed in the directory | A login that presents the new password is checked with the directory at once. The previous password keeps matching a cached decision until that decision expires — within one cache_ttl_seconds. A session already connected stays connected until it disconnects or is closed. |
| Account disabled in the directory | When the cached decision expires — within one cache_ttl_seconds. The directory refuses the bind of a disabled account itself, so the wait is the cache lifetime, not a policy mistake. |
| Account added to, or removed from, a mapped directory group | At the next CONNECT, or within one cache_ttl_seconds. An existing session keeps the groups it connected with. |
| Permission rules for a mapped XMQ group edited on the Permissions page | Immediately, including sessions already connected. |
| Mapped XMQ group deleted, or its name changed | Immediately: the mapping no longer names an existing group, and the identity is denied until the mapping is corrected. |
| Extension settings: URI, search base, filter, mappings | When saved on the Extensions page — the running extension applies them without a restart. Invalid settings are refused and the previous ones stay. |
| Directory unreachable, certificate expired, service account refused | New ldap/ connections are refused while it lasts, except identities admitted before the outage and still inside their cache lifetime. Sessions already connected continue, and local accounts are unaffected. |
An outage is never cached, so it can never turn into a remembered allow or a remembered refusal. Cache keys are built from the username and a keyed hash of the password under a per-process salt: the password itself is not kept, a login presenting a different password is a different key and is checked with the directory at once, and a restart shares no keys with the previous process. Reloading the extension settings clears the cache.
The cache cannot see that the directory changed its answer; the lifetime is what bounds that. A password revoked or an account disabled at the directory keeps working until the entry expires, at most one cache_ttl_seconds, which is why0 is the setting for a directory whose answers must apply immediately.
The cost can be measured rather than guessed: the test stand shipped with the extension has a benchmark mode that connects 1000 distinct directory users once each at a fixed concurrency, reports CONNECT/s, and repeats the round. A cold round pays for every directory operation; the second is served from the cache. On the development host that was 794 → 13 549 CONNECT/s, while with the cache switched off both rounds stayed near 815–833. On the Windows Server stand, where a directory round trip is cheaper, 500 CONNECTs at concurrency 8 went from 3 445 to 11 071 CONNECT/s. Seeextension/ldap/README.md in the source tree.
Active Directory
The quickest way is to choose Active Directory as the directory type: the profile that belongs with it is filled in at once, and the Set defaults choice offers the same two profiles as a button. It sets the nested-group matching, the account-state check with its attribute and mask, and clears an inherited search filter that would otherwise override the profile. The address, search base, search account, CA, group mappings, transport, prefix, timeouts and cache are left alone, because those are the site's. Nothing is saved until Apply, so the filled values stay visible before they take effect, and the form says which fields it filled and which already had those values.
Set Directory type to ad and the defaults follow what Active Directory expects: a login without @ is looked up bysAMAccountName, a login with @ byuserPrincipalName, nested groups are followed, and the disabled flag of the account is checked after a successful bind.
| Setting | What ad changes |
|---|---|
User search filter, empty | (sAMAccountName={username}), or(userPrincipalName={username}) when the login contains@. A filter you write yourself is used as it is. |
Nested groups (auto) | Group membership is asked through the in-chain matching rule (1.2.840.113556.1.4.1941), so a user nested two groups deep is still a member of the mapped one. no reads direct membership only, which is what OpenLDAP understands. |
Check account state (auto) | After the password binds, the account's userAccountControl is read with the service account and an account whose 2 bit (ACCOUNTDISABLE) is set is refused, instead of relying on the bind alone. |
The attribute and the bit are settings of their own (account_state_attribute, account_state_disabled_mask), so a directory with a different flag layout can be described without code. A value that is not a number is read as "no opinion", never as "disabled": a misconfigured attribute must not lock everybody out.
Active Directory support has been checked against a Samba AD DC and aWindows Server 2026 domain controller, both serving the real AD schema. Both stands verify login by sAMAccountName and by user principal name, a mapped group reached through a nested group, and the refusal of a disabled account.
TLS and the search account
Passwords travel in a bind, so the connection to the directory must be encrypted:LDAPS from the first byte, or StartTLS, which upgrades a plain connection before any password is sent and is refused if that upgrade fails. Certificate and hostname checks are mandatory. Directory CA certificate names the authority that signed the directory server's certificate — not this broker's own certificate, which vouches for the broker and for nothing else. Leave it empty to use the system trust store. Referrals are not followed, so credentials are not sent to a server nobody configured.
Searching for the user's DN is done with a service account (bind_dn andbind_password), or anonymously when both are empty. Give it read access to the user subtree and to the mapped group entries, and nothing else — not the directory administrator. Each network operation has its own timeout (timeout_seconds, 1–30), so the worst case for one CONNECT is roughly that timeout times two plus the number of mapped groups.
"settings": {
"host": "ldap.example.org",
"port": "636",
"encryption": "ldaps",
"search_base": "ou=people,dc=example,dc=org",
"bind_dn": "cn=xmq-reader,ou=services,dc=example,dc=org",
"bind_password": "REPLACE-ME",
"user_filter": "(uid={username})",
"username_prefix": "ldap/",
"ca_file": "/etc/xmq/directory-ca.crt",
"timeout_seconds": "3",
"group_filter": "(member={dn})",
"group_mappings": "cn=Server Monitoring,dc=example,dc=org => Server Monitoring",
"cache_ttl_seconds": "60",
"negative_cache_ttl_seconds": "10",
"cache_max_entries": "4096"
}In a cluster every node needs the same extension configuration, because each of them authenticates its own clients against the directory. Keep the file readable only by the broker's account: it carries the service password.
When it does not work
| Symptom | Usually |
|---|---|
Authentication failed for a name typed without the prefix | The client sent alice; send ldap/alice. |
| Connected, but nothing is delivered | The SUBSCRIBE was refused: a filter wider than the group's rule. The log says so, naming the filter. |
| Everybody with the prefix is refused, local accounts still work | The directory, its certificate or the service account. The log names the failed operation without printing credentials or DNs. |
| Signed in, but every topic is denied | No mapped group matched, or the mapped XMQ group has no rule for that topic. Check group_filter, the group DN, and the Permissions page. |
A directory user is also a perfectly ordinary MQTT client: any MQTT 5 client, including the bundled command-line tools, can be used to reproduce a problem without involving the application that reported it.
Current limits
Direct group membership only, no nested groups. Account state beyond what the bind reports — disabled or expired accounts, password-expiry warnings — is not interpreted separately. No CRL or OCSP checking. Compatibility has been verified against OpenLDAP; Active Directory has not yet been certified, and its schema variants are a separate test. There is no provisioning of directory users into the accounts database.
