Autenticação MQTT com Usuário e Senha Explicada

A autenticação MQTT com usuário e senha é a forma mais usada para um cliente provar sua identidade a um broker e também a mais mal configurada. Neste guia você vai ver exatamente como as credenciais trafegam no pacote CONNECT, por que elas só ficam seguras dentro do TLS, quais reason codes você recebe quando elas estão erradas e como gerenciar um conjunto de credenciais por dispositivo.

Como as credenciais trafegam no pacote CONNECT

Toda sessão MQTT começa com um pacote CONNECT enviado pelo cliente. Seu cabeçalho variável contém os connect flags, dois dos quais são o User Name Flag e o Password Flag. Quando esses flags estão ativos, o payload carrega o usuário como string UTF-8 e a senha como dados binários, logo depois do client ID e da mensagem Will opcional.

CONNECT
  Protocol name:    MQTT
  Protocol level:   5 (MQTT 5.0) or 4 (MQTT 3.1.1)
  Connect flags:    username=1, password=1, clean start=1
  Keep alive:       60
  Payload:
    Client ID:      sensor-0042
    Username:       YOUR_USERNAME
    Password:       YOUR_PASSWORD   <- raw bytes, not hashed

Não há hash, desafio nem criptografia na camada MQTT. A senha é enviada como está. Qualquer pessoa que consiga ler o fluxo TCP na porta 1883 lê a senha com uma ferramenta de captura de pacotes em segundos.

Alguns detalhes do protocolo valem a pena conhecer:

• No MQTT 3.1.1, uma senha só pode ser enviada se um usuário também for enviado. O MQTT 5.0 flexibilizou isso para permitir enviar só a senha, mas a maioria dos brokers ainda espera os dois.
• O campo de senha é binário, então pode conter bytes arbitrários, inclusive tokens. É assim que esquemas baseados em token, como a autenticação JWT no MQTT, reaproveitam o mesmo campo.
• O MQTT 5.0 também define a autenticação estendida por meio da propriedade Authentication Method e de pacotes AUTH, para mecanismos de desafio-resposta. Usuário e senha continuam sendo a base comum.

Por que o TLS é obrigatório com senhas

Como a senha atravessa a rede em texto claro, a autenticação MQTT com usuário e senha sem TLS é pouco melhor do que nenhuma autenticação em qualquer rede não confiável. O TLS criptografa a sessão inteira, incluindo o pacote CONNECT, e permite que o cliente verifique que está falando com o broker verdadeiro, e não com um impostor que coleta credenciais.

No ConnectMQ, use a porta 8883 para dispositivos e serviços e a 8084 para navegadores sempre que enviar credenciais. O broker apresenta um certificado Let's Encrypt, confiável pelos pacotes de CAs padrão dos sistemas operacionais de desktop e servidor. Clientes embarcados precisam da CA raiz incluída no firmware; o guia de configuração de TLS no MQTT cobre essa etapa.

Verifique também o certificado. Desativar a verificação (insecure, setInsecure(), rejectUnauthorized: false) dá criptografia contra escuta passiva, mas nenhuma proteção contra um atacante que intercepta a conexão e apresenta o próprio certificado.

Conectando com usuário e senha

Os exemplos usam os placeholders YOUR_USERNAME, YOUR_PASSWORD e YOUR_CLIENT_ID, que você recebe ao criar um broker no portal. Se ainda não configurou um, o guia de broker MQTT na nuvem apresenta as opções de hospedagem.

Python (paho-mqtt 2.x)

import os
import ssl
import paho.mqtt.client as mqtt

HOST = os.environ.get("MQTT_HOST", "YOUR_BROKER_HOST")
USERNAME = os.environ["MQTT_USERNAME"]   # nunca coloque fixo no código versionado
PASSWORD = os.environ["MQTT_PASSWORD"]
CLIENT_ID = os.environ["MQTT_CLIENT_ID"]

def on_connect(client, userdata, flags, reason_code, properties):
    if reason_code.is_failure:
        print("Rejected:", reason_code)   # ex.: Bad user name or password
        client.disconnect()
        return
    print("Authenticated")
    client.publish(f"devices/{CLIENT_ID}/status", "online", qos=1, retain=True)

client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2,
                     client_id=CLIENT_ID, protocol=mqtt.MQTTv5)
client.username_pw_set(USERNAME, PASSWORD)
client.tls_set(cert_reqs=ssl.CERT_REQUIRED)
client.on_connect = on_connect
client.connect(HOST, 8883, keepalive=60)
client.loop_forever()

Linha de comando

mosquitto_pub -h YOUR_BROKER_HOST -p 8883 \
  --cafile /etc/ssl/certs/ca-certificates.crt \
  -i YOUR_CLIENT_ID -u YOUR_USERNAME -P "$MQTT_PASSWORD" \
  -t 'devices/YOUR_CLIENT_ID/status' -m online -V mqttv5

Leia a senha de uma variável de ambiente em vez de digitá-la na linha de comando, onde ela acaba no histórico do shell e nas listagens de processos.

O que acontece quando as credenciais estão erradas

O broker responde ao CONNECT com um CONNACK. O código indica se o problema está nas credenciais ou na autorização:

Os passos completos de solução de problemas estão em conexão MQTT recusada: not authorized. Duas regras práticas valem para todo cliente:

1. Não tente de novo imediatamente em um loop apertado. Credenciais erradas não se corrigem sozinhas, e muitos brokers tratam falhas rápidas como ataque. O ConnectMQ bloqueia endereços IP após repetidas falhas de login, então uma frota mal configurada martelando o broker pode acabar se trancando do lado de fora.
2. Use backoff exponencial com jitter e exponha as falhas de autenticação nos logs ou no status do dispositivo, separadas dos erros de rede.

Credenciais por dispositivo: por que e como

O atalho com que a maioria dos projetos começa é um único usuário e senha compartilhados, gravados em todos os dispositivos, por exemplo em todos os sensores de uma usina. Funciona no primeiro dia e causa problemas daí em diante:

• Um único dispositivo vazado expõe a frota inteira.
• Você não consegue revogar um dispositivo sem regravar todos.
• Os logs não dizem qual dispositivo se comportou mal.

Credenciais por dispositivo resolvem os três problemas. Em um broker Mosquitto auto-hospedado, você manteria um arquivo de senhas:

# Cria o arquivo com o primeiro usuário e depois adiciona outros sem -c
mosquitto_passwd -c /etc/mosquitto/passwd sensor-0001
mosquitto_passwd /etc/mosquitto/passwd sensor-0002

# mosquitto.conf
listener 8883
certfile /etc/mosquitto/certs/server.crt
keyfile  /etc/mosquitto/certs/server.key
allow_anonymous false
password_file /etc/mosquitto/passwd

O arquivo armazena hashes com salt, não as próprias senhas, e o broker precisa ser recarregado após mudanças. Operar isso por conta própria também significa manter o certificado TLS renovado e o arquivo sincronizado entre instâncias.

Credenciais por dispositivo no ConnectMQ

Com o ConnectMQ, o broker gera as credenciais para você. Ao criar um broker no portal, você recebe usuário, senha e client ID, e o client ID fica vinculado às credenciais emitidas. Esse vínculo importa: uma senha roubada não pode ser usada com um client ID arbitrário, e dois dispositivos não conseguem compartilhar silenciosamente um conjunto de credenciais, porque estariam disputando a mesma identidade vinculada.

Prática recomendada em um broker MQTT gerenciado:

1. Emita um conjunto de credenciais separado para cada dispositivo ou serviço e registre qual dispositivo físico tem qual client ID.
2. Guarde a senha em armazenamento protegido no dispositivo, não no código-fonte. Veja proteger credenciais MQTT em dispositivos.
3. Conecte apenas pelas portas 8883 ou 8084 com verificação de certificado.
4. Planeje mudanças: o guia de rotação de credenciais mostra como substituir credenciais em uma frota sem tempo de inatividade.

Os tenants são isolados entre si, então as credenciais emitidas para o seu broker dão acesso apenas ao tráfego do seu broker. Cotas e proteção contra flood se aplicam por plano, o que limita o estrago que um único cliente comprometido pode causar.

Usuário e senha versus outros métodos

Para a maioria das frotas, senhas únicas por dispositivo sobre TLS verificado são uma base sólida. O guia de boas práticas de segurança MQTT cobre as camadas que vêm por cima.

Comece a usar o ConnectMQ

Esqueça os arquivos de senhas e as renovações de certificado. Um broker MQTT gerenciado do ConnectMQ oferece TLS nas portas 8883 e 8084, credenciais geradas vinculadas a client IDs e bloqueio de IP após repetidas falhas de login. Crie um broker Serverless gratuito em app.connectmq.com, sem cartão de crédito.

Perguntas frequentes

A autenticação MQTT com usuário e senha é segura?

É segura o suficiente para a maioria das implantações quando usada sobre TLS com verificação de certificado e senhas únicas por dispositivo. Sobre TCP simples na porta 1883, a senha fica visível para qualquer pessoa que consiga capturar o tráfego.

O MQTT criptografa a senha?

Não. O MQTT envia a senha como bytes brutos dentro do CONNECT. A criptografia vem apenas da camada TLS em volta da conexão.

Posso me conectar ao servidor MQTT público com usuário e senha?

O servidor MQTT público (gratuito) em broker.connectmq.com aceita conexões anônimas com qualquer client ID único e não vazio e serve para testes e protótipos, não para dados de produção. Para tráfego autenticado e privado, crie o seu próprio broker e use as credenciais geradas.

Qual é a diferença entre 0x86 e 0x87?

0x86 significa que o usuário ou a senha estavam errados. 0x87 significa que as credenciais foram entendidas, mas o cliente não tem permissão para se conectar ou executar a ação.