ZimaOS verfügt inzwischen über eine dokumentierte OpenAPI, aber das alte Muster von 2024, /v1/users/login aufzurufen und das zurückgegebene Zugriffstoken wiederzuverwenden, sollte als Sitzungsauthentifizierung und nicht als dauerhaftes API-Schlüsselsystem betrachtet werden. IceWhale erklärte in diesem Thread ausdrücklich, dass dauerhafte Tokens nicht unterstützt wurden.
Die aktuelle OpenAPI-Dokumentation konzentriert sich auf generierte Clients und Service-Endpunkte statt auf eine Benutzeroberfläche für persönliche Zugriffstokens. Für Automatisierungen wie Home Assistant sollten Sie die Authentifizierung lokal halten, den Login-Endpunkt nicht öffentlich zugänglich machen und Ihre Integration so gestalten, dass sie sich erneut authentifiziert, wenn ein Sitzungstoken abläuft.
Verwenden Sie die aktuellen OpenAPI-Spezifikationen
Der aktuelle ZimaOS-OpenAPI-Leitfaden verweist Entwickler auf das OpenAPI-Repository von IceWhale und zeigt generierte Clients für Speicher und andere Dienste.
Der historische Login-Endpunkt gab ein Zugriffstoken zurück
Im ursprünglichen Thread sendete der Benutzer erfolgreich per POST Zugangsdaten an /v1/users/login und fand in der Antwort ein Zugriffstoken. IceWhale erklärte anschließend, dass dauerhafte Tokens nicht unterstützt wurden.
Speichern Sie ein temporäres Token nicht dauerhaft
Ein Sitzungstoken kann ablaufen oder durch Änderungen an Login oder Sicherheit ungültig werden. Speichern Sie Zugangsdaten oder den aktualisierten Sitzungsstatus sicher und behandeln Sie Authentifizierungsfehler ausdrücklich.
Halten Sie die API in einem vertrauenswürdigen Netzwerk
Leiten Sie interne ZimaOS-API-Endpunkte nicht per Portweiterleitung ins öffentliche Internet weiter. Verwenden Sie zunächst LAN, VPN oder ZimaClient bzw. ein privates Netzwerk, um den Server zu erreichen.
Aktualisieren Sie alte ZimaOS-Versionen vor der Entwicklung mit Login-APIs
ZimaOS wies bis einschließlich Version 1.5.0 eine kritische Umgehung der Authentifizierung auf, die /v1/users/login betraf; sie wurde in Version 1.5.3 behoben. Entwickeln Sie immer mit einer aktuellen stabilen Version.
Die Sicherheitswarnung zum ZimaOS-Login dokumentiert diese Sicherheitsgrenze.
Verwenden Sie in Home Assistant das Prinzip der geringsten Rechte
Wenn Sie Temperatur-, CPU-, Strom- oder Festplattenmetriken erfassen, fordern Sie nur die Daten an, die Ihre Integration benötigt. Vermeiden Sie Automatisierungen, die zusätzlich Benutzer, Speicher oder Systemeinstellungen ändern können, sofern dies nicht unbedingt erforderlich ist.
Rechnen Sie mit Änderungen an API-Versionen
Der aktuelle Leitfaden verweist auf versionierte Servicepfade wie /v2/local_storage. Gehen Sie nicht davon aus, dass jeder Endpunkt von 2024 dauerhaft die bevorzugte Schnittstelle bleibt; generieren oder aktualisieren Sie Clients anhand der aktuellen OpenAPI-Schemas.
Der Leitfaden für privaten Zugriff beschreibt das sicherere Netzwerkmodell.
Behandeln Sie 401-Antworten mit erneuter Authentifizierung
Eine robuste Integration sollte eine HTTP-401- oder abgelaufene Sitzungsantwort als Signal verstehen, eine neue Sitzung anzufordern, statt dasselbe Token wiederholt zu verwenden. Fügen Sie einen begrenzten Wiederholungsmechanismus hinzu, damit ein Login-Ausfall keine Endlosschleife von Anfragen erzeugt.
Schreiben Sie Tokens nicht in Protokolle
Debug-Protokolle von Home Assistant, die Shell-Historie, Screenshots und Git-Repositories sind häufige Orte, an denen Tokens versehentlich offengelegt werden. Schwärzen Sie Autorisierungs-Header und JSON-Loginantworten, bevor Sie Diagnosedaten öffentlich teilen.
Fixieren Sie den API-Vertrag, von dem Sie abhängen
Wenn Ihre Integration generierte OpenAPI-Clients verwendet, bewahren Sie das Schema und die Version zusammen mit Ihrem Code auf und prüfen Sie Änderungen am Upstream, bevor Sie den Client neu generieren. So wird deutlich, wenn sich ein Endpunkt oder die Form einer Antwort geändert hat, statt dass Automatisierungen unbemerkt ausfallen.
FAQ
Kann ZimaOS ein dauerhaftes API-Token generieren?
In der ursprünglichen Antwort von IceWhale hieß es, dass dauerhafte Tokens nicht unterstützt wurden; auch die aktuellen öffentlichen Dokumentationen beschreiben keine Benutzeroberfläche für persönliche Zugriffstokens.
Wie wurde das alte Zugriffstoken abgerufen?
Der Forenbenutzer erhielt es nach einem erfolgreichen POST an /v1/users/login.
Sollte ich die API dem Internet zugänglich machen?
Nein. Halten Sie sie in einem vertrauenswürdigen privaten Netzwerk und verwenden Sie einen aktuell unterstützten Authentifizierungsablauf.
Kann ich eine Home-Assistant-Integration entwickeln?
Ja, aber planen Sie den Ablauf für Token-Ablauf, Änderungen der API-Version und Zugriffe mit den geringstmöglichen Berechtigungen.
