Connexion MQTT

Utilisez MQTT quand un courtier (broker) convient mieux qu’une connexion directe en WSS ou en HTTPS.

MQTT reste un protocole public sécurisé. Les clients se connectent au courtier en TLS, s’authentifient avec des identifiants propres à chaque client et ne publient que sur les sujets (topics) permis pour ce client.

Quand utiliser MQTT

Clients en périphérie

Des appareils ou de petits services ont besoin d’un chemin qui passe par un courtier.

Frontières réseau

Le client joint un courtier de façon plus fiable qu’une route directe vers le hub.

Trafic convergent

De nombreux clients ont besoin d’un accès isolé à leurs sujets par un seul point de terminaison public du courtier.

Pas le choix par défaut

Commencez par WSS, sauf si MQTT règle un vrai problème de déploiement.

Ce qui doit être en place

1. MQTT est activé sur le hub. WSS peut rester le protocole par défaut pendant que MQTT est optionnel.
2. Le courtier est joignable en TLS. Les clients publics devraient utiliser mqtts://.
3. L’identité du client contient des identifiants MQTT. Après avoir activé MQTT, créez ou téléchargez une nouvelle identité, ou ouvrez Connection details.
4. L’accès aux sujets est limité au client. Publiez et abonnez-vous uniquement sous le topic_prefix que renvoie l’identité.

Forme des identifiants

Quand MQTT est activé, l’identité du client porte un bloc mqtt :

{
  "mqtt": {
    "endpoint": "mqtts://mqtt.thalovant.com:8883",
    "username": "client-access-key",
    "password": "client-broker-password",
    "topic_prefix": "<namespace>/<hub-id>/<client-id>",
    "tls": true
  }
}

Champ	Signification
endpoint	URL du courtier. Les clients publics devraient utiliser mqtts://.
username	Nom d’utilisateur du courtier pour ce client. C’est la clé d’accès du client.
password	Mot de passe du courtier pour ce client.
topic_prefix	Base complète des sujets de ce client. Ajoutez-y un suffixe de canal au lieu de coder un chemin en dur.
tls	Indique si le client doit se connecter en TLS.

Attention

Le mot de passe du courtier, le mot de passe du hub et la clé privée statique du client sont des secrets. Gardez-les dans un stockage protégé.

Sujets

Le topic_prefix de l’identité est la base complète de tous les sujets qu’utilise ce client. Il ressemble à <namespace>/<hub-id>/<client-id>, où <client-id> est la clé d’accès du client. Traitez-le comme une valeur opaque : lisez topic_prefix dans l’identité et ajoutez le suffixe de canal au lieu d’assembler le chemin vous-même.

Canal	Sujet	Rôle
Entrant	<topic_prefix>/in	Le client y publie ses requêtes.
Sortant	<topic_prefix>/out	Le client s’y abonne pour recevoir les réponses.
État	<topic_prefix>/status	Présence et état conservés (retained) pour ce client.

Note

Ces canaux sont la convention du protocole. Ce qu’un client peut réellement publier ou recevoir par abonnement est régi par la liste de contrôle d’accès (ACL) du courtier propre à chaque connexion du hub. Un abonnement peut être refusé, par exemple sur <topic_prefix>/out ou <topic_prefix>/status, tant que l’ACL de cette connexion ne l’accorde pas. Si les réponses n’arrivent jamais après une connexion réussie, l’ACL de la connexion a probablement besoin de l’autorisation d’abonnement.

Obtenir les identifiants MQTT

Les identifiants MQTT d’un client proviennent de son identité. Pour les lire en vue d’un client personnalisé :

1. Ouvrez la connexion. Dans Connections, sélectionnez le client, puis ouvrez son panneau Connection details.
2. Confirmez que c’est bien vous. Confirmez avec votre application d’authentification ou un code de récupération. Le panneau est protégé parce qu’il renvoie des secrets.
3. Copiez les identifiants du courtier. Prenez le point de terminaison (mqtts://mqtt.thalovant.com:8883), le nom d’utilisateur (la clé d’accès), le mot de passe du courtier et le préfixe de sujet. Gardez aussi l’identité complète : c’est son mot de passe de hub qui authentifie la session auprès du hub. Vous pouvez aussi télécharger _identity.json.

Si la connexion en deux étapes bloque le panneau, configurez-la d’abord dans Profile and Security.

Note

Après l’activation de MQTT, il peut falloir ouvrir une fois Connection details pour qu’une connexion existante obtienne ses identifiants MQTT.

Clients MQTT personnalisés

Vous pouvez connecter n’importe quel client MQTT au courtier avec les identifiants ci-dessus, sans Thalovant Voice ni runtime géré. Joindre le courtier est la partie la plus simple.

Les sujets <topic_prefix>/in et <topic_prefix>/out transportent les messages de connexion et d’authentification, suivis des messages applicatifs chiffrés. Abonnez-vous au sujet sortant avant d’envoyer quoi que ce soit. Les messages chiffrés sont en binaire brut, pas en base64 ni en JSON; gardez dans l’ordre tous les fragments d’un même message et ne rejouez jamais un message.

Un client personnalisé doit se connecter au courtier et s’authentifier auprès du hub avant d’envoyer des requêtes applicatives. Utilisez le transport MQTT d’un SDK Python, Node.js, Go ou Rust compatible, ou pilotez le protocole avec la bibliothèque C embarquée et votre propre transport. Une connexion au courtier ne constitue pas à elle seule une session authentifiée avec le hub.

Conservez les clés enregistrées par le SDK d’une reconnexion à l’autre. Après la perte de la connexion au courtier, authentifiez-vous de nouveau avant d’envoyer quoi que ce soit. Utilisez des identités différentes pour les processus clients connectés en même temps.

Attention

Connectez-vous toujours avec mqtts:// et validez le certificat du courtier. TLS protège les identifiants du courtier et la connexion. La session avec le hub est une deuxième couche : elle chiffre les messages applicatifs et prouve que le hub est bien le hub. Aucune des deux ne remplace l’autre.

Python

from thalovant import ThalovantClient, ThalovantControlPlane

api = ThalovantControlPlane()
api.login("[email protected]", "password")

result = api.create_client_identity(
    "hub-id",
    name="python-mqtt-client",
    preferred_protocols=("mqtt", "wss"),
)

identity = result.identity
if identity.mqtt is None:
    raise RuntimeError("MQTT is not available for this identity.")

with ThalovantClient(identity, protocol="mqtt") as client:
    print(client.ask("Reply over MQTT.").text)

Node.js

import { ThalovantClient, ThalovantControlPlane } from "@thalovant/sdk";

const api = new ThalovantControlPlane();
await api.login("[email protected]", "password");

const result = await api.createClientIdentity("hub-id", {
  name: "node-mqtt-client",
  preferredProtocols: ["mqtt", "wss"],
});

if (!result.identity.mqtt) {
  throw new Error("MQTT is not available for this identity.");
}

const client = new ThalovantClient(result.identity, { protocol: "mqtt" });
try {
  const reply = await client.ask("Reply over MQTT.");
  console.log(reply.text);
} finally {
  await client.close();
}

Go

result, err := control.CreateClientIdentityForHubID(ctx, "hub-id", thalovant.BootstrapIdentityOptions{
  Name: "go-mqtt-client",
  PreferredProtocols: []thalovant.HubProtocol{
    thalovant.ProtocolMQTT,
    thalovant.ProtocolWSS,
  },
})
if err != nil {
  log.Fatal(err)
}
if result.Identity.MQTT == nil {
  log.Fatal("MQTT is not available for this identity.")
}

client, err := thalovant.NewClientWithOptions(result.Identity, thalovant.ClientOptions{
  Protocol: thalovant.ProtocolMQTT,
})
if err != nil {
  log.Fatal(err)
}
defer client.Close(ctx)

Rust

let result = control
    .create_client_identity_for_hub_id(
        "hub-id",
        BootstrapIdentityOptions {
            name: "rust-mqtt-client".into(),
            preferred_protocols: vec![HubProtocol::Mqtt, HubProtocol::Wss],
            ..Default::default()
        },
    )
    .await?;

if result.identity.mqtt.is_none() {
    panic!("MQTT is not available for this identity.");
}

let client = Client::with_protocol(result.identity.clone(), HubProtocol::Mqtt)?;

Problèmes fréquents

Symptôme	Vérification
Le SDK indique que MQTT n’est pas pris en charge	Utilisez Python, Node.js côté serveur, Go ou Rust. Kotlin, Swift, .NET et la version navigateur de Node n’ont pas de transport MQTT. Confirmez aussi que le hub et l’identité activent MQTT.
L’identité n’a pas de bloc mqtt	Activez MQTT sur le hub, puis ouvrez Connection details ou téléchargez une nouvelle identité pour obtenir les identifiants du courtier.
L’authentification auprès du courtier échoue	Confirmez que le nom d’utilisateur est la clé d’accès et que le client utilise le plus récent mot de passe du courtier. Faites une rotation de l’identité au besoin.
TLS échoue	Utilisez le point de terminaison mqtts:// et confirmez que le certificat du courtier est valide.
Une publication réussit, mais rien ne répond	Confirmez que l’abonnement au sujet sortant et l’authentification auprès du hub étaient terminés avant l’envoi. Un accusé de réception du courtier ne confirme à lui seul ni l’authentification auprès du hub ni une réponse applicative.
Une reconnexion échoue à l’authentification	Conservez les clés enregistrées par le SDK, vérifiez le mot de passe du hub et authentifiez-vous de nouveau avant d’envoyer.
Les messages sont ignorés	Publiez sur <topic_prefix>/in et abonnez-vous à <topic_prefix>/out. N’inventez pas de chemins de sujets.

Astuce

Si WSS fonctionne et que le client n’a pas besoin d’un courtier, continuez d’utiliser WSS.