ZimaOS ora dispone di un’OpenAPI documentata, ma il vecchio metodo del 2024, che consisteva nel chiamare /v1/users/login e riutilizzare il token di accesso restituito, deve essere considerato una tecnica di autenticazione della sessione, non un sistema permanente di chiavi API. IceWhale ha dichiarato esplicitamente in quella discussione che i token permanenti non erano supportati.
La documentazione OpenAPI attuale si concentra sui client generati e sugli endpoint dei servizi, non su un’interfaccia per i token di accesso personali. Per l’automazione, ad esempio con Home Assistant, mantieni l’autenticazione locale, evita di esporre pubblicamente l’endpoint di accesso e progetta l’integrazione in modo che effettui nuovamente l’autenticazione quando il token di sessione scade.
Usa le specifiche OpenAPI attuali
L’attuale guida OpenAPI di ZimaOS indirizza gli sviluppatori al repository OpenAPI di IceWhale e mostra client generati per l’archiviazione e altri servizi.
L’endpoint di accesso storico restituiva un token di accesso
Nella discussione originale, l’utente ha inviato correttamente le credenziali tramite POST a /v1/users/login e ha trovato un token di accesso nella risposta. IceWhale ha poi dichiarato che i token permanenti non erano supportati.
Non conservare per sempre un token temporaneo
Un token di sessione può scadere o essere invalidato da modifiche all’accesso o alla sicurezza. Archivia in modo sicuro le credenziali o lo stato aggiornato della sessione e gestisci esplicitamente gli errori di autenticazione.
Mantieni l’API su una rete attendibile
Non inoltrare gli endpoint API interni di ZimaOS verso Internet. Usa la LAN, una VPN o ZimaClient/una rete privata per raggiungere prima il server.
Aggiorna le versioni obsolete di ZimaOS prima di sviluppare sulle API di accesso
ZimaOS presentava una vulnerabilità critica di bypass dell’autenticazione nelle versioni fino alla 1.5.0, che interessava /v1/users/login; il problema è stato corretto nella versione 1.5.3. Sviluppa sempre sulla versione stabile più recente.
L’avviso di sicurezza sull’accesso a ZimaOS documenta questo limite di sicurezza.
Applica il principio del privilegio minimo in Home Assistant
Se raccogli metriche relative a temperatura, CPU, alimentazione o disco, richiedi solo i dati necessari alla tua integrazione. Evita di creare automazioni che possano anche modificare utenti, archiviazione o impostazioni di sistema, salvo assoluta necessità.
Prevedi modifiche alle versioni API
La guida attuale fa riferimento a percorsi dei servizi versionati, come /v2/local_storage. Non dare per scontato che ogni endpoint del 2024 rimanga indefinitamente l’interfaccia preferita; genera o aggiorna i client a partire dagli schemi OpenAPI attuali.
La guida all’accesso privato illustra il modello di rete più sicuro.
Gestisci le risposte 401 effettuando nuovamente l’autenticazione
Un’integrazione robusta dovrebbe considerare una risposta HTTP 401 o una sessione scaduta come un segnale per ottenere una nuova sessione, invece di riprovare continuamente con lo stesso token. Aggiungi un percorso di tentativi limitato, così un’interruzione dell’accesso non crea un ciclo infinito di richieste.
Non inserire i token nei log
I log di debug di Home Assistant, la cronologia della shell, le schermate e i repository Git sono luoghi comuni in cui i token possono essere divulgati. Oscura gli header di autorizzazione e le risposte JSON di accesso prima di condividere pubblicamente i dati diagnostici.
Blocca il contratto API da cui dipendi
Se la tua integrazione utilizza client OpenAPI generati, conserva lo schema e la versione insieme al codice e controlla le modifiche upstream prima di rigenerare i client. In questo modo è evidente quando cambia un endpoint o la struttura di una risposta, invece di interrompere silenziosamente le automazioni.
Domande frequenti
ZimaOS può generare un token API permanente?
La risposta originale di IceWhale affermava che i token permanenti non erano supportati e la documentazione pubblica attuale non descrive un’interfaccia per i token di accesso personali.
Come veniva ottenuto il vecchio token di accesso?
L’utente del forum lo otteneva dopo un POST riuscito a /v1/users/login.
Devo esporre l’API su Internet?
No. Mantienila su una rete attendibile e privata e utilizza un flusso supportato attualmente per l’autenticazione.
Posso creare un’integrazione per Home Assistant?
Sì, ma progettala tenendo conto della scadenza dei token, delle modifiche alle versioni API e dell’accesso con privilegi minimi.
