Tous les produits
Search

Ce produit

    ApsaraMQ for MQTT:Client operations for token-based authentication

    Centre de documentation

    ApsaraMQ for MQTT:Client operations for token-based authentication

    Dernière mise à jour :Aug 11, 2026

    ApsaraMQ for MQTT prend en charge l'authentification par jeton pour contrôler l'accès des clients aux ressources de messagerie. Cette rubrique explique comment configurer les paramètres de connexion avec des jetons, mettre à jour les jetons sans déconnexion et gérer les notifications d'expiration et d'invalidation des jetons.

    Flux d'authentification

    L'authentification par jeton suit la séquence suivante :

    1. Votre application demande des jetons au service de jetons ApsaraMQ for MQTT, en spécifiant les ressources et les types d'autorisation (lecture, écriture ou les deux).

    2. Le client MQTT se connecte au broker en incluant les données du jeton dans les champs Username et Password du paquet CONNECT.

    3. Le broker vérifie le jeton et accorde l'accès aux ressources spécifiées.

    4. Pendant la session, le client peut mettre à jour les jetons en publiant sur un sujet système ; le broker envoie alors des notifications en cas d'expiration ou d'invalidation du jeton.

    Types de jetons

    Chaque client ApsaraMQ for MQTT peut détenir un jeton par type et utiliser un ou plusieurs types simultanément.

    Identifiant de type Autorisation Description
    R Lecture seule Accorde l'autorisation de lecture pour les ressources spécifiées
    W Écriture seule Accorde l'autorisation d'écriture pour les ressources spécifiées
    RW Lecture et écriture Accorde les autorisations de lecture et d'écriture pour les ressources spécifiées

    Paramètres de connexion

    Pour vous connecter avec une authentification par jeton, définissez les champs Username et Password dans le paquet MQTT CONNECT comme suit.

    Nom d'utilisateur

    Format : Token|<AccessKey ID>|<Instance ID>

    Composant Description
    Token La chaîne littérale Token, indiquant le mode d'authentification par jeton
    <AccessKey ID> Votre AccessKey ID Alibaba Cloud
    <Instance ID> L'ID de votre instance ApsaraMQ for MQTT

    Exemple :

    Pour un client dont l'ID est GID_Test@@@0001, l'ID d'instance mqtt-xxxxx et l'AccessKey ID YYYYY :

    Token|YYYYY|mqtt-xxxxx

    Mot de passe

    Format : Paires de type et de contenu de jeton concaténées avec des barres verticales (|). Les différents types de jetons peuvent apparaître dans n'importe quel ordre.

    Exemples :

    • Jeton unique : Si le client détient un jeton en lecture seule 123, définissez Password sur :

        R|123

    • Plusieurs jetons : Si le client détient un jeton en lecture seule 123 et un jeton en écriture seule abcd, définissez Password sur :

        R|123|W|abcd
    Important

    Tous les jetons du champ Password doivent être valides. Si un jeton est invalide, le broker peut rejeter la connexion.

    Mise à jour des jetons sans déconnexion

    Par défaut, pour renouveler un jeton, déconnectez le client et reconnectez-le avec le nouveau jeton. Pour éviter la déconnexion, publiez un message de mise à jour de jeton sur le sujet système $SYS/uploadToken. Le broker remplace le jeton dans sa session sans interrompre la connexion.

    Procédure de mise à jour

    1. Publiez un message JSON vers $SYS/uploadToken contenant le nouveau jeton.

    2. Attendez la réponse PUBACK avant toute opération de publication ou d'abonnement. Si le client poursuit ses opérations sans attendre, le broker risque de continuer à s'authentifier avec l'ancien jeton, ce qui entraînera un échec d'authentification et une déconnexion.

    3. Mettez à jour la configuration locale du jeton afin que le client utilise le nouveau jeton lors de la prochaine reconnexion.

    Format du message

    Sujet : $SYS/uploadToken

    Charge utile : Chaîne JSON contenant les champs suivants :

    Paramètre Type Obligatoire Description
    token String Oui La nouvelle chaîne de jeton
    type String Oui Type de jeton : R, W ou RW. Un type invalide provoque une erreur de vérification des autorisations.

    Exemple de charge utile :

    {
  "token": "<your-token-string>",
  "type": "RW"
}

    Réponse : Un message PUBACK standard.

    Important

    Mettez toujours à jour la configuration locale du jeton après une mise à jour réussie. Sinon, le client risque d'utiliser les anciennes données de jeton lors de la prochaine reconnexion.

    Notifications d'expiration de jeton

    Le broker ApsaraMQ for MQTT envoie des avertissements d'expiration aux clients via le sujet système $SYS/tokenExpireNotice. Aucun abonnement n'est requis : le broker délivre ces notifications directement.

    Sujet : $SYS/tokenExpireNotice

    Charge utile : Chaîne JSON contenant les champs suivants :

    Paramètre Type Description
    expireTime Long Heure d'expiration du jeton sous forme d'horodatage Unix en millisecondes
    type String Type de jeton : R, W ou RW

    Comportement des notifications

    • Le broker envoie généralement une notification environ 5 minutes avant l'expiration d'un jeton.

    • La livraison n'est pas garantie. Ne comptez pas uniquement sur ces notifications pour gérer le cycle de vie des jetons.

    • Après avoir reçu une notification, demandez un nouveau jeton et mettez-le à jour rapidement pour éviter les échecs de messagerie.

    Notifications d'invalidation de jeton

    Lorsque le broker détecte une erreur de vérification de jeton, il envoie une notification d'erreur au client via le sujet système $SYS/tokenInvalidNotice puis déconnecte le client. Aucun abonnement n'est requis.

    Sujet : $SYS/tokenInvalidNotice

    Charge utile : Chaîne JSON contenant les champs suivants :

    Paramètre Type Description
    code int Code d'erreur identifiant le type d'échec de vérification du jeton
    type String Type de jeton : R, W ou RW

    Codes d'erreur

    Code Description
    1 Le jeton est falsifié et ne peut pas être analysé
    2 Le jeton a expiré
    3 Le jeton a été révoqué
    4 La ressource et le jeton ne correspondent pas
    5 Le type d'autorisation et le jeton ne correspondent pas
    8 La signature est invalide
    -1 L'autorisation du compte est invalide

    Comportement de déconnexion

    En cas d'erreur de vérification de jeton par le broker :

    1. L'authentification échoue.

    2. Le broker envoie le code d'erreur au client via $SYS/tokenInvalidNotice.

    3. Le broker déconnecte le client.

    Utilisez le code d'erreur pour identifier la cause racine et prendre les mesures correctives nécessaires avant de vous reconnecter.

    Bonnes pratiques

    • Utilisez des jetons à courte durée de vie. Définissez une période de validité raisonnable pour les jetons afin de limiter l'impact d'une éventuelle fuite.

    • Activez TLS. Chiffrez les connexions client pour empêcher l'interception des jetons pendant la transmission.

    • Gérez proactivement l'expiration. Implémentez une logique d'actualisation des jetons dans votre client plutôt que de compter uniquement sur les notifications d'expiration du broker, car leur livraison n'est pas garantie.

    • Stockez les identifiants en toute sécurité. Récupérez votre AccessKey ID à partir de variables d'environnement ou d'un gestionnaire de secrets au lieu de le coder en dur dans votre application.

    • Maintenez la synchronisation entre les jetons locaux et ceux du broker. Après avoir mis à jour un jeton via $SYS/uploadToken, mettez toujours à jour la configuration locale pour éviter l'utilisation de jetons obsolètes lors de la reconnexion.