ZimaOS dispose désormais d’une documentation OpenAPI, mais l’ancienne méthode de 2024, qui consistait à appeler /v1/users/login et à réutiliser le jeton d’accès renvoyé, doit être considérée comme une technique d’authentification par session, et non comme un système de clés API permanentes. Dans ce fil de discussion, IceWhale a explicitement indiqué que les jetons permanents n’étaient pas pris en charge.
La documentation OpenAPI actuelle porte principalement sur les clients générés et les points de terminaison des services, et non sur une interface de jetons d’accès personnels. Pour l’automatisation, par exemple avec Home Assistant, gardez l’authentification en local, évitez d’exposer publiquement le point de terminaison de connexion et concevez votre intégration pour qu’elle se réauthentifie à l’expiration d’un jeton de session.
Utilisez les spécifications OpenAPI actuelles
Le guide OpenAPI de ZimaOS actuel oriente les développeurs vers le dépôt OpenAPI d’IceWhale et présente des clients générés pour le stockage et d’autres services.
L’ancien point de terminaison de connexion renvoyait un jeton d’accès
Dans le fil de discussion d’origine, l’utilisateur a envoyé avec succès ses identifiants par POST à /v1/users/login et a trouvé un jeton d’accès dans la réponse. IceWhale a ensuite précisé que les jetons permanents n’étaient pas pris en charge.
Ne codez pas en dur un jeton temporaire et ne le réutilisez pas indéfiniment
Un jeton de session peut expirer ou être invalidé à la suite de changements liés à la connexion ou à la sécurité. Stockez les identifiants ou l’état de session actualisé de manière sécurisée et gérez explicitement les échecs d’authentification.
Gardez l’API sur un réseau de confiance
Ne redirigez pas les points de terminaison internes de l’API ZimaOS vers l’Internet public. Connectez-vous d’abord au serveur via le réseau local, un VPN ou le réseau privé ZimaClient.
Mettez à jour les anciennes versions de ZimaOS avant de développer avec les API de connexion
Une faille critique de contournement de l’authentification affectait ZimaOS jusqu’à la version 1.5.0 et concernait /v1/users/login ; elle a été corrigée dans la version 1.5.3. Développez toujours avec une version stable récente.
L’avis de sécurité sur la connexion à ZimaOS décrit cette limite de sécurité.
Appliquer le principe du moindre privilège dans Home Assistant
Si vous collectez des données de température, de processeur, d’alimentation ou de disque, ne demandez que celles dont votre intégration a besoin. Évitez de créer des automatisations capables aussi de modifier des utilisateurs, le stockage ou les paramètres système, sauf nécessité absolue.
Prévoyez des changements de version de l’API
Le guide actuel fait référence à des chemins de service versionnés, tels que /v2/local_storage. Ne supposez pas que tous les endpoints de 2024 resteront indéfiniment l’interface de référence ; générez ou mettez à jour les clients à partir des schémas OpenAPI actuels.
Le guide d’accès privé présente un modèle réseau plus sûr.
Réauthentifiez-vous en cas de réponse 401
Une intégration robuste doit considérer une réponse HTTP 401 ou indiquant une session expirée comme un signal pour obtenir une nouvelle session, plutôt que de réessayer sans cesse avec le même jeton. Prévoyez un mécanisme de nouvelle tentative limité pour éviter qu’une panne de connexion ne déclenche une boucle infinie de requêtes.
Ne mettez pas de jetons dans les journaux
Les journaux de débogage de Home Assistant, l’historique du shell, les captures d’écran et les dépôts Git sont autant d’endroits où des jetons peuvent fuiter. Masquez les en-têtes d’autorisation et les réponses JSON de connexion avant de partager publiquement des diagnostics.
Épinglez le contrat d’API dont vous dépendez
Si votre intégration utilise des clients OpenAPI générés, conservez le schéma et sa version avec votre code, et examinez les modifications en amont avant de régénérer les clients. Vous repérerez ainsi facilement les changements d’endpoint ou de format de réponse, au lieu de laisser vos automatisations tomber en panne sans avertissement.
FAQ
ZimaOS peut-il générer un jeton d’API permanent ?
La réponse d’IceWhale indiquait que les jetons permanents n’étaient pas pris en charge, et la documentation publique actuelle ne décrit aucune interface de jeton d’accès personnel.
Comment l’ancien jeton d’accès a-t-il été obtenu ?
L’utilisateur du forum l’a obtenu après une requête POST réussie vers /v1/users/login.
Dois-je exposer l’API à Internet ?
Non. Gardez-la sur un réseau privé et de confiance, et utilisez un flux d’authentification actuellement pris en charge.
Puis-je créer une intégration Home Assistant ?
Oui, mais concevez-la en tenant compte de l’expiration des jetons, des changements de version de l’API et du principe du moindre privilège.
