Skip to content

Latest commit

 

History

History
149 lines (95 loc) · 7.67 KB

howto-connect-mqtt-websocket-client.md

File metadata and controls

149 lines (95 loc) · 7.67 KB
title description author ms.author ms.service ms.date ms.topic
How to connect MQTT clients to Azure Web PubSub
How to connect MQTT clients to Azure Web PubSub
Y-Sindo
zityang
azure-web-pubsub
06/17/2024
how-to

How to connect MQTT clients to Azure Web PubSub

MQTT is a lightweight pub/sub messaging protocol designed for devices with constrained resources.

In this article, we introduce how to connect MQTT clients to the service, so that the clients can publish and subscribe messages.

Connection parameters

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

  • {hub} is a mandatory parameter that provides isolation for different applications.
  • {token} is required by default. Alternatively, you can include the token in the Authorization header in the format Bearer {token}. You can bypass the token requirement by enabling anonymous access to the hub.

If client library doesn't accept a URI, then you probably need to split the information in the URI into multiple parameters:

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

[!INCLUDE MQTT-Connection-parameters]

By default MQTT clients don't have any permissions to publish or subscribe to any topics. You need to grant permissions to MQTT clients.

Permissions

A client can publish to other clients only when it's authorized to do so. A client's permissions can be granted when it's being connected or during the lifetime of the connection.

Role Permission
Not specified The client can send event requests.
webpubsub.joinLeaveGroup The client can join or leave any group.
webpubsub.sendToGroup The client can publish messages to any group.
webpubsub.joinLeaveGroup.<group> The client can join or leave group <group>.
webpubsub.sendToGroup.<group> The client can publish messages to group <group>.

Authentication and authorization

There are two workflows supported by Web PubSub to authenticate and authorize MQTT clients, so that they have proper permissions.

These workflows can be used individually or in combination. If they're used in together, the auth result in the latter workflow would be honored by the service.

1. JWT workflow

This is the default workflow, shown as follows:

Diagram of MQTT auth workflow with JWT.

  1. The client negotiates with your auth server. The auth server contains the authorization middleware, which handles the client request and signs a JWT for the client to connect to the service.
  2. The auth server returns the JWT to the client.
  3. The client tries to connect to the Web PubSub service with the JWT token returned from the auth server. The token can be in either the query string, as /clients/mqtt/hubs/{hub}?access_token={token}, or the Authorization header, as Authorization: Bearer {token}.

Supported claims

You could also configure properties for the client connection when generating the access token by specifying special claims inside the JWT token:

Description Claim type Claim value Notes
The permissions the client connection initially has role the role value defined in permissions Specify multiple role claims if the client has multiple permissions.
The lifetime of the token exp the expiration time The exp (expiration time) claim identifies the expiration time on or after which the token MUST NOT be accepted for processing.
The initial groups that the client connection joins once it connects to Azure Web PubSub group the group to join Specify multiple group claims if the client joins multiple groups.
The userId for the client connection sub the userId Only one sub claim is allowed.

You could also add custom claims into the access token, and these values are preserved as the claims property in connect upstream request body.

Server SDKs provides APIs to generate the access token for MQTT clients. Note that you must specify the client protocol to Mqtt.

JavaScript

  1. Follow Getting started with server SDK to create a WebPubSubServiceClient object service

Note

Generating MQTT client access URL is supported since version 1.1.3.

  1. Generate Client Access URL by calling WebPubSubServiceClient.getClientAccessToken:

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

C#

  1. Follow Getting started with server SDK to create a WebPubSubServiceClient object service

Note

Generating MQTT client access URL is supported since version 1.4.0.

  1. Generate Client Access URL by calling WebPubSubServiceClient.GetClientAccessUri:

    var url = service.GetClientAccessUri(clientProtocol: WebPubSubClientProtocol.Mqtt);

Python

  1. Follow Getting started with server SDK to create a WebPubSubServiceClient object service

Note

Generating MQTT client access URL is supported since version 1.2.0.

  1. Generate Client Access URL by calling WebPubSubServiceClient.get_client_access_token:

    token = service.get_client_access_token(client_protocol="MQTT")

Java

  1. Follow Getting started with server SDK to create a WebPubSubServiceClient object service

Note

Generating MQTT client access URL is supported since version 1.3.0.

  1. Generate Client Access URL by calling WebPubSubServiceClient.getClientAccessToken:

    GetClientAccessTokenOptions option = new GetClientAccessTokenOptions();
option.setWebPubSubClientProtocol(WebPubSubClientProtocol.MQTT);
WebPubSubClientAccessToken token = service.getClientAccessToken(option);

2. Upstream server workflow

The MQTT client sends an MQTT CONNECT packet after it establishes a WebSocket connection with the service, then the service calls an API in the upstream server. The upstream server can auth the client according to the username and password fields in the MQTT connection request, and the TLS certificate from the client.

Diagram of MQTT auth workflow with upstream server

This workflow needs explicit configuration.

Troubleshooting

If you're experiencing failure of connection, or unable to publish or subscribe messages, please check the reason code / return code from the service, or see How to troubleshoot with resource logs.