HTTP Authentication
HTTP authentication
The HTTP authenticator asks a service of yours whether an MQTT client may connect, and takes the client's groups from the answer. The accounts, the business rules and the state of each device stay in that service; XMQ keeps the MQTT topic permissions in Permissions and never asks the service about a topic.
The library ships with the broker and needs no directory or vendor SDK, only HTTPS. An installation that does not use it has no xmq_http_auth entry in its extension configuration. Loading it, and the settings that go with it, is described on the Extensions page.
A common arrangement is HTTP authentication first anduser-database or ldap after it: the HTTP users are handled by the service, and the accounts that must keep working when the service is down are owned by the next authenticator. A named client that no authenticator claims is refused.
What the service receives
With the default username_prefix of http/, a client connects as http/alice and the prefix is stripped before the request is sent. A username outside the prefix is not handled, so it continues down the chain.
POST /mqtt/authenticate HTTP/1.1
Content-Type: application/json
Accept: application/json
{
"username": "alice",
"password": "secret",
"client_id": "sensor-room-7",
"remote_address": "10.1.1.25",
"protocol_version": 5,
"encrypted": true
}protocol_version is 3, 4 or 5; encrypted says whether MQTT itself runs over TLS. remote_address is the peer address, not a forwarded header. If username_prefix is empty, every client with a username is sent to the service; clients without one are left to the broker's anonymous policy.
What the answer means
| Answer | Effect |
|---|---|
{"decision": "allow", "groups": ["Sensors"]} | Admit the client with those groups. groups may be missing or empty, but the client then has no topic access. |
{"decision": "deny"}, HTTP 401 or 403 | Refuse the credentials. Remembered for the negative lifetime. |
{"decision": "not_handled"} | Ask the next authenticator. Never remembered. |
| Any other status, malformed JSON, unknown decision | Refuse as server unavailable, never as a wrong password and never as an admission. |
A malformed answer cannot become an accidental allow: a missing or unknowndecision, a body that is not a JSON object, or a groupsvalue that is not an array of strings is a subsystem error. MQTT 5 clients see CONNACK 0x86 for a refused credential and 0x88 for an unavailable service; MQTT 3.x clients see 0x04 and 0x03.
Groups, not topic rules
The names in groups are used as they are and must already exist as XMQ groups. A service that returns Sensors gives the client exactly the permissions of a local account in Sensors; the extension never synthesizes an ACL rule. Duplicate names are collapsed, at most 256 groups of at most 256 characters each are accepted, and a group that matches no rule grants nothing.
Keep the mapping in the service if it should not depend on the broker's group names: the service is free to translate its own roles into XMQ groups before answering.
Caching and when a change applies
An ALLOW is remembered for cache_ttl_seconds (default 60), a DENY fornegative_cache_ttl_seconds (default 10), and the store is bounded bycache_max_entries, least recently used first out. The key is a keyed hash of the exact request under a per-process random salt, so the identity, password, client id and peer address all have to match; neither passwords nor request bodies are stored.
| Change at the service | Reaches clients |
|---|---|
| An account or password is disabled | When the cached ALLOW expires (at most one cache_ttl_seconds) and the client reconnects. Set it to 0 when every CONNECT must ask the service. |
| Groups change | With the next token-free recheck: after the cached ALLOW expires, on reconnect. |
| The service is unavailable | A cached answer can still be used. Without one, the CONNECT is refused as server unavailable; the outage is never remembered. That is checked by the bundled stand. |
| The extension configuration is applied | At once: reload replaces both the configuration and the decision cache. |
An already connected session is not disconnected when a cached decision would have expired or an account is disabled at the service. Authentication decides at CONNECT; cutting a live session needs a separate policy.
TLS and limits
The endpoint must be https:// outside loopback. Plain http://is accepted only for localhost and 127.0.0.1, for a stand on the same machine; IPv6 endpoints, including ::1, are currently rejected. HTTPS verifies the chain and the host name, requires TLS 1.2 or newer and uses a private context. ca_file replaces system trust for this endpoint and is how a corporate CA is trusted.
timeout_seconds (default 5) is one budget for connection establishment, the TLS handshake and HTTP I/O. Synchronous DNS resolution cannot be interrupted and can exceed it. Responses are requested uncompressed: only HTTP 200 is accepted, the body is limited to 64 KiB and headers to 16 KiB, and redirects are not followed.max_inflight (default 16) bounds concurrent uncached requests; excess CONNECTs are refused as server unavailable rather than queued without limit.
Known limits
- Authentication only. There is no HTTP request per PUBLISH or SUBSCRIBE; topic rules stay in XMQ's own Permissions, which is what keeps the message path free of network calls.
- No introspection or revocation list: the broker trusts the service's answer for the cache lifetime and does not ask again per message.
- No retries and no background refresh. A request either answers within the deadline or the CONNECT fails.
- The cache is per process: two nodes decide independently until their entries expire. A clustered deployment that needs one answer for all nodes should keep
cache_ttl_secondsshort or set it to0. not_handledis not anonymous access. Anonymous access remains the broker's own setting and applies to clients that send no username.
