ZimaOS ma teraz udokumentowane OpenAPI, ale stary sposób z 2024 roku, polegający na wywołaniu /v1/users/login i ponownym używaniu otrzymanego tokenu dostępu, należy traktować jako metodę uwierzytelniania sesji, a nie system stałych kluczy API. IceWhale wyraźnie poinformowało w tym wątku, że stałe tokeny nie były obsługiwane.
Aktualna dokumentacja OpenAPI skupia się na wygenerowanych klientach i endpointach usług, a nie na interfejsie do tworzenia osobistych tokenów dostępu. W przypadku automatyzacji, takiej jak Home Assistant, korzystaj z lokalnego uwierzytelniania, nie udostępniaj publicznie endpointu logowania i zaprojektuj integrację tak, aby ponownie się uwierzytelniała po wygaśnięciu tokenu sesji.
Korzystaj z aktualnych specyfikacji OpenAPI
Aktualny przewodnik OpenAPI ZimaOS odsyła programistów do repozytorium OpenAPI IceWhale i przedstawia wygenerowanych klientów do obsługi pamięci masowej oraz innych usług.
Historyczny endpoint logowania zwracał token dostępu
W wątku źródłowym użytkownik pomyślnie wysłał dane logowania metodą POST do /v1/users/login i znalazł token dostępu w odpowiedzi. IceWhale poinformowało następnie, że stałe tokeny nie są obsługiwane.
Nie używaj bezterminowo tymczasowego tokenu wpisanego na stałe w kodzie
Token sesji może wygasnąć lub zostać unieważniony w wyniku zmian dotyczących logowania lub bezpieczeństwa. Przechowuj dane logowania lub odświeżony stan sesji w bezpieczny sposób i jawnie obsługuj błędy uwierzytelniania.
Korzystaj z API w zaufanej sieci
Nie przekierowuj portów wewnętrznych endpointów API ZimaOS do publicznego internetu. Najpierw połącz się z serwerem przez LAN, VPN lub prywatną sieć ZimaClient.
Zaktualizuj stare wersje ZimaOS, zanim zaczniesz korzystać z interfejsów API logowania
W wersjach ZimaOS do 1.5.0 włącznie występowała krytyczna luka umożliwiająca obejście uwierzytelniania, która dotyczyła endpointu /v1/users/login; została załatana w wersji 1.5.3. Zawsze twórz rozwiązania z użyciem aktualnego stabilnego wydania.
Komunikat dotyczący bezpieczeństwa logowania do ZimaOS opisuje tę granicę bezpieczeństwa.
Stosuj zasadę najmniejszych uprawnień w Home Assistant
Jeśli zbierasz dane o temperaturze, procesorze, poborze mocy lub dyskach, żądaj tylko danych potrzebnych integracji. Unikaj tworzenia automatyzacji, która może także modyfikować użytkowników, pamięć masową lub ustawienia systemowe, chyba że jest to absolutnie konieczne.
Uwzględnij 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 nadal będzie preferowanym interfejsem; generuj lub aktualizuj klientów na podstawie aktualnych schematów OpenAPI.
Przewodnik po dostępie prywatnym opisuje bezpieczniejszy model sieci.
Po odpowiedzi 401 ponownie się uwierzytelnij
Solidna integracja powinna traktować odpowiedź HTTP 401 lub informację o wygaśnięciu sesji jako sygnał do uzyskania nowej sesji, zamiast wielokrotnie ponawiać próbę z tym samym tokenem. Dodaj ograniczoną liczbę ponowień, aby awaria logowania nie powodowała niekończącej się pętli żądań.
Nie umieszczaj tokenów w dziennikach
Dzienniki debugowania Home Assistant, historia powłoki, zrzuty ekranu i repozytoria Git to częste miejsca wycieku tokenów. Przed publicznym udostępnieniem diagnostyki usuń nagłówki autoryzacji i odpowiedzi logowania w formacie JSON.
Przypnij używany kontrakt API
Jeśli integracja korzysta z wygenerowanych klientów OpenAPI, przechowuj schemat i jego wersję razem z kodem oraz sprawdzaj zmiany wprowadzane w upstreamie przed ponownym generowaniem. Dzięki temu od razu widać, że zmienił się punkt końcowy lub struktura odpowiedzi, zamiast po cichu psuć automatyzacje.
FAQ
Czy ZimaOS może wygenerować stały token API?
W odpowiedzi IceWhale źródło podało, że stałe tokeny nie są obsługiwane, a aktualna publiczna dokumentacja nie opisuje interfejsu do zarządzania osobistymi tokenami dostępu.
Jak uzyskano stary token dostępu?
Użytkownik forum uzyskał go po pomyślnym żądaniu POST do /v1/users/login.
Czy należy udostępnić API w internecie?
Nie. Korzystaj z zaufanej, prywatnej sieci i uwierzytelniaj się za pomocą aktualnie obsługiwanego procesu.
Czy mogę zbudować integrację z Home Assistant?
Tak, ale uwzględnij wygaśnięcie tokenów, zmiany wersji API i dostęp z minimalnymi uprawnieniami.
