MQTT JWT-Authentifizierung: Tokens im Passwortfeld

Bei der MQTT JWT-Authentifizierung legt ein Client ein signiertes JSON Web Token in das Passwortfeld seines CONNECT-Pakets, und der Broker prüft Signatur und Claims, statt ein gespeichertes Passwort nachzuschlagen. Dieser Artikel erklärt, wie das auf Protokollebene funktioniert, wie Sie auf echten Geräten mit Ablauf und Erneuerung von Tokens umgehen und wann sich der zusätzliche Aufwand im Vergleich zu statischen Zugangsdaten pro Gerät lohnt.

Wie ein JWT in MQTT CONNECT mitreist

Die Basis-Authentifizierung von MQTT kennt kein eigenes Token-Feld. Es gibt einen Username-String und ein Passwortfeld, das die Spezifikation als Binärdaten definiert. Broker mit JWT-Unterstützung verwenden genau dieses Feld:

CONNECT
  Client ID:  sensor-0042
  Username:   sensor-0042            (often ignored or matched to a claim)
  Password:   eyJhbGciOiJSUzI1NiIs...  (the encoded JWT)

Ein JWT besteht aus drei base64url-kodierten, durch Punkte getrennten Teilen: einem Header mit dem Algorithmus, einem Payload mit Claims und einer Signatur. Die Claims eines typischen Geräte-Tokens sehen so aus:

{
  "iss": "https://auth.example.com",
  "sub": "sensor-0042",
  "aud": "mqtt.example.com",
  "iat": 1792130400,
  "exp": 1792134000,
  "topics": {
    "pub": ["plant1/line3/sensor-0042/#"],
    "sub": ["plant1/line3/sensor-0042/cmd/#"]
  }
}

Der Broker oder ein angebundenes Authentifizierungs-Plugin geht dann so vor:

1. Er dekodiert das Token und prüft die Signatur mit einem gemeinsamen Geheimnis (HS256) oder einem öffentlichen Schlüssel (RS256, ES256).
2. Er prüft exp, nbf, iss und aud.
3. Optional vergleicht er sub mit der Client ID oder dem Username.
4. Optional wertet er eigene Claims aus, um zu entscheiden, welche Topics der Client nutzen darf.

In Industrie-4.0-Anlagen ist die Topic-Struktur oft ein Unified Namespace (UNS) nach ISA-95. Ein Topic-Claim kann ein Gerät dann auf genau seinen Teilbaum beschränken, etwa acme/werk-stuttgart/montage/linie-1/zelle-3/#.

Da das Token als Passwort übertragen wird, gilt dieselbe Regel wie bei jedem Verfahren zur MQTT-Authentifizierung mit Benutzername und Passwort: Es muss über TLS gesendet werden. Ein JWT ist ein Bearer-Credential. Wer es abfängt, kann es bis zum Ablauf verwenden.

MQTT 5 Enhanced Authentication

MQTT 5.0 ergänzt eine Authentication-Method-Property und ein AUTH-Paket, damit Broker und Client Challenge-Response-Abläufe durchführen und sich während einer laufenden Session ohne Verbindungsabbau erneut authentifizieren können. Manche Broker stellen Token-Verfahren über diesen Mechanismus bereit, sodass sich ein Token auf einer offenen Verbindung erneuern lässt. Die Unterstützung unterscheidet sich stark zwischen Brokern und Client-Bibliotheken, daher setzen die meisten Deployments weiterhin auf den einfacheren Weg über das Passwortfeld und verbinden sich zur Erneuerung neu. Die OASIS-Spezifikation zu MQTT 5.0 beschreibt den AUTH-Ablauf.

Welche Broker unterstützen JWT?

JWT ist eine Funktion des Brokers oder eines Plugins, nicht Teil von MQTT selbst. Einige Broker bringen einen JWT-Authenticator mit, und Mosquitto kann Tokens über Authentifizierungs-Plugins von Drittanbietern prüfen. Schauen Sie in der Dokumentation Ihres Brokers nach, welche Algorithmen, Schlüsselquellen (statischer Schlüssel oder JWKS-Endpunkt) und Claim-Zuordnungen unterstützt werden.

ConnectMQ unterstützt keine JWT-Authentifizierung. Ein ConnectMQ-Broker authentifiziert Clients mit dem im Portal generierten Benutzernamen und Passwort und bindet jede Client ID an die für sie ausgestellten Zugangsdaten. Mandanten sind voneinander isoliert, sodass diese Zugangsdaten nur Ihren eigenen Broker erreichen. Die folgenden Abwägungen helfen Ihnen zu entscheiden, ob dieses Modell oder ein Token-Modell besser zu Ihrem Projekt passt.

Token ausstellen und verwenden: ein Beispiel

Das folgende Beispiel zeigt die beiden Hälften eines JWT-Setups mit einem hypothetischen Broker unter mqtt.example.com, der RS256-Tokens prüft. Zuerst signiert ein minimaler Aussteller-Dienst ein Token für ein Gerät:

# pip install pyjwt cryptography
import time
import jwt

PRIVATE_KEY = open("issuer_private.pem", "rb").read()

def issue_device_token(device_id: str, ttl_seconds: int = 3600) -> str:
    now = int(time.time())
    claims = {
        "iss": "https://auth.example.com",
        "sub": device_id,
        "aud": "mqtt.example.com",
        "iat": now,
        "nbf": now - 30,          # geringe Uhrenabweichung tolerieren
        "exp": now + ttl_seconds,
    }
    return jwt.encode(claims, PRIVATE_KEY, algorithm="RS256")

if __name__ == "__main__":
    print(issue_device_token("sensor-0042"))

Anschließend verbindet sich das Gerät mit dem Token als Passwort und verbindet sich vor dem Ablauf mit einem frischen Token neu:

# pip install paho-mqtt requests
import ssl
import time
import requests
import paho.mqtt.client as mqtt

DEVICE_ID = "sensor-0042"
TOKEN_URL = "https://auth.example.com/device-token"
REFRESH_EVERY = 50 * 60   # 10 Minuten vor einem 60-Minuten-Ablauf erneuern

def fetch_token() -> str:
    # Das Gerät authentifiziert sich beim Aussteller mit seinem eigenen langfristigen Geheimnis
    r = requests.post(TOKEN_URL, json={"device": DEVICE_ID}, timeout=10)
    r.raise_for_status()
    return r.json()["token"]

def on_connect(client, userdata, flags, reason_code, properties):
    print("CONNACK:", reason_code)

client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2,
                     client_id=DEVICE_ID, protocol=mqtt.MQTTv5)
client.tls_set(cert_reqs=ssl.CERT_REQUIRED)
client.on_connect = on_connect

def connect_with_fresh_token():
    client.username_pw_set(DEVICE_ID, fetch_token())
    client.connect("mqtt.example.com", 8883, keepalive=60)
    client.loop_start()

connect_with_fresh_token()
while True:
    time.sleep(REFRESH_EVERY)
    client.disconnect()      # sauberer Disconnect, Session bleibt erhalten, falls konfiguriert
    client.loop_stop()
    connect_with_fresh_token()

Beachten Sie den Kommentar in fetch_token: Das Gerät braucht weiterhin ein langfristiges Geheimnis oder Zertifikat, um sich gegenüber dem Aussteller auszuweisen. JWT verlagert das statische Credential von der Broker-Verbindung auf die Verbindung zum Aussteller; es beseitigt es nicht.

Muster für Ablauf und Erneuerung

Der Ablauf ist der Hauptgrund für Tokens und zugleich die häufigste Ursache für Produktionsstörungen. Broker gehen auf eine von zwei Arten mit einem ablaufenden Token um:

Muster, die sich auf Geräten bewähren:

1. Früh erneuern. Fordern Sie ein neues Token bei etwa 80 Prozent seiner Lebensdauer an, nicht erst beim Ablauf.
2. Sauber neu verbinden. Nutzen Sie eine persistente Session (Clean Start false mit Session Expiry), damit Subscriptions und gepufferte QoS-1-Nachrichten den Reconnect überstehen.
3. Die Uhr richtig halten. Ein Gerät mit falscher Uhrzeit erzeugt oder verwirft Tokens fehlerhaft. Synchronisieren Sie die Zeit per NTP, bevor Sie ein Token anfordern, und erlauben Sie eine kleine Abweichung über nbf.
4. Ausfälle des Ausstellers abfangen. Ist der Aussteller nicht erreichbar, behält das Gerät seine aktuelle Verbindung und versucht es mit Backoff erneut; eine funktionierende Session sollte es nicht abbrechen.
5. CONNACK-Gründe protokollieren. Ein abgelaufenes oder ungültiges Token führt in MQTT 5 typischerweise zu 0x86 (Bad User Name or Password) oder 0x87 (Not authorized).

Sicherheitsfallen bei Tokens

Tokens scheitern auf andere Weise als Passwörter, prüfen Sie daher diese Punkte vor dem Produktivbetrieb:

• Algorithm Confusion. Konfigurieren Sie den Broker so, dass er nur den Algorithmus akzeptiert, den Sie ausstellen, zum Beispiel RS256. Akzeptieren Sie niemals none, und lassen Sie den Token-Header nie zwischen symmetrischer und asymmetrischer Prüfung wählen.
• Gemeinsame HMAC-Geheimnisse auf Geräten. Wenn Geräte ihre eigenen HS256-Tokens signieren könnten, besäße jedes Gerät das Master-Geheimnis. Signieren Sie Tokens ausschließlich serverseitig.
• Zu lange Lebensdauer. Ein Token, das ein Jahr gültig ist, ist nur ein Passwort mit Umwegen. Halten Sie die Lebensdauer so kurz, dass ein geleaktes Token schnell abläuft, und so lang, dass Geräte in schlechten Netzen nicht ständig erneuern.
• Fehlende Audience-Prüfung. Ohne aud kann ein Token, das für einen anderen Dienst ausgestellt wurde, gegen Ihren Broker wiederverwendet werden.
• Tokens im Log. Tokens landen genau wie Passwörter in Debug-Logs und Absturzberichten. Protokollieren Sie sub und exp, niemals das Token.

JWT im Vergleich zu statischen Zugangsdaten pro Gerät

JWT spielt seine Stärken aus, wenn Sie bereits einen Identity Provider betreiben, wenn sich Nutzer (nicht nur Geräte) aus Browsern oder mobilen Apps mit kurzen Sessions verbinden oder wenn die Autorisierung direkt im Credential stecken soll.

Statische Zugangsdaten pro Gerät spielen ihre Stärken bei Geräteflotten aus, bei denen Einfachheit zählt: Mikrocontroller mit begrenzten Ressourcen, SPS-nahe Gateways in der Fertigung, Standorte mit unzuverlässigem Zugang zu einem Aussteller und Teams, die keinen Authentifizierungsdienst betreiben möchten. Ihre Schwäche, langlebige Geheimnisse, wird durch geschützte Speicherung und geplante Rotation abgefangen. Lesen Sie dazu, wie Sie MQTT-Zugangsdaten rotieren, und für die Autorisierungsseite die Hinweise zu MQTT-ACL-Konzepten.

Ein Mittelweg mit einem verwalteten MQTT-Broker

Wenn Sie von JWT vor allem „keine gemeinsamen Geheimnisse und eine schnelle Möglichkeit, ein einzelnes Gerät auszusperren" erwarten, erreichen Sie das meiste davon auch ohne Tokens: Geben Sie jedem Gerät eigene Zugangsdaten, binden Sie diese an eine Client ID, bewahren Sie sie in geschütztem Speicher auf und rotieren Sie sie planmäßig. Genau dieses Modell bietet ein verwalteter MQTT-Broker wie ConnectMQ von Haus aus, mit TLS auf 8883 und 8084, IP-Sperre nach wiederholten fehlgeschlagenen Logins und Mandantenisolation. Bei Browser-Apps bleiben die Broker-Zugangsdaten in Ihrem Backend, und Nutzer authentifizieren sich dort mit dem Token-System, das Sie ohnehin verwenden.

Starten Sie mit ConnectMQ

Sie möchten starke Authentifizierung pro Gerät, ohne einen Token-Aussteller zu betreiben? Erstellen Sie unter app.connectmq.com einen kostenlosen Serverless-Cloud-MQTT-Broker, ganz ohne Kreditkarte, und verbinden Sie Ihr erstes Gerät in wenigen Minuten über TLS mit generierten Zugangsdaten.

Häufig gestellte Fragen

Unterstützt ConnectMQ die MQTT JWT-Authentifizierung?

Nein. ConnectMQ authentifiziert Clients mit generierten Benutzernamen und Passwörtern, wobei jede Client ID an die für sie ausgestellten Zugangsdaten gebunden ist. Mandanten sind voneinander isoliert.

Wo steht das JWT in einer MQTT-Verbindung?

Die meisten Broker erwarten es im Passwortfeld von CONNECT, teilweise mit der Geräte-ID oder einem festen Wert als Username. Manche MQTT-5-Broker akzeptieren Tokens auch über Enhanced Authentication.

Was passiert, wenn das Token während einer Session abläuft?

Das hängt vom Broker ab. Manche prüfen nur beim Verbindungsaufbau, andere trennen den Client beim Ablauf. Geräte sollten das Token daher vor dem Ablauf erneuern und sich neu verbinden.

Ist JWT sicherer als ein Passwort?

Ein kurzlebiges Token begrenzt, wie lange ein gestohlenes Credential funktioniert, doch Geräte brauchen weiterhin ein langfristiges Geheimnis, um Tokens zu beziehen. Die Gesamtsicherheit hängt davon ab, wie beide Geheimnisse gespeichert und übertragen werden.