Client operations for token-based authentication - ApsaraMQ for MQTT: Central de Documentação do Alibaba Cloud

Fluxo de autenticação

A autenticação baseada em token segue esta sequência:

Sua aplicação solicita tokens ao serviço de tokens do ApsaraMQ for MQTT e especifica os recursos e os tipos de permissão (leitura, escrita ou ambos).
O cliente MQTT conecta-se ao broker com os dados do token nos campos Username e Password do pacote CONNECT.
O broker verifica o token e concede acesso aos recursos especificados.
Durante a sessão, o cliente atualiza tokens publicando em um tópico do sistema, e o broker envia notificações sobre expiração ou invalidação de tokens.

Tipos de token

Cada cliente do ApsaraMQ for MQTT mantém um token por tipo e usa um ou mais tipos simultaneamente.

Identificador de tipo	Permissão	Descrição
R	Somente leitura	Concede permissão de leitura para os recursos especificados
W	Somente escrita	Concede permissão de escrita para os recursos especificados
RW	Leitura e escrita	Concede permissões de leitura e escrita para os recursos especificados

Parâmetros de conexão

Para conectar-se com autenticação baseada em token, defina os campos Username e Password no pacote CONNECT do MQTT conforme descrito abaixo.

Username

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

Componente	Descrição
`Token`	A string literal `Token`, que indica o modo de autenticação baseada em token
`<AccessKey ID>`	Seu AccessKey ID da Alibaba Cloud
`<Instance ID>`	O ID da sua instância do ApsaraMQ for MQTT

Exemplo:

Para um cliente com ID GID_Test@@@0001, ID da instância mqtt-xxxxx e AccessKey ID YYYYY:

Token|YYYYY|mqtt-xxxxx

Password

Formato: Pares de tipo e conteúdo de token concatenados com barras verticais (|). Vários tipos de token podem aparecer em qualquer ordem.

Exemplos:

Token único: Se o cliente possui um token de somente leitura 123, defina o Password como:
```
  R|123
```
Múltiplos tokens: Caso o cliente tenha um token de somente leitura 123 e um token de somente escrita abcd, configure o Password da seguinte forma:
```
  R|123|W|abcd
```

Importante

Todos os tokens no campo Password devem ser válidos. Se algum token for inválido, o broker poderá rejeitar a conexão.

Atualize tokens sem desconectar

Por padrão, para rotacionar um token, desconecte o cliente e reconecte-se com o novo token. Para evitar a desconexão, publique uma mensagem de atualização de token no tópico do sistema $SYS/uploadToken. O broker substitui o token na sessão sem encerrar a conexão.

Procedimento de atualização

Publique uma mensagem JSON em $SYS/uploadToken com o conteúdo do novo token.
Aguarde a resposta PUBACK antes de executar qualquer operação de publicação ou assinatura. Se o cliente prosseguir sem esperar, o broker ainda poderá autenticar com o token antigo, causando falha de autenticação e desconexão.
Atualize a configuração local do token para que o cliente use o novo token na próxima reconexão.

Formato da mensagem

Tópico: $SYS/uploadToken

Payload: String JSON com os seguintes campos:

Parâmetro	Tipo	Obrigatório	Descrição
token	String	Sim	A string do novo token
type	String	Sim	Tipo de token: `R`, `W` ou `RW`. Um tipo inválido causa erro de verificação de permissão.

Exemplo de payload:

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

Resposta: Uma mensagem PUBACK padrão.

Importante

Sempre atualize a configuração local do token após uma atualização bem-sucedida. Caso contrário, o cliente poderá usar os dados do token antigo durante a próxima reconexão.

Notificações de expiração de token

O broker do ApsaraMQ for MQTT envia avisos de expiração aos clientes por meio do tópico do sistema $SYS/tokenExpireNotice. Nenhuma assinatura é necessária — o broker entrega essas notificações diretamente.

Tópico: $SYS/tokenExpireNotice

Payload: String JSON com os seguintes campos:

Parâmetro	Tipo	Descrição
expireTime	Long	Tempo de expiração do token como um timestamp Unix em milissegundos
type	String	Tipo de token: `R`, `W` ou `RW`

Comportamento da notificação

Geralmente, o broker envia uma notificação aproximadamente 5 minutos antes da expiração do token.
A entrega não é garantida. Não dependa exclusivamente dessas notificações para gerenciar o ciclo de vida do token.
Após receber uma notificação, solicite um novo token e atualize-o prontamente para evitar falhas nas mensagens.

Notificações de invalidação de token

Quando o broker detecta um erro de verificação de token, ele envia uma notificação de erro ao cliente por meio do tópico do sistema $SYS/tokenInvalidNotice e, em seguida, desconecta o cliente. Nenhuma assinatura é necessária.

Tópico: $SYS/tokenInvalidNotice

Payload: String JSON com os seguintes campos:

Parâmetro	Tipo	Descrição
code	int	Código de erro que identifica o tipo de falha na verificação do token
type	String	Tipo de token: `R`, `W` ou `RW`

Códigos de erro

Código	Descrição
1	O token é falsificado e não pode ser analisado
2	O token expirou
3	O token foi revogado
4	O recurso e o token não correspondem
5	O tipo de permissão e o token não correspondem
8	A assinatura é inválida
-1	A permissão da conta é inválida

Comportamento de desconexão

Quando o broker encontra um erro de verificação de token:

A autenticação falha.
O broker envia o código de erro ao cliente por meio de $SYS/tokenInvalidNotice.
O broker desconecta o cliente.

Utilize o código de erro para identificar a causa raiz e tomar medidas corretivas antes de se reconectar.

Melhores práticas

Use tokens de curta duração. Defina um período de validade razoável para os tokens a fim de limitar o impacto de vazamentos.
Ative o TLS. Criptografe as conexões do cliente para evitar a interceptação de tokens durante a transmissão.
Lide com a expiração proativamente. Implemente a lógica de renovação de token no seu cliente em vez de depender apenas das notificações de expiração do broker, pois a entrega não é garantida.
Armazene credenciais com segurança. Recupere seu AccessKey ID de variáveis de ambiente ou de um gerenciador de segredos em vez de codificá-lo diretamente na aplicação.
Mantenha os tokens locais e do broker sincronizados. Após atualizar um token via $SYS/uploadToken, sempre atualize a configuração local para evitar o uso de tokens obsoletos na reconexão.