ZimaOS dispone ora di una documentazione OpenAPI, ma il metodo usato nel 2024, che consisteva nel chiamare /v1/users/login e riutilizzare il token di accesso restituito, va considerato una tecnica di autenticazione basata sulla sessione, non un sistema di chiavi API permanenti. In quel thread, IceWhale ha dichiarato esplicitamente 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 le automazioni, come Home Assistant, mantieni l’autenticazione in locale, evita di esporre l’endpoint di accesso pubblicamente e progetta l’integrazione in modo che effettui nuovamente l’autenticazione alla scadenza del token di sessione.
Usa le specifiche OpenAPI aggiornate
L’attuale guida OpenAPI di ZimaOS rimanda gli sviluppatori al repository OpenAPI di IceWhale e mostra i client generati per lo storage e altri servizi.
L’endpoint di accesso storico restituiva un token di accesso
Nel thread originale, l’utente è riuscito a inviare credenziali con una richiesta 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 usare per sempre un token temporaneo codificato nel codice
Un token di sessione può scadere o essere invalidato da modifiche all’accesso o alla sicurezza. Conserva in modo sicuro le credenziali o lo stato della sessione aggiornata e gestisci esplicitamente gli errori di autenticazione.
Mantieni l’API su una rete attendibile
Non configurare il port forwarding degli endpoint API interni di ZimaOS verso Internet. Per raggiungere prima il server, usa la rete LAN, una VPN o la rete privata di ZimaClient.
Aggiorna le versioni obsolete di ZimaOS prima di sviluppare con le API di accesso
ZimaOS presentava una vulnerabilità critica di bypass dell’autenticazione nelle versioni fino alla 1.5.0, che interessava /v1/users/login; è stata corretta nella versione 1.5.3. Sviluppa sempre usando una versione stabile aggiornata.
L’avviso sulla sicurezza dell’accesso a ZimaOS documenta questo confine di sicurezza.
Usa i privilegi minimi in Home Assistant
Se raccogli metriche di 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, a meno che non sia assolutamente necessario.
Considera che le versioni dell’API possono cambiare
La guida attuale fa riferimento a percorsi di servizio con versione, come /v2/local_storage. Non dare per scontato che tutti gli endpoint del 2024 restino a tempo indeterminato l’interfaccia preferita; genera o aggiorna i client a partire dagli schemi OpenAPI attuali.
La guida all’accesso privato illustra un modello di rete più sicuro.
Gestisci le risposte 401 riautenticandoti
Un’integrazione robusta dovrebbe trattare una risposta HTTP 401 o una sessione scaduta come un segnale per ottenere una nuova sessione, anziché riprovare ripetutamente con lo stesso token. Aggiungi un meccanismo di tentativi limitati, così un’interruzione del servizio di 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, gli screenshot e i repository Git sono luoghi comuni in cui possono finire i token. Prima di condividere pubblicamente informazioni diagnostiche, oscura gli header di autorizzazione e le risposte JSON di accesso.
Fissa il contratto API da cui dipendi
Se la tua integrazione usa client OpenAPI generati, conserva lo schema e la versione insieme al codice e controlla le modifiche upstream prima di rigenerarli. In questo modo, eventuali modifiche a un endpoint o alla struttura di una risposta saranno evidenti, anziché causare malfunzionamenti silenziosi nelle automazioni.
FAQ
ZimaOS può generare un token API permanente?
La risposta di IceWhale all’epoca affermava che i token permanenti non erano supportati e la documentazione pubblica attuale non descrive un’interfaccia per i token di accesso personali.
Come è stato ottenuto il vecchio token di accesso?
L’utente del forum l’ha ottenuto dopo una richiesta POST riuscita a /v1/users/login.
Dovrei esporre l’API a Internet?
No. Mantienila su una rete affidabile e privata e autentica tramite un flusso attualmente supportato.
Posso creare un’integrazione per Home Assistant?
Sì, ma progetta tenendo conto della scadenza dei token, delle modifiche alle versioni dell’API e dell’accesso con privilegi minimi.
