Autenticação JWT no MQTT: Tokens no Campo de Senha

Autenticação JWT no MQTT significa que o cliente coloca um JSON Web Token assinado no campo de senha do pacote CONNECT, e o broker valida a assinatura e as claims em vez de consultar uma senha armazenada. Este artigo explica como isso funciona na rede, como lidar com a expiração e a renovação de tokens em dispositivos reais e quando as peças extras compensam em comparação com credenciais estáticas por dispositivo.

Como um JWT viaja dentro do CONNECT do MQTT

O MQTT não tem um campo dedicado a tokens na autenticação básica. O que ele tem é uma string de usuário e um campo de senha que a especificação define como dados binários. Os brokers que suportam JWT reaproveitam esse campo:

CONNECT
  Client ID:  sensor-0042
  Username:   sensor-0042            (often ignored or matched to a claim)
  Password:   eyJhbGciOiJSUzI1NiIs...  (the encoded JWT)

Um JWT tem três partes codificadas em base64url, separadas por pontos: um cabeçalho que indica o algoritmo, um payload de claims e uma assinatura. As claims de um token típico de dispositivo são assim:

{
  "iss": "https://auth.example.com",
  "sub": "sensor-0042",
  "aud": "mqtt.example.com",
  "iat": 1792130400,
  "exp": 1792134000,
  "topics": {
    "pub": ["plant1/line3/sensor-0042/#"],
    "sub": ["plant1/line3/sensor-0042/cmd/#"]
  }
}

Em seguida, o broker, ou um plugin de autenticação acoplado a ele:

1. Decodifica o token e verifica a assinatura com um segredo compartilhado (HS256) ou uma chave pública (RS256, ES256).
2. Verifica exp, nbf, iss e aud.
3. Opcionalmente compara sub com o client ID ou o usuário.
4. Opcionalmente lê claims personalizadas para decidir quais topics o cliente pode usar.

Como o token trafega como senha, vale a mesma regra de qualquer esquema de autenticação MQTT com usuário e senha: ele precisa ser enviado sobre TLS. Um JWT é uma credencial ao portador. Quem o capturar pode usá-lo até que expire.

Autenticação estendida do MQTT 5

O MQTT 5.0 adiciona a propriedade Authentication Method e o pacote AUTH para que broker e cliente possam executar trocas de desafio-resposta e se reautenticar durante uma sessão ativa sem desconectar. Alguns brokers expõem métodos de token por esse mecanismo, o que permite renovar um token em uma conexão aberta. O suporte varia muito entre brokers e bibliotecas de cliente, então a maioria das implantações ainda usa a abordagem mais simples do campo de senha e se reconecta para renovar. A especificação OASIS MQTT 5.0 descreve o fluxo AUTH.

Quais brokers suportam JWT?

JWT é um recurso do broker ou de um plugin, não do MQTT em si. Alguns brokers incluem um autenticador JWT, e o Mosquitto pode validar tokens por meio de plugins de autenticação de terceiros. Consulte a documentação do seu broker para ver quais algoritmos, fontes de chave (chave estática ou endpoint JWKS) e mapeamentos de claims ele suporta.

O ConnectMQ não suporta autenticação JWT. Um broker ConnectMQ autentica os clientes com o usuário e a senha gerados no portal e vincula cada client ID às credenciais emitidas. Os tenants são isolados entre si, então essas credenciais só alcançam o seu próprio broker. Os prós e contras abaixo vão ajudar você a decidir se esse modelo ou um modelo de tokens é o mais adequado ao seu projeto.

Emitindo e usando um token: exemplo

O exemplo abaixo mostra as duas metades de uma configuração JWT com um broker hipotético em mqtt.example.com que valida tokens RS256. Primeiro, um serviço emissor mínimo assina um token para um dispositivo:

# pip install pyjwt cryptography
import time
import jwt

PRIVATE_KEY = open("issuer_private.pem", "rb").read()

def issue_device_token(device_id: str, ttl_seconds: int = 3600) -> str:
    now = int(time.time())
    claims = {
        "iss": "https://auth.example.com",
        "sub": device_id,
        "aud": "mqtt.example.com",
        "iat": now,
        "nbf": now - 30,          # tolera pequenas diferenças de relógio
        "exp": now + ttl_seconds,
    }
    return jwt.encode(claims, PRIVATE_KEY, algorithm="RS256")

if __name__ == "__main__":
    print(issue_device_token("sensor-0042"))

Depois, o dispositivo se conecta usando o token como senha e se reconecta com um token novo antes da expiração:

# pip install paho-mqtt requests
import ssl
import time
import requests
import paho.mqtt.client as mqtt

DEVICE_ID = "sensor-0042"
TOKEN_URL = "https://auth.example.com/device-token"
REFRESH_EVERY = 50 * 60   # renova 10 minutos antes de uma expiração de 60 minutos

def fetch_token() -> str:
    # O dispositivo se autentica no emissor com o próprio segredo de longo prazo
    r = requests.post(TOKEN_URL, json={"device": DEVICE_ID}, timeout=10)
    r.raise_for_status()
    return r.json()["token"]

def on_connect(client, userdata, flags, reason_code, properties):
    print("CONNACK:", reason_code)

client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION2,
                     client_id=DEVICE_ID, protocol=mqtt.MQTTv5)
client.tls_set(cert_reqs=ssl.CERT_REQUIRED)
client.on_connect = on_connect

def connect_with_fresh_token():
    client.username_pw_set(DEVICE_ID, fetch_token())
    client.connect("mqtt.example.com", 8883, keepalive=60)
    client.loop_start()

connect_with_fresh_token()
while True:
    time.sleep(REFRESH_EVERY)
    client.disconnect()      # desconexão limpa, sessão mantida se configurada
    client.loop_stop()
    connect_with_fresh_token()

Repare no comentário em fetch_token: o dispositivo ainda precisa de algum segredo ou certificado de longo prazo para se provar ao emissor. O JWT move a credencial estática da conexão com o broker para a conexão com o emissor; ele não a elimina.

Padrões de expiração e renovação

A expiração é o principal motivo para usar tokens e também a principal fonte de incidentes em produção. Os brokers tratam um token que expira de uma de duas formas:

Padrões que funcionam em dispositivos:

1. Renove cedo. Solicite um token novo por volta de 80 por cento da vida útil, não na expiração.
2. Reconecte de forma limpa. Use uma sessão persistente (Clean Start false com session expiry) para que assinaturas e mensagens QoS 1 enfileiradas sobrevivam à reconexão.
3. Mantenha o relógio certo. Um dispositivo com o relógio errado vai gerar ou rejeitar tokens incorretamente. Sincronize a hora por NTP antes de solicitar um token e permita uma pequena diferença com nbf.
4. Trate indisponibilidades do emissor. Se o emissor estiver fora do ar, o dispositivo mantém a conexão atual e tenta de novo com backoff; ele não deve derrubar uma sessão que está funcionando.
5. Registre os motivos do CONNACK. Um token expirado ou inválido normalmente gera 0x86 (Bad User Name or Password) ou 0x87 (Not authorized) no MQTT 5.

Armadilhas de segurança com tokens

Tokens falham de jeitos que senhas não falham, então revise estes pontos antes de ir para produção:

• Confusão de algoritmo. Configure o broker para aceitar apenas o algoritmo que você emite, por exemplo RS256. Nunca aceite none e nunca deixe o cabeçalho do token escolher entre verificação simétrica e assimétrica.
• Segredos HMAC compartilhados nos dispositivos. Se os dispositivos pudessem assinar os próprios tokens HS256, cada dispositivo teria o segredo mestre. Assine tokens apenas no lado do servidor.
• Vidas úteis longas demais. Um token válido por um ano é só uma senha com passos extras. Mantenha a vida útil curta o suficiente para que um token vazado expire rápido, e longa o suficiente para que dispositivos em redes ruins não fiquem renovando o tempo todo.
• Falta de verificação de audiência. Sem aud, um token emitido para outro serviço pode ser reutilizado contra o seu broker.
• Registrar tokens em log. Tokens acabam em logs de depuração e relatórios de falhas, assim como senhas. Registre o sub e o exp, nunca o token.

JWT versus credenciais estáticas por dispositivo

O JWT se destaca quando você já opera um provedor de identidade, quando usuários (e não só dispositivos) se conectam a partir de navegadores ou apps móveis com sessões curtas, ou quando você quer a autorização embutida na própria credencial.

As credenciais estáticas por dispositivo se destacam em frotas em que a simplicidade importa: microcontroladores com recursos limitados, locais com acesso instável a um emissor, como fazendas e mineradoras no interior, e equipes que não querem operar um serviço de autenticação. A fraqueza delas, segredos de longa duração, é tratada com armazenamento protegido e rotação planejada. Veja como rotacionar credenciais MQTT e as notas de projeto em conceitos de ACL MQTT para o lado da autorização.

Um meio-termo com um broker MQTT gerenciado

Se o que você quer do JWT é principalmente "nenhum segredo compartilhado e um jeito rápido de cortar um dispositivo", dá para obter quase tudo isso sem tokens: dê a cada dispositivo seu próprio conjunto de credenciais, vincule-o a um client ID, guarde-o em armazenamento protegido e rotacione-o periodicamente. Esse é o modelo que um broker MQTT gerenciado como o ConnectMQ oferece de fábrica, com TLS nas portas 8883 e 8084, bloqueio de IP após repetidas falhas de login e isolamento de tenants. Para apps no navegador, mantenha as credenciais do broker no seu backend e deixe os usuários se autenticarem no backend com o sistema de tokens que você já usa.

Comece a usar o ConnectMQ

Quer autenticação forte por dispositivo sem operar um emissor de tokens? Crie um broker MQTT na nuvem Serverless gratuito em app.connectmq.com, sem cartão de crédito, e conecte seu primeiro dispositivo via TLS com credenciais geradas em minutos. Para um primeiro teste do cliente sem cadastro, o servidor MQTT público (gratuito) em broker.connectmq.com serve para testes e protótipos, nunca para dados de produção.

Perguntas frequentes

O ConnectMQ suporta autenticação JWT no MQTT?

Não. O ConnectMQ autentica clientes com usuários e senhas gerados, com cada client ID vinculado às credenciais emitidas. Os tenants são isolados entre si.

Onde fica o JWT em uma conexão MQTT?

A maioria dos brokers espera o token no campo de senha do CONNECT, às vezes com o usuário definido como o ID do dispositivo ou um valor fixo. Alguns brokers MQTT 5 também aceitam tokens pela autenticação estendida.

O que acontece quando o token expira durante uma sessão?

Depende do broker. Alguns só validam no momento da conexão, outros desconectam o cliente na expiração, então os dispositivos devem renovar e se reconectar antes de o token expirar.

JWT é mais seguro do que uma senha?

Um token de curta duração limita por quanto tempo uma credencial roubada funciona, mas os dispositivos ainda precisam de um segredo de longo prazo para obter tokens. A segurança geral depende de como os dois segredos são armazenados e transportados.