Node-RED MQTT com TLS: Configurando o Node do Broker com Segurança

A configuração de TLS no MQTT do Node-RED leva poucos minutos, mas alguns campos fáceis de deixar passar decidem se a sua conexão é realmente segura ou apenas criptografada. Este tutorial configura o node de configuração mqtt-broker para a porta 8883 com verificação de certificado, credenciais e MQTT 5, entrega um fluxo pronto para importar e explica os erros que você pode encontrar pelo caminho.

Como o TLS funciona no Node-RED

Os nodes MQTT do Node-RED são construídos sobre o MQTT.js e a pilha TLS do Node.js. Três peças estão envolvidas:

• Node de configuração mqtt-broker: guarda o servidor, a porta, o client ID, a versão do protocolo, as credenciais e uma caixa "Use TLS".
• Node tls-config: um node de configuração separado que guarda opções de TLS, como certificado de CA, certificado de cliente, nome do servidor e se o certificado do servidor deve ser verificado.
• Nodes mqtt in / mqtt out: fazem referência ao node do broker; não têm configurações de TLS próprias.

Quando o broker usa um certificado de uma CA publicamente confiável, o Node.js já confia nele por meio da lista de raízes da Mozilla que vem embutida. O broker do ConnectMQ usa um certificado Let's Encrypt, então você não precisa enviar nenhum arquivo de CA; basta habilitar o TLS e manter a verificação ativada.

Se o Node-RED ainda não estiver instalado, siga primeiro nosso guia para instalar o Node-RED.

Escolha de porta e protocolo

Configuração de TLS no Node-RED MQTT passo a passo

Passo 1: crie o node do broker

Arraste um node mqtt in para a área de trabalho e dê um duplo clique nele. Ao lado de Server, escolha Add new mqtt-broker e clique no ícone de lápis.

Na aba Connection:

1. Server: broker.connectmq.com
2. Port: 8883
3. Connect automatically: marcado
4. Use TLS: marcado
5. Protocol: MQTT V5 (ou V3.1.1, se seus outros clientes precisarem)
6. Client ID: o client ID gerado no portal do broker (YOUR_CLIENT_ID). Nunca o deixe vazio em um broker privado e nunca o reutilize em outro cliente, senão as duas conexões vão ficar se derrubando mutuamente.
7. Keep Alive: 60 segundos é um padrão sensato.

Passo 2: adicione a configuração de TLS

Ao marcar Use TLS, aparece um campo TLS Configuration. Escolha Add new tls-config e clique no ícone de lápis:

• Certificate / Private Key: deixe em branco. Servem para autenticação por certificado de cliente (TLS mútuo), que o ConnectMQ não usa; ele autentica com username e senha sobre TLS.
• CA Certificate: deixe em branco para brokers publicamente confiáveis. Envie seu arquivo de CA apenas para um broker privado com CA própria.
• Verify server certificate: marcado. Esta é a caixa mais importante da página.
• Server Name: broker.connectmq.com. O Node.js normalmente deriva o SNI do campo de servidor, mas defini-lo explicitamente evita surpresas.
• Name: um rótulo descritivo, como Cloud broker TLS, para que você possa reutilizar o node em outras configurações de broker.

Clique em Add para voltar ao node do broker.

Passo 3: informe as credenciais

Na aba Security do node do broker, informe o Username e a Password do portal. O Node-RED guarda esses dados em flows_cred.json, separado do fluxo, e eles nunca são incluídos quando você exporta fluxos. Defina o credentialSecret no settings.js para que esse arquivo seja criptografado com uma chave que você controla, e não com uma gerada automaticamente; caso contrário, mover o projeto para outra máquina pode deixar você com credenciais ilegíveis.

Passo 4: configurações opcionais do MQTT 5

Com o MQTT V5 selecionado, aparecem opções extras:

• Session Expiry no node do broker: por quanto tempo o broker mantém suas assinaturas e mensagens QoS 1/2 enfileiradas após uma desconexão. Combinado com um client ID fixo e clean start desativado, isso permite que uma instância do Node-RED reiniciada receba as mensagens que perdeu.
• Aba Messages: mensagens de birth, close e will. Uma mensagem de birth retida como {"status":"online"} e uma mensagem will {"status":"offline"} em um topic de status oferecem um indicador de saúde simples.
• Opções do mqtt in: retain handling, "no local" (não receber as próprias publicações) e "retain as published".
• Opções do mqtt out: message expiry, content type, response topic, correlation data e user properties.

Nossa visão geral dos recursos do MQTT 5 explica cada um deles em mais detalhes.

Passo 5: faça o deploy e verifique

Aponte o node mqtt in para um topic como factory/line1/#, ligue-o a um node debug e clique em Deploy. Em poucos segundos, o status do node deve mudar para um "connected" verde. Se ficar em "connecting" indefinidamente ou mostrar "disconnected", vá para a seção de solução de problemas abaixo.

Fluxo de exemplo para importar

Importe este fluxo (menu, Import, colar) para ter uma configuração TLS completa em um passo. Ele usa o servidor MQTT público (gratuito) sobre TLS com acesso anônimo, então funciona de imediato. Substitua 8b2f por caracteres aleatórios seus; para um broker privado, troque o client ID e adicione as credenciais na aba Security.

[
  {
    "id": "f1e2d3c4b5a69701",
    "type": "tls-config",
    "name": "ConnectMQ TLS",
    "cert": "",
    "key": "",
    "ca": "",
    "certname": "",
    "keyname": "",
    "caname": "",
    "servername": "broker.connectmq.com",
    "verifyservercert": true,
    "alpnprotocol": ""
  },
  {
    "id": "f1e2d3c4b5a69702",
    "type": "mqtt-broker",
    "name": "ConnectMQ over TLS",
    "broker": "broker.connectmq.com",
    "port": "8883",
    "tls": "f1e2d3c4b5a69701",
    "clientid": "nodered-tls-8b2f",
    "autoConnect": true,
    "usetls": true,
    "protocolVersion": "5",
    "keepalive": "60",
    "cleansession": true,
    "autoUnsubscribe": true,
    "sessionExpiry": "",
    "birthTopic": "connectmq/demo/8b2f/nodered/status",
    "birthQos": "1",
    "birthRetain": "true",
    "birthPayload": "{\"status\":\"online\"}",
    "willTopic": "connectmq/demo/8b2f/nodered/status",
    "willQos": "1",
    "willRetain": "true",
    "willPayload": "{\"status\":\"offline\"}"
  },
  {
    "id": "f1e2d3c4b5a69703",
    "type": "inject",
    "name": "Every 10 s",
    "props": [{ "p": "payload" }],
    "repeat": "10",
    "once": true,
    "onceDelay": "2",
    "topic": "",
    "payload": "",
    "payloadType": "date",
    "x": 140,
    "y": 80,
    "wires": [["f1e2d3c4b5a69704"]]
  },
  {
    "id": "f1e2d3c4b5a69704",
    "type": "change",
    "name": "Build reading",
    "rules": [
      { "t": "set", "p": "payload", "pt": "msg", "to": "{\"ts\": payload, \"value\": $round($random() * 100, 1)}", "tot": "jsonata" },
      { "t": "set", "p": "topic", "pt": "msg", "to": "connectmq/demo/8b2f/nodered/reading", "tot": "str" }
    ],
    "x": 330,
    "y": 80,
    "wires": [["f1e2d3c4b5a69705"]]
  },
  {
    "id": "f1e2d3c4b5a69705",
    "type": "mqtt out",
    "name": "Publish over TLS",
    "topic": "",
    "qos": "1",
    "retain": "false",
    "broker": "f1e2d3c4b5a69702",
    "x": 540,
    "y": 80,
    "wires": []
  },
  {
    "id": "f1e2d3c4b5a69706",
    "type": "mqtt in",
    "name": "Subscribe over TLS",
    "topic": "connectmq/demo/8b2f/nodered/#",
    "qos": "1",
    "datatype": "auto-detect",
    "broker": "f1e2d3c4b5a69702",
    "nl": false,
    "rap": true,
    "rh": 0,
    "inputs": 0,
    "x": 160,
    "y": 160,
    "wires": [["f1e2d3c4b5a69707"]]
  },
  {
    "id": "f1e2d3c4b5a69707",
    "type": "debug",
    "name": "Show",
    "active": true,
    "tosidebar": true,
    "console": false,
    "complete": "true",
    "targetType": "full",
    "x": 370,
    "y": 160,
    "wires": []
  }
]

Depois do deploy, a barra lateral de debug mostra o status "online" retido e uma nova leitura a cada dez segundos, tudo trafegando sobre TLS. O servidor MQTT público é visível para todos e serve apenas para testes e protótipos, então use-o apenas para dados de teste, nunca para dados de produção.

Usando WebSocket seguro

Se a sua rede bloqueia a porta 8883, coloque uma URL completa no campo Server: wss://broker.connectmq.com:8084/mqtt. O Node-RED então ignora o campo de porta e se conecta via WebSocket seguro na 8084, com o TLS tratado pela mesma verificação de certificado. Isso é comum em redes corporativas, como as de muitas plantas industriais e mineradoras; veja MQTT sobre WebSocket para entender o contexto.

Solução de problemas de TLS no Node-RED MQTT

1. Preso em "connecting": a porta 8883 provavelmente está bloqueada. Teste a partir do host do Node-RED com openssl s_client -connect broker.connectmq.com:8883 -servername broker.connectmq.com e experimente WSS na 8084.
2. "unable to get local issuer certificate" no log: o Node.js não consegue montar a cadeia. Normalmente é causado por inspeção TLS na rede ou por um arquivo de CA enviado que substituiu os padrões pela raiz errada. Remova o arquivo de CA no caso de brokers publicamente confiáveis.
3. "Hostname/IP does not match certificate's altnames": você informou um endereço IP ou um alias. Use o hostname.
4. "Connection refused: Not authorized" ou um reason code após conectar: o TLS funciona; as credenciais ou o client ID estão errados. Copie-os novamente do portal.
5. Conecta e desconecta a cada poucos segundos: outro cliente usa o mesmo client ID, muitas vezes uma segunda instância do Node-RED ou um script de teste esquecido.
6. "Use TLS" desmarcado com a porta 8883: a conexão trava ou cai porque o broker espera um handshake TLS na 8883, então "Use TLS" precisa estar marcado.

O guia Node-RED MQTT não conecta e como corrigir falhas de handshake TLS no MQTT cobrem mais casos. Nunca desmarque Verify server certificate para fazer um erro sumir; isso esconde a causa real e remove a proteção contra brokers impostores.

Reforçando o restante da sua instalação do Node-RED

Uma conexão criptografada com o broker é uma camada. Proteja também o editor com adminAuth, sirva-o via HTTPS, mantenha o Node-RED e seus nodes atualizados e defina o credentialSecret. Nosso guia para proteger o Node-RED cobre cada passo, e o tutorial de MQTT no Node-RED mostra como estruturar topics e payloads para fluxos maiores.

Rode seus fluxos Node-RED no ConnectMQ

O Node-RED é um cliente MQTT, então precisa de um broker confiável do outro lado. Um broker MQTT gerenciado como o ConnectMQ oferece TLS na 8883, WebSocket seguro na 8084, certificado renovado automaticamente e um portal com explorador de topics ao vivo e dashboard para conferir o que seus fluxos publicam. Cadastre-se em app.connectmq.com, escolha o plano Serverless (Free), sem cartão de crédito, crie um broker e cole o username, a senha e o client ID gerados no node do broker. Para comparar modelos de hospedagem antes, leia nosso guia de broker MQTT na nuvem.

Perguntas frequentes

Preciso enviar um certificado de CA no Node-RED para o ConnectMQ?

Não. O certificado dele é emitido pela Let's Encrypt, em que o Node.js já confia. Habilite o TLS, mantenha "Verify server certificate" marcado e deixe o campo de CA em branco.

Minhas credenciais MQTT são incluídas quando exporto um fluxo?

Não. O Node-RED guarda as credenciais separadamente em flows_cred.json e as exclui das exportações, então você precisa informá-las de novo depois de importar em outra instância.

Várias instâncias do Node-RED podem compartilhar uma configuração de broker?

Podem compartilhar as mesmas configurações, mas cada instância precisa do próprio client ID exclusivo. Dois clientes com o mesmo ID vão ficar se derrubando mutuamente.

Devo escolher MQTT V5 ou V3.1.1 no node do broker?

Escolha V5, a menos que outra parte do seu sistema exija 3.1.1. O V5 acrescenta session expiry, message expiry, user properties e reason codes mais claros, e o ConnectMQ suporta as duas versões.