Uma ACL MQTT (lista de controle de acesso) é o conjunto de regras que um broker usa para decidir qual cliente autenticado pode publicar ou se inscrever em quais topics. Este artigo explica os conceitos, mostra como eles aparecem na configuração real de um broker usando o Mosquitto, descreve o que acontece quando um cliente é negado e apresenta padrões de design de topics que mantêm a autorização simples, seja com ACLs granulares, seja com isolamento no nível do tenant.
Autenticação versus autorização
As duas são fáceis de confundir, e os brokers as tratam em etapas diferentes:
- Autenticação responde "quem é você?". Ela acontece uma vez, no CONNECT, usando usuário e senha, um certificado de cliente ou um token. Veja autenticação MQTT com usuário e senha para os detalhes.
- Autorização responde "o que você pode fazer?". Ela é verificada em cada SUBSCRIBE e, dependendo do broker, em cada PUBLISH. As ACLs são a forma mais comum de expressá-la.
Um cliente autenticado sem regras de autorização normalmente pode ler e escrever tudo o que o seu broker ou tenant permite. As ACLs restringem isso por usuário, por client ID ou por papel.
O que uma regra de ACL MQTT contém
Seja qual for a sintaxe do broker, cada regra combina os mesmos elementos:
| Elemento | Exemplos |
|---|---|
| Sujeito | Um usuário, um client ID, um papel ou "todos" |
| Ação | Leitura (subscribe e recebimento), escrita (publish) ou ambas |
| Filtro de topic | factory/line1/#, devices/+/cmd, devices/%u/# |
| Decisão | Permitir ou negar |
As regras são comparadas com o topic de cada operação. Para assinaturas, muitos brokers verificam o próprio filtro solicitado, de modo que um cliente autorizado a ler devices/sensor-01/# não consegue passar uma assinatura mais ampla devices/# pela verificação.
Exemplo de ACL MQTT no Mosquitto
O Mosquitto é uma referência conveniente porque sua ACL baseada em arquivo é curta e legível. A autenticação e o arquivo de ACL são ativados no mosquitto.conf:
# mosquitto.conf
listener 8883
certfile /etc/mosquitto/certs/server.crt
keyfile /etc/mosquitto/certs/server.key
allow_anonymous false
password_file /etc/mosquitto/passwd
acl_file /etc/mosquitto/acl
O arquivo de ACL em si:
# /etc/mosquitto/acl
# Regras antes de qualquer linha "user" valem para clientes anônimos (nenhuma aqui)
# Um serviço de backend que lê toda a telemetria e envia comandos
user backend
topic read factory/+/+/telemetry/#
topic write factory/+/+/cmd/#
# Um dashboard que só pode ler
user dashboard
topic read factory/#
# Regras pattern valem para todos os usuários.
# %u = usuário, %c = client ID
pattern write factory/+/%c/telemetry/#
pattern read factory/+/%c/cmd/#
pattern write factory/+/%c/status
Com essas regras, um dispositivo que se conecta com o client ID cnc-07 pode publicar em factory/line2/cnc-07/telemetry/spindle e receber factory/line2/cnc-07/cmd/stop, mas não pode ler os comandos de outra máquina nem publicar como outra máquina. As regras pattern escalam para milhares de dispositivos sem uma entrada por dispositivo, e esse é o principal motivo para colocar o client ID no caminho do topic. O Mosquitto também suporta linhas topic deny e um plugin de segurança dinâmica com papéis e grupos; a documentação do Mosquitto cobre os dois.
Recarregue o broker depois de editar o arquivo e então teste:
# Permitido: cnc-07 publica a própria telemetria
mosquitto_pub -h localhost -p 8883 --cafile ca.crt -V mqttv5 \
-i cnc-07 -u cnc-07 -P "$PW" -t 'factory/line2/cnc-07/telemetry/spindle' -m 1200 -q 1
# Negado: cnc-07 publica como cnc-08
mosquitto_pub -h localhost -p 8883 --cafile ca.crt -V mqttv5 \
-i cnc-07 -u cnc-07 -P "$PW" -t 'factory/line2/cnc-08/telemetry/spindle' -m 1200 -q 1
O que acontece quando um cliente é negado
Operações negadas nem sempre produzem um erro óbvio, e é por isso que problemas de ACL são notoriamente difíceis de depurar.
| Operação | MQTT 3.1.1 | MQTT 5.0 |
|---|---|---|
| SUBSCRIBE negado | Return code 0x80 (falha) no SUBACK | Reason code 0x87 Not authorized no SUBACK |
| PUBLISH QoS 0 negado | Descartado silenciosamente | Descartado silenciosamente |
| PUBLISH QoS 1/2 negado | Geralmente confirmado e descartado | PUBACK/PUBREC pode trazer 0x87, depende do broker |
Dicas práticas de depuração:
- Sempre inspecione os códigos do SUBACK. Muitas bibliotecas os expõem em um callback; registre-os na inicialização.
- Use MQTT 5 e QoS 1 nos testes. Os reason codes nas confirmações tornam as negações visíveis.
- Teste com a identidade do dispositivo. Testar com uma conta de administrador não prova nada sobre as regras do dispositivo.
- Confira o log do broker. A maioria dos brokers registra publicações e assinaturas negadas em nível de depuração.
Projetando namespaces de topics para uma autorização simples
Boas ACLs começam com bons topics. Se a identidade e a direção ficam visíveis no caminho do topic, as regras se reduzem a alguns padrões. Se não ficam, você acaba com uma longa lista de casos especiais.
Coloque a identidade no caminho
Inclua o client ID ou o ID do dispositivo em um nível fixo: factory/<line>/<deviceId>/.... Regras pattern como %c só funcionam quando a identidade ocupa um nível inteiro do topic.
Separe as direções
Use ramos distintos para os dados que sobem e os comandos que descem: .../telemetry, .../status, .../cmd. Os dispositivos recebem escrita nos dois primeiros e leitura no terceiro.
Separe tenants ou clientes no topo
Se um broker atende vários clientes (por exemplo, várias plantas de uma mineradora ou cooperativas de uma fazenda), faça do cliente o primeiro nível: <tenant>/.... Assim as credenciais de cada tenant ficam limitadas a uma subárvore.
Mantenha os dados compartilhados em um ramo com nome claro
Configurações transmitidas a todos os dispositivos ficam em broadcast/... ou config/..., com acesso somente leitura para os dispositivos.
O artigo exemplos de hierarquia de topics MQTT mostra árvores completas construídas com esses princípios.
Checklist de design de ACL
- Negue por padrão; permita apenas o que cada papel precisa.
- Dê aos dispositivos escrita na própria telemetria e no próprio status, leitura nos próprios comandos e nada mais.
- Dê aos dashboards acesso somente leitura.
- Dê aos serviços de backend escrita nos ramos de comandos e audite quem tem essas credenciais.
- Nunca conceda
#a uma credencial de dispositivo. - Mantenha o arquivo de regras ou as definições de papéis no controle de versão e revise as mudanças.
- Teste cada papel com as credenciais reais após cada mudança.
Autorização no ConnectMQ
O ConnectMQ não oferece ACLs por topic. O isolamento no ConnectMQ funciona no nível do tenant: o tráfego do broker de cada cliente é isolado de todos os outros tenants, as credenciais são geradas por broker e os client IDs são vinculados ao usuário e à senha emitidos, de modo que um cliente não pode assumir a identidade de outro. Cotas por plano, proteção contra flood e bloqueio de IP após repetidas falhas de login limitam o que um cliente mal-comportado pode fazer.
O que isso significa para o design:
- Use brokers separados como fronteira de segurança. Se dois grupos de clientes nunca podem ver os dados um do outro, coloque-os em brokers diferentes em vez de depender de regras de topic. Um plano Dedicated oferece um cluster isolado quando essa fronteira também precisa ser física.
- Mantenha clientes não confiáveis fora do broker. Usuários de navegador e terceiros devem falar com o seu backend, que guarda as credenciais do broker e decide o que publicar em nome deles.
- Projete os topics como se as ACLs pudessem vir depois. Identidade no caminho e ramos de comandos separados não custam nada agora e mantêm as opções em aberto caso você mova parte do sistema para um broker com regras de topic.
- Valide os comandos no dispositivo. Um dispositivo deve verificar se um comando está bem formado e é esperado antes de agir, independentemente de como o broker o autoriza.
Essa combinação de isolamento de tenants e disciplina de topics atende bem muitas frotas. Se o seu projeto precisa de restrições de topic por dispositivo dentro de um único namespace compartilhado, planeje um broker com suporte a ACLs por topic para essa parte do sistema. Para o panorama geral, veja boas práticas de segurança MQTT e o MQTT é seguro?.
Comece a usar o ConnectMQ
Execute seus dispositivos em um broker MQTT gerenciado com isolamento de tenants, TLS, credenciais geradas vinculadas a client IDs e bloqueio de IP após falhas de login. Crie um broker Serverless gratuito em app.connectmq.com, sem cartão de crédito, e prototipe primeiro os designs de topics no servidor MQTT público (gratuito), que serve para testes e protótipos, não para dados de produção.
Perguntas frequentes
O que é uma ACL MQTT?
É uma lista de regras que diz ao broker quais usuários ou clientes podem publicar ou se inscrever em quais filtros de topic. Ela é verificada depois que o cliente se autenticou.
O ConnectMQ suporta ACLs por topic?
Não. O ConnectMQ isola os tenants entre si e vincula os client IDs às credenciais de usuário e senha emitidas, mas não aplica regras de leitura e escrita por topic dentro de um broker.
Por que minha publicação negada não retorna erro?
No MQTT 3.1.1 não há como o broker informar uma publicação negada, então ela é descartada silenciosamente. Brokers MQTT 5 podem retornar o reason code 0x87 nas confirmações de QoS 1 e 2.
As regras de ACL devem usar o usuário ou o client ID?
Use o identificador que for único por dispositivo e que o cliente não possa escolher livremente. Se o broker vincula client IDs a credenciais, qualquer um funciona; caso contrário, prefira o usuário.
