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

JWT Authentication

JWT authentication

The JWT authenticator lets a client sign in with a token its identity provider has already issued — Keycloak, Entra ID, Auth0, Okta, or anything else that speaks OIDC. The signature is checked locally against a configured key or the issuer's published key set, and the claims say who the client is and which XMQ groups it joins. No directory round trip is made per connection.

The library ships with the broker and needs no extra dependency beyond OpenSSL. An installation that does not use it simply has no xmq_jwt 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 signature, issuer, groups and cache sections: the shared secret appears for HS256, the public key and key-set URL for RS256 and ES256, and a value is kept when a field is hidden. Nothing is saved until Apply; if the form description is unavailable or incompatible, the ordinary settings form remains usable.

The token is the password

MQTT has no field of its own for a token, so the token goes in the password field. The username carries the identity, prefixed: with the defaultusername_prefix a client connects as jwt/alice with the token as its password, and the token's username claim must sayalice. A token issued for one identity cannot connect under another.

The prefix keeps a token from standing in for a local account of the same name, and it is what lets the extension tell its clients from everybody else's. A password that is not three dot-separated base64url parts is not this extension's business: it answersnot handled, and the next authenticator in configuration order is asked. Put user-database or ldap after it if other accounts must share the broker: a name that no authenticator claims is refused, and anonymous access is a separate broker setting. A username without the prefix is not handled either.

mosquitto_pub -h broker -p 1883 \
    --username jwt/alice \
    --pw "$(cat alice.jwt)" \
    -t sensors/room1 -m hello

Always connect over TLS with a token. A password field is sent in the clear on a plain listener, and a token is a bearer credential until it expires.

Algorithms and where the key comes from

algorithmKeyNotes
RS256public_key or jwks_urlThe usual choice; Keycloak's default.
ES256public_key or jwks_urlP-256. The raw signature is converted for verification.
HS256secretA shared secret; no key set, no public key.

Only the configured algorithm is accepted. A token that asks for another one is refused before the key is looked at — accepting whatever the token names is how an attacker turns RS256 into HS256 and signs with the public key as the secret.

With public_key the key is pasted into the settings and never fetched. Withjwks_url the issuer's key set is fetched at load and then trusted for five minutes; a token naming a key the set does not hold refreshes it at once, which is how a provider rotates its key without the broker being reconfigured. A key set that cannot be fetched when the configuration is applied is an error on the Extensions page rather than a surprise on the first connection.

Claims the broker checks

ClaimRule
expRequired. A token without an expiry is a password that never changes.
nbfWhen present, must not be in the future beyond the allowed clock skew.
issMust equal issuer exactly.
audWhen audience is set, the token must name it. Empty accepts any audience, which is weaker.
username_claimRequired and non-empty; must equal the MQTT username without the prefix.
groups_claimA string or an array of strings. A dotted path is allowed.

clock_skew_seconds (default 30) is how far exp andnbf may disagree with this host's clock. Keep the broker's clock synchronised anyway: skew is a tolerance, not a substitute for NTP.

Claim names are configurable because providers disagree about where they put things. Keycloak, for example, puts the login in preferred_username and roles inrealm_access.roles; that is a dotted path:

{
  "algorithm": "RS256",
  "jwks_url": "https://keycloak.example.org/realms/xmq/protocol/openid-connect/certs",
  "issuer": "https://keycloak.example.org/realms/xmq",
  "audience": "xmq",
  "username_claim": "preferred_username",
  "groups_claim": "realm_access.roles"
}

Claim values to XMQ groups

Group names in the token are mapped to existing XMQ groups ingroup_mappings: the claim value, then =>, then the name of a group the Groups page already knows.

Operators => Operators
mqtt-publishers => Publishers

With no mappings the claim values are used as group names as they are. In either case the groups decide topic access through Permissions— the token never holds a topic policy. A token that maps to no group is still admitted but has no permissions: native Permissions fail closed for token identities, and local group membership of a similarly named account is never merged in.

How soon a change reaches XMQ

A verified token and its groups are remembered for cache_ttl_seconds(default 60). Refusals are remembered separately and briefly, fornegative_cache_ttl_seconds (default 10), and the store is bounded bycache_max_entries, least recently used evicted first. The cache is keyed by the presented identity and a keyed hash of the token under a per-process random salt: the token itself is never stored, and a restart shares no keys with the previous process.

Change at the issuerReaches clients
Token expiresExpiry is checked on a cache miss. A cached ALLOW can outliveexp plus clock skew until its TTL elapses. Setcache_ttl_seconds=0 to check every CONNECT. Existing sessions are not disconnected at token expiry.
Token revoked or an account disabledNot checked with the provider: there is no introspection or revocation list. An issued token can remain usable until its expiry, and a cached ALLOW can extend admission further. Disabling the cache does not provide immediate revocation.
Groups or roles changed in the tokenThe new token carries them at once; a session already connected keeps the groups it was admitted with until it reconnects.
Provider rotates its signing keyOn a decision-cache miss, a token naming an unknown key refreshes the key set. Otherwise a key lookup refreshes it once the five-minute key-cache lifetime has elapsed; there is no background refresh.
Key set endpoint unreachableA cached ALLOW or a valid token with a fresh cached signing key can still work. If fetching is necessary and fails, CONNECT is refused as a subsystem error; that error is not cached.

The key set over TLS

jwks_url must be an https:// URL. The server's certificate is verified against the system trust store, or against jwks_ca_file when the issuer's key set is served by an internal CA, and the host name is checked against the certificate. Plain http:// is accepted only on loopback (localhost, 127.0.0.1). IPv6 URLs, including::1, are currently rejected by the IPv4-only connect path.

jwks_ca_file is the CA that signed the key-set server's certificate — not the key that signs tokens. For RS256 and ES256 the public_key setting is a PEM public key; the issuer's private key never comes near the broker.

Current limits

  • Tokens are checked locally: provider-side revocation and account disabling are not checked, even when decision caching is disabled. Cache TTL is not capped by token expiry.
  • Only HS256, RS256 and ES256 are accepted. none is not an algorithm here, and a key set entry for another algorithm is ignored.
  • The token identity is the MQTT username, prefixed. Per-user subjects (user:<name>) do not apply to token users today; write their policies on the mapped group, or as a pattern rule.
  • The key-set fetch shares timeout_seconds (default 5) across connect, TLS handshake and HTTP I/O. Synchronous DNS resolution cannot be interrupted and can exceed that budget.
  • SPTK 5.6.20 is required together with OpenSSL 3 or newer. TLS requires at least version 1.2. JWKS responses are limited to 64 KiB of headers and 4 MiB of body; only HTTP 200 is accepted, redirects and compressed responses are not supported. JSON nesting is limited to 32 levels.
  • The extension is experimental: the settings, the cache behaviour and the.ui.json form may change in a later release.