Freigeben über

So verbinden Sie MQTT-Clients mit Azure Web PubSub

MQTT ist ein einfaches Pub/Sub-Messagingprotokoll, das für Geräte mit eingeschränkten Ressourcen entwickelt wurde.

In diesem Artikel wird erläutert, wie MQTT-Clients mit dem Dienst verbunden werden, damit die Clients Nachrichten veröffentlichen und abonnieren können.

Verbindungsparameter

WebSocket-Verbindungs-URI: wss://{serviceName}.webpubsub.azure.com/clients/mqtt/hubs/{hub}?access_token={token}.

  • {hub} ist ein obligatorischer Parameter, der Isolation für verschiedene Anwendungen bietet.
  • {token} ist standardmäßig erforderlich. Alternativ können Sie das Token in den Authorization-Header im Format „Bearer {token}“ einschließen. Sie können die Tokenanforderung umgehen, indem Sie anonymen Zugriff auf den Hub aktivieren.

Wenn die Clientbibliothek keinen URI akzeptiert, müssen Sie wahrscheinlich die Informationen im URI in mehrere Parameter aufteilen:

  • Host: {serviceName}.webpubsub.azure.com
  • Pfad: /clients/mqtt/hubs/{hub}?access_token={token}
  • Port: 443
  • Transport: WebSockets mit TLS.

Es gibt einige Einschränkungen, die Sie bei Ihren MQTT-Clients beachten müssen. Andernfalls wird die Verbindung abgelehnt. Zu diesen MQTT-Protokollparametern zählen:

  • Protokollversionen: 3.1.1 oder 5.0.
  • Client-ID-Format
    • Zulässige Zeichen: 0–9, a–z, A–Z
    • Die Länge liegt zwischen 1 und 128
  • Keepalive-Intervall für MQTT 3.1.1: 1–180 Sekunden
  • Last-Will-Themenformat: nicht leer und enthält mindestens ein Zeichen, das kein Leerzeichen ist. Die maximale Länge ist 1.024.
  • Last-Will-Nachrichtengröße: bis zu 2.000 Bytes

Standardmäßig besitzen MQTT-Clients keine Berechtigungen zum Veröffentlichen oder Abonnieren von Themen. Sie müssen MQTT-Clients Berechtigungen erteilen.

Berechtigungen

Ein Client kann nur dann auf anderen Clients veröffentlicht werden, wenn er dazu autorisiert ist. Die Berechtigungen eines Clients können beim Herstellen der Verbindung oder für die Dauer der Verbindung erteilt werden.

Role Berechtigung
Nicht angegeben Der Client kann Ereignisanforderungen senden.
webpubsub.joinLeaveGroup Der Client kann einer beliebigen Gruppe beitreten oder diese verlassen.
webpubsub.sendToGroup Der Client kann Nachrichten in einer beliebigen Gruppe veröffentlichen.
webpubsub.joinLeaveGroup.<group> Der Client kann der Gruppe <group> beitreten oder diese verlassen.
webpubsub.sendToGroup.<group> Der Client kann Nachrichten in Gruppe <group> veröffentlichen.

Authentifizierung und Autorisierung

Es gibt zwei Workflows, die von Web PubSub unterstützt werden, um MQTT-Clients zu authentifizieren und zu autorisieren, sodass sie über entsprechende Berechtigungen verfügen.

Diese Workflows können einzeln oder in Kombination verwendet werden. Wenn sie zusammen verwendet werden, würde das Authentifizierungsergebnis im letzteren Workflow vom Dienst berücksichtigt werden.

1. JWT-Workflow

Dies ist der Standardworkflow, der wie folgt aussieht:

Diagramm des MQTT-Authentifizierungsworkflows mit JWT.

  1. Der Client verhandelt mit Ihrem Authentifizierungsserver. Der Authentifizierungsserver enthält die Middleware für die Autorisierung, die die Anforderungen des Clients bearbeitet und ein JWT signiert, damit der Client eine Verbindung mit dem Dienst herstellen kann.
  2. Der Authentifizierungsserver gibt JWT an den Client zurück.
  3. Der Client versucht, eine Verbindung mit dem Web PubSub-Dienst herzustellen, wobei das JWT-Token vom Authentifizierungsserver zurückgegeben wird. Das Token kann entweder in der Abfragezeichenfolge als /clients/mqtt/hubs/{hub}?access_token={token} oder im Authorization-Header als Authorization: Bearer {token} enthalten sein.

Unterstützte Ansprüche

Sie können auch Eigenschaften für die Clientverbindung konfigurieren, wenn Sie das Zugriffstoken generieren, indem Sie spezielle Ansprüche im JWT-Token angeben:

Beschreibung Anspruchstyp Anspruchswert Hinweise
Die Berechtigungen, über die die Clientverbindung anfänglich verfügt role der in den Berechtigungen definierte Rollenwert Geben Sie mehrere role-Ansprüche an, wenn der Client über mehrere Berechtigungen verfügt.
Die Lebensdauer des Token exp Die Ablaufzeit Der exp-Anspruch (Ablaufzeit) gibt die Ablaufzeit an, ab oder nach der das Token NICHT für die Bearbeitung akzeptiert werden darf.
Die anfänglichen Gruppen, denen die Clientverbindung beitritt, sobald sie eine Verbindung mit Azure Web PubSub herstellt group die Gruppe, der beizutreten ist Geben Sie mehrere group-Ansprüche an, wenn der Client mehreren Gruppen beitritt.
userId für die Clientverbindung sub die userId Es ist nur ein sub-Anspruch zulässig.

Sie können dem Zugriffstoken auch benutzerdefinierte Ansprüche hinzufügen, und diese Werte werden als claims-Eigenschaft im Upstreamanforderungstext für die Verbindung beibehalten.

Server-SDKs stellen APIs zum Generieren der Zugriffstoken für MQTT-Clients bereit. Beachten Sie, dass Sie das Clientprotokoll auf Mqtt festlegen müssen.

  1. Folgen Sie den ersten Schritten mit dem Server-SDK, um ein WebPubSubServiceClient Objekt service zu erstellen.

Hinweis

Die MQTT-Clientzugriffs-URL wird seit Version 1.1.3 unterstützt.

  1. Generieren Sie die Clientzugriffs-URL durch Aufrufen von WebPubSubServiceClient.getClientAccessToken:

    let token = await serviceClient.getClientAccessToken({ clientProtocol: "mqtt" });

2. Upstream-Serverworkflow

Der MQTT-Client sendet ein MQTT CONNECT-Paket, nachdem es eine WebSocket-Verbindung mit dem Dienst hergestellt hat, und der Dienst ruft dann eine API auf dem Upstream-Server auf. Der Upstream-Server kann den Client entsprechend den Benutzernamen- und Kennwortfeldern in der MQTT-Verbindungsanforderung und dem TLS-Zertifikat vom Client authentifizieren.

Diagramm des MQTT-Authentifizierungsworkflows mit Upstream-Server

Dieser Workflow benötigt eine explizite Konfiguration.

Problembehandlung

Wenn ein Verbindungsausfall auftritt oder Nachrichten nicht veröffentlicht oder abonniert werden können, überprüfen Sie den Ursachencode/Rückgabecode des Diensts, oder lesen Sie die Problembehandlung bei Ressourcenprotokollen.