Credits:The XMQ web site is provided by Linotex.The XMQ and SPTK Windows installers are created with Advanced Installer free Open-Source license.
There were 0 unique visitors to this page

User Database Authentication

User database authentication

The user-database extension authenticates MQTT clients against the broker's own SQL account database - the same accounts the Users screen edits. An account added or changed in the interface is in the same store the extension reads, so there is no copy to synchronize and no second user table to explain.

Unlike the optional extensions it is not a switch on the Extensions page: a broker either authenticates against its account database or runs with no accounts at all, and the Users screens exist only when it does. What it has is a configuration, edited like any other extension's.

It answers one question - may this client connect - and nothing else. Group membership and topic permissions are the broker's authorizer's business, read from the same database through Permissions. This extension declares no authorizer capability and never answers a publish or subscribe question.

The four answers

An authenticator can say more than yes or no, and the difference is what a client sees during an outage. The broker asks the configured authenticators in order and stops at the first allow or deny.

AnswerWhenWhat the client sees
ALLOWThe account exists, is enabled, and the password verifies.The connection is accepted.
DENYThe password is wrong, the account is disabled, it has no password set, or it does not exist while unknown_user is deny.Bad user name or password: CONNACK 0x86 for MQTT 5,0x04 for MQTT 3.x.
NOT_HANDLEDThe client sent no user name - that is the broker's anonymous policy to decide - or the name is unknown while unknown_user isabstain.Nothing yet: the next authenticator is asked, and the broker refuses the client if none claims it.
SUBSYSTEM_ERRORThe database could not be reached or the query failed.Server unavailable: CONNACK 0x88 for MQTT 5,0x03 for MQTT 3.x.

An outage is never reported as a wrong password: telling a client with good credentials that they are wrong sends an operator looking at the wrong system, and it hides a database failure behind an authentication failure.

An unknown name is the one answer that is deliberately not remembered. A name may appear a second after a client tried it, and with abstain configured the next attempt has to reach the database and see it.

The database

Any database the SPTK driver layer speaks:sqlite3://localhost/path,postgresql://user:pass@host/db ormysql://user:pass@host/db (MariaDB is treated as MySQL). Set it once on the Initial Setup page; the extension uses that address unless its owndatabase_uri names another.

The xmq_user table is created on first start when it is missing, so the database account this connects with has to be allowed to create tables - or the table has to be created by hand. SQLite and PostgreSQL and MySQL are understood; a driver that this extension does not know how to give an auto-assigned key is refused rather than half-created.

Changing the address on a running server opens and probes the new database first, and refuses the change while the old one is still authenticating if the new one names nothing, cannot be logged into, or has no schema. When the new database is one this extension has just created, the accounts are copied into it; a table that was already there is never written to, because a shared database somebody else populates must not quietly acquire this node's local accounts because a URI was edited. Ids are not copied - the new store assigns its own - and group membership is not copied, because it is not this extension's data.

In a cluster every node has to name the same database. That shared database is what makes an account added on one node valid on the next connection to another; seeSetting up a Cluster.

Password formats

The password is verified inside the extension, not by the database, and it understands the formats a broker may already have on disk:

PrefixFormatWhere it comes from
pbkdf2-sha256$pbkdf2-sha256$iterations$salt$hashWhat the interface writes for an account created here.
$7$PBKDF2-HMAC-SHA512A Mosquitto 2.0 password file, copied as it is by the import.
$6$SHA512-crypt, checked with the platform's crypt()A Mosquitto 1.6 password file, where the platform hascrypt().
$argon2id$Argon2idAn account imported from a source that uses it, where Argon2 is available.

An account whose stored password is empty has never had one set, and nothing authenticates against it - least of all an empty password, which is exactly what a client that sent none arrives with. Disabling an account is theis_enabled column, checked on every verification.

Importing accounts and their hashes is described onImporting from Mosquitto.

Configuration

SettingDefaultMeaning
database_uriemptyThe database that holds user accounts. Empty means the broker's ownauthentication.database_uri, which is the setting on theInitial Setup page. Changing it on a running server copies the accounts into a database it has just created.
usernameemptyThe account this extension opens the database with - not an MQTT client. Leave empty for SQLite, which has no users.
passwordemptyThe password for that database account. A secret: masked in the interface and kept out of the log, including the line that names the database when a connection fails.
unknown_userdenydeny refuses a name this database does not hold, because it is the account database. abstain passes the client to the next authenticator, for a deployment where a directory or an HTTP service owns the names this one has never held.
poll_interval5How often, in seconds, to check xmq_store_version for changes made by another node sharing this database. Only PostgreSQL and MySQL; SQLite is local and is not polled. 0 disables polling.

The one-minute cache

Verifying a password costs an HMAC and a key derivation - about a millisecond - and the broker hands every connection to an authenticator over a small pool of threads. A scenario run, or a reconnect storm after a restart, arrives far faster than that. So the answer is remembered for up to 60 seconds.

Nothing in the cache holds a password. An entry is found by an HMAC of the credentials under a key made when the process starts and never written anywhere, so a core file yields nothing replayable. Refusals are remembered as well as admissions: otherwise a client sending wrong passwords costs a full derivation each time, which is a way to spend the broker's cores from outside. A corrected password hashes to a different entry and is verified properly, so keeping refusals delays no repair.

The cache is 4096 entries, direct-mapped: a collision overwrites and a miss is not a failure, it falls through to a real verification. It is dropped when the interface saves a change to accounts or groups on this node, and when the version poll sees another node's change. There is no way to shorten the lifetime itself, so a password changed through a path the broker is not told about, or an account revoked elsewhere while polling is off, can keep working for up to a minute. Restarting the broker clears it immediately.

Beside other authenticators

Authenticators are asked in configuration order and the first allow or deny is final. user-database is the natural last entry: an HTTP service, a directory or a token issuer claims the names it owns, and this one answers for the rest. That arrangement needs unknown_user set to abstain; with the default deny a name the database has never held is refused before the next authenticator is asked.

The other way round - this database as the authority, with another source reachable only for names it does not hold - is the same ordering written differently, and is what the abstain setting exists for.

Limits

  • One answer per connection. A password or an enablement change reaches the next CONNECT once the cache entry expires or is dropped; an established session is not disconnected by a revocation.
  • No topic rules here. Group membership and permissions are the authorizer's and are edited on the Groups and Permissions screens, not in this extension's settings.
  • The database is on the connect path. With the cache cold, every connect that misses it costs a query; an unreachable database refuses connects asserver unavailable rather than admitting them.
  • Schema changes are refused, not migrated. A xmq_user table this extension does not recognise is a start-up error, which is preferable to reading the wrong columns.