O ZimaOS tem agora uma OpenAPI documentada, mas o método antigo de 2024, que consistia em chamar /v1/users/login e reutilizar o token de acesso devolvido, deve ser tratado como uma técnica de autenticação de sessão, e não como um sistema permanente de chaves de API. A IceWhale afirmou explicitamente nessa discussão que os tokens permanentes não eram suportados.
A documentação atual da OpenAPI centra-se em clientes gerados e endpoints de serviços, e 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 sua integração para voltar a autenticar-se quando o token de sessão expirar.
Utilize as especificações OpenAPI atuais
O guia OpenAPI do ZimaOS atual 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
Na discussão original, o utilizador fez POST das credenciais para /v1/users/login e encontrou um token de acesso na resposta. A IceWhale afirmou então que os tokens permanentes não eram suportados.
Não mantenha um token temporário codificado indefinidamente
Um token de sessão pode expirar ou ser invalidado por alterações de início de sessão ou de segurança. Armazene as credenciais ou o estado da sessão atualizado de forma segura e trate explicitamente as falhas de autenticação.
Mantenha a API numa rede de confiança
Não encaminhe através de port forwarding os endpoints internos da API do ZimaOS para a Internet pública. Utilize a LAN, uma VPN ou a rede privada do ZimaClient para chegar 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; a vulnerabilidade foi corrigida na versão 1.5.3. Desenvolva sempre com base numa versão estável atual.
O aviso de segurança relativo ao início de sessão do 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 disco, solicite apenas os dados de que a sua integração necessita. Evite criar automatizações que também possam alterar utilizadores, armazenamento ou definições do sistema, exceto quando for absolutamente necessário.
Conte com alterações nas versões da API
O guia atual faz referência a caminhos de serviço versionados, como /v2/local_storage. Não parta do princípio de que todos os endpoints de 2024 continuarão indefinidamente a ser a interface preferencial; gere ou atualize os clientes a partir dos esquemas OpenAPI atuais.
O guia de acesso privado apresenta o modelo de rede mais seguro.
Trate as respostas 401 voltando a autenticar-se
Uma integração robusta deve tratar uma resposta HTTP 401 ou de sessão expirada como um sinal para obter uma sessão nova, em vez de repetir continuamente o mesmo token. Adicione uma tentativa limitada para que uma falha de início de sessão não crie um ciclo infinito de pedidos.
Não coloque 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 onde os tokens podem ficar expostos. Oculte os cabeçalhos de autorização e as respostas JSON de início de sessão antes de partilhar diagnósticos publicamente.
Fixe o contrato da API de que depende
Se a sua integração utilizar clientes OpenAPI gerados, mantenha o esquema e a versão juntamente com o seu código e reveja as alterações a montante antes de voltar a gerar os clientes. Assim, torna-se evidente quando um endpoint ou o formato de uma resposta mudou, em vez de as automatizações deixarem de funcionar silenciosamente.
FAQ
O ZimaOS pode gerar um token de API permanente?
A resposta da IceWhale na fonte afirmava que os tokens permanentes não eram suportados, e a documentação pública atual não documenta uma interface de tokens de acesso pessoais.
Como era obtido o antigo token de acesso?
O utilizador do fórum obteve-o após um POST bem-sucedido para /v1/users/login.
Devo expor a API à Internet?
Não. Mantenha-a numa rede privada/de confiança e autentique-se através de um fluxo atual suportado.
Posso criar uma integração para o Home Assistant?
Sim, mas conceba-a tendo em conta a expiração dos tokens, as alterações de versão da API e o acesso com o menor privilégio possível.
