O ZimaOS tem agora uma OpenAPI documentada, mas a abordagem antiga de 2024, que consistia em chamar /v1/users/login e reutilizar o token de acesso devolvido, deve ser considerada uma técnica de autenticação de sessão, não um sistema de chaves de API permanentes. A IceWhale afirmou explicitamente nesse tópico que não eram suportados tokens permanentes.
A documentação OpenAPI atual centra-se em clientes gerados e endpoints de serviços, não numa interface de tokens de acesso pessoais. Para automatizações como o Home Assistant, mantenha a autenticação local, evite expor publicamente o endpoint de início de sessão e conceba a integração para voltar a autenticar-se quando um token de sessão expirar.
Utilize as especificações OpenAPI atuais
O guia OpenAPI atual do ZimaOS encaminha os programadores para o repositório OpenAPI da IceWhale e apresenta clientes gerados para armazenamento e outros serviços.
O endpoint de início de sessão histórico devolvia um token de acesso
No tópico original, o utilizador enviou com sucesso as credenciais por POST para /v1/users/login e encontrou um token de acesso na resposta. A IceWhale afirmou então que não eram suportados tokens permanentes.
Não utilize um token temporário codificado permanentemente
Um token de sessão pode expirar ou ser invalidado por alterações ao início de sessão ou à segurança. Armazene as credenciais ou o estado da sessão atualizado em segurança e trate explicitamente as falhas de autenticação.
Mantenha a API numa rede de confiança
Não redirecione portas para endpoints internos da API do ZimaOS a partir da Internet pública. Utilize a LAN, uma VPN ou a rede privada do ZimaClient para aceder primeiro ao servidor.
Atualize versões antigas do ZimaOS antes de desenvolver com as APIs de início de sessão
O ZimaOS tinha uma vulnerabilidade crítica de contorno da autenticação nas versões até à 1.5.0, inclusive, que afetava /v1/users/login; foi corrigida na versão 1.5.3. Desenvolva sempre com base numa versão estável atual.
O aviso de segurança sobre o início de sessão no ZimaOS documenta esse limite de segurança.
Utilize o princípio do menor privilégio no Home Assistant
Se estiver a recolher métricas de temperatura, CPU, energia ou discos, peça apenas os dados de que a sua integração precisa. Evite criar automações que também possam alterar utilizadores, armazenamento ou definições do sistema, salvo se for absolutamente necessário.
Conte com alterações às versões da API
O guia atual faz referência a caminhos de serviço com versões, como /v2/local_storage. Não parta do princípio de que todos os endpoints de 2024 continuarão a ser a interface recomendada indefinidamente; gere ou atualize os clientes com base nos esquemas OpenAPI atuais.
O guia de acesso privado apresenta um modelo de rede mais seguro.
Volte a autenticar-se ao receber respostas 401
Uma integração robusta deve tratar uma resposta HTTP 401 ou de sessão expirada como um sinal para obter uma nova sessão, em vez de voltar a tentar repetidamente com o mesmo token. Adicione um mecanismo de novas tentativas com limite para que uma falha no início de sessão não crie um ciclo interminável de pedidos.
Não inclua tokens nos registos
Os registos de depuração do Home Assistant, o histórico da shell, as capturas de ecrã e os repositórios Git são locais comuns de fuga de tokens. Oculte os cabeçalhos de autorização e as respostas de início de sessão em JSON antes de partilhar publicamente dados de diagnóstico.
Fixe o contrato da API de que depende
Se a sua integração usar clientes OpenAPI gerados, mantenha o esquema e a versão junto ao código e reveja as alterações a montante antes de voltar a gerar os clientes. Assim, é mais fácil perceber quando um endpoint ou formato de resposta mudou, em vez de as automações deixarem de funcionar sem aviso.
Perguntas frequentes
O ZimaOS pode gerar um token de API permanente?
A resposta da IceWhale no fórum dizia que os tokens permanentes não eram suportados, e a documentação pública atual não menciona uma interface para tokens de acesso pessoal.
Como foi obtido o antigo token de acesso?
O utilizador do fórum obteve-o após um pedido POST bem-sucedido a /v1/users/login.
Devo expor a API à Internet?
Não. Restrinja-a a uma rede de confiança ou privada e autentique-se através de um método atualmente suportado.
Posso criar uma integração com o Home Assistant?
Sim, mas tenha em conta a expiração dos tokens, as alterações de versão da API e o acesso com o mínimo de privilégios.
