ZimaOS ma teraz udokumentowane OpenAPI, ale stary schemat z 2024 roku, polegający na wywołaniu /v1/users/login i ponownym używaniu zwróconego tokenu dostępu, należy traktować jako technikę uwierzytelniania sesji, a nie system stałych kluczy API. IceWhale wyraźnie poinformowało w tamtym wątku, że stałe tokeny nie były obsługiwane.
Aktualna dokumentacja OpenAPI koncentruje się na generowanych klientach i punktach końcowych usług, a nie na interfejsie do tworzenia osobistych tokenów dostępu. W przypadku automatyzacji, takiej jak Home Assistant, uwierzytelnianie powinno pozostać lokalne, punkt końcowy logowania nie powinien być publicznie dostępny, a integracja powinna ponownie uwierzytelniać się po wygaśnięciu tokenu sesji.
Korzystaj z aktualnych specyfikacji OpenAPI
Aktualny przewodnik po OpenAPI ZimaOS kieruje deweloperów do repozytorium OpenAPI firmy IceWhale i pokazuje generowane klienty dla pamięci masowej oraz innych usług.
Historyczny punkt końcowy logowania zwracał token dostępu
W wątku źródłowym użytkownik pomyślnie wysłał dane uwierzytelniające metodą POST do /v1/users/login i znalazł token dostępu w odpowiedzi. IceWhale poinformowało następnie, że stałe tokeny nie były obsługiwane.
Nie używaj tymczasowego tokenu bezterminowo
Token sesji może wygasnąć lub zostać unieważniony wskutek zmian logowania albo ustawień zabezpieczeń. Bezpiecznie przechowuj dane uwierzytelniające lub odświeżony stan sesji i jawnie obsługuj błędy uwierzytelniania.
Utrzymuj API w zaufanej sieci
Nie przekierowuj wewnętrznych punktów końcowych API ZimaOS do publicznego internetu. Najpierw połącz się z serwerem przez LAN, VPN lub prywatną sieć ZimaClient.
Zaktualizuj starsze kompilacje ZimaOS przed rozpoczęciem pracy z API logowania
W ZimaOS występował krytyczny problem umożliwiający obejście uwierzytelniania w wersjach do 1.5.0 włącznie, dotyczący /v1/users/login; został on naprawiony w wersji 1.5.3. Zawsze twórz rozwiązania w oparciu o aktualne stabilne wydanie.
Poradnik bezpieczeństwa logowania ZimaOS opisuje tę granicę bezpieczeństwa.
Stosuj zasadę minimalnych uprawnień w Home Assistant
Jeśli zbierasz temperaturę, użycie procesora, zużycie energii lub dane o dyskach, żądaj tylko informacji potrzebnych integracji. Unikaj tworzenia automatyzacji, które mogą również modyfikować użytkowników, pamięć masową lub ustawienia systemowe, chyba że jest to absolutnie konieczne.
Zakładaj zmiany wersji API
Aktualny przewodnik odwołuje się do wersjonowanych ścieżek usług, takich jak /v2/local_storage. Nie zakładaj, że każdy punkt końcowy z 2024 roku na zawsze pozostanie zalecanym interfejsem; generuj lub aktualizuj klientów na podstawie aktualnych schematów OpenAPI.
Przewodnik po prywatnym dostępie przedstawia bezpieczniejszy model sieciowy.
Obsługuj odpowiedzi 401, ponownie się uwierzytelniając
Solidna integracja powinna traktować odpowiedź HTTP 401 lub informację o wygaśnięciu sesji jako sygnał do uzyskania nowej sesji, zamiast wielokrotnie ponawiać żądanie z tym samym tokenem. Dodaj ograniczoną ścieżkę ponawiania, aby awaria logowania nie powodowała nieskończonej pętli żądań.
Nie umieszczaj tokenów w logach
Logi debugowania Home Assistant, historia powłoki, zrzuty ekranu i repozytoria Git to częste miejsca wycieku tokenów. Przed publicznym udostępnieniem diagnostyki usuń lub zamaskuj nagłówki autoryzacji i odpowiedzi JSON logowania.
Przypnij używany kontrakt API
Jeśli integracja korzysta z generowanych klientów OpenAPI, przechowuj schemat i wersję razem z kodem oraz analizuj zmiany wprowadzane upstream przed ponownym wygenerowaniem klienta. Dzięki temu będzie jasne, kiedy zmienił się punkt końcowy lub struktura odpowiedzi, zamiast dopuścić do cichego przerwania automatyzacji.
FAQ
Czy ZimaOS może wygenerować stały token API?
W źródłowej odpowiedzi IceWhale poinformowano, że stałe tokeny nie były obsługiwane, a aktualna publiczna dokumentacja nie opisuje interfejsu osobistych tokenów dostępu.
Jak uzyskiwano dawny token dostępu?
Użytkownik forum uzyskał go po pomyślnym wysłaniu żądania POST do /v1/users/login.
Czy należy udostępniać API w internecie?
Nie. Utrzymuj je w zaufanej, prywatnej sieci i korzystaj z aktualnie obsługiwanego sposobu uwierzytelniania.
Czy mogę zbudować integrację z Home Assistant?
Tak, ale projektuj ją z uwzględnieniem wygasania tokenów, zmian wersji API i dostępu zgodnego z zasadą minimalnych uprawnień.
