Długoterminowy token Home Assistant: jak go utworzyć, dlaczego od admina i „działa, ale nic nie pokazuje”

Krótka odpowiedź

Długoterminowy token dostępu to zamiennik hasła dla aplikacji i skryptów: tworzysz go w swoim profilu Home Assistant, na karcie Bezpieczeństwo, w sekcji Długotrwałe tokeny dostępu, a Home Assistant pokazuje go tylko raz. Jest ważny 10 lat. Niektóre aplikacje potrzebują tokenu administratora, bo część API, na przykład /api/template, odmawia każdemu innemu użytkownikowi błędem 401.

Dalsza część artykułu omawia każdy element po kolei: czym jest token, gdzie go znaleźć, jak go skopiować, nie psując go, dlaczego kwestia administratora ma znaczenie, jak sprawdzić token dwoma poleceniami curl i jak trzymać tokeny pod kontrolą. Przykładem jest AmazHA, aplikacja Home Assistant na zegarki Amazfit, bo dotyka każdego z tych punktów: potrzebuje tokenu, potrzebuje tokenu administratora i musi radzić sobie z tokenami zniekształconymi przy kopiowaniu i wklejaniu.

Czym jest długoterminowy token dostępu

Długoterminowy token dostępu to dane uwierzytelniające, które pozwalają programowi działać jako Twój użytkownik Home Assistant bez przechodzenia przez ekran logowania. Gdy logujesz się do interfejsu webowego, Home Assistant daje przeglądarce krótki token dostępu (30 minut) i token odświeżania, który go odnawia. Skrypt, aplikacja na telefon czy aplikacja na zegarek nie przejdą łatwo przez taki proces logowania, więc Home Assistant oferuje drugi rodzaj tokenu: taki, który tworzysz ręcznie, kopiujesz raz i przekazujesz programowi.

W praktyce liczą się trzy cechy:

• Jest ważny 10 lat. Dokumentacja API uwierzytelniania Home Assistant mówi, że tokeny długoterminowe są ważne 10 lat, i strona profilu to powtarza: każdy token jest ważny 10 lat od utworzenia.
• Jest pokazywany raz. Home Assistant nie przechowuje samego tokenu, więc nie może go wyświetlić ponownie. Jeśli go zgubisz, tworzysz nowy.
• Jest tym użytkownikiem, który go utworzył. Token ma uprawnienia użytkownika, który go utworzył, ani mniej, ani więcej. Token utworzony przez administratora jest administratorem przy każdym podpisanym nim zapytaniu; token utworzony przez zwykłego użytkownika jest zwykłym użytkownikiem.

Token jest przesyłany w nagłówku HTTP przy każdym zapytaniu:

Authorization: Bearer <your token>

To wszystko, co musi zrobić klient. Nie ma nazwy użytkownika, hasła ani sesji: każde zapytanie z ważnym tokenem w tym nagłówku jest przyjmowane jako zapytanie tego użytkownika.

Gdzie go znaleźć

Długoterminowe tokeny dostępu tworzysz we własnym profilu użytkownika, na karcie Bezpieczeństwo. W aplikacji Home Assistant albo w przeglądarce:

1. Otwórz pasek boczny (menu ≡ na telefonie) i dotknij swojej nazwy na dole.
2. W profilu otwórz kartę Bezpieczeństwo.
3. Niżej na tej karcie jest sekcja Długotrwałe tokeny dostępu, z listą tokenów, które już masz, i przyciskiem Utwórz token.

Dokumentacja użytkownika Home Assistant ujmuje to tak samo: Profil użytkownika › Bezpieczeństwo, czyli strona, na której zmieniasz też hasło, konfigurujesz uwierzytelnianie wieloskładnikowe i zarządzasz tokenami odświeżania.

„Nie mogę go znaleźć”

Najczęstszy powód to karta. Profil otwiera się na ustawieniach ogólnych (język, motyw i tym podobne); sekcja z tokenami jest na karcie Bezpieczeństwo. Wiele starszych poradników każe przewinąć na dół strony profilu, co było prawdą, zanim profil podzielono na karty.

Dwa inne powody:

• Szukasz cudzego tokenu. Każdy użytkownik widzi i zarządza tylko własnymi tokenami. Token utworzony przez inną osobę z domowników nie pojawia się w Twoim profilu i nie możesz go stamtąd usunąć.
• Jesteś zalogowany jako inny użytkownik, niż myślisz. Sprawdź nazwę na dole paska bocznego. Jeśli aplikacja potrzebuje tokenu administratora (więcej o tym niżej), upewnij się, że ta nazwa należy do administratora, zanim go utworzysz.

Utwórz go i skopiuj

Utworzenie tokenu to cztery dotknięcia; problemy zaczynają się przy kopiowaniu. Kroki:

1. Na karcie Bezpieczeństwo, w sekcji Długotrwałe tokeny dostępu, dotknij Utwórz token.
2. Home Assistant poprosi o nazwę tokenu. Użyj nazwy aplikacji, na przykład AmazHA. Nazwy Twoich tokenów muszą być unikalne.
3. Następne okno pokazuje token z ostrzeżeniem, że trzeba go skopiować, bo nie zostanie wyświetlony ponownie. Skopiuj go teraz, w całości.
4. Zamknij okno. Token pojawia się teraz na liście pod swoją nazwą, z datą utworzenia.

Token to długi ciąg liter, cyfr, - i _, w trzech częściach rozdzielonych kropkami. Jego długość to powód większości problemów z kopiowaniem: nie mieści się w jednym wierszu, więc nieuważne zaznaczenie łapie tylko część, a niektóre aplikacje skracają długi ciąg na ekranie wielokropkiem (…) i kopiują to, co wyświetlają.

Praktyczne nawyki, które oszczędzają kłopotów:

• Użyj przycisku kopiowania w oknie, a nie ręcznego zaznaczenia.
• Wklej go prosto do aplikacji, która go potrzebuje. Objazd przez czat, e-mail czy aplikację do notatek może dodać niewidoczne znaki, typograficzne cudzysłowy lub podziały wierszy.
• Nie dopisuj Bearer na początku, chyba że aplikacja wyraźnie prosi o cały nagłówek. Prawie każda aplikacja dodaje to słowo sama.
• Jeśli potrzebujesz go na innym urządzeniu, utwórz tam drugi token, zamiast przesyłać pierwszy.

Dlaczego niektóre aplikacje potrzebują tokenu administratora

Niektóre aplikacje potrzebują tokenu administratora, bo Home Assistant rezerwuje kilka punktów końcowych API dla administratorów, a token może tylko to, co może jego użytkownik. Najwyraźniejszy przykład to punkt końcowy szablonów, POST /api/template, który renderuje szablon Jinja na serwerze i zwraca wynik.

W kodzie źródłowym Home Assistant widok, który go obsługuje, APITemplateView w homeassistant/components/api/__init__.py, ma metodę post opatrzoną dekoratorem @require_admin. Ten dekorator sprawdza użytkownika stojącego za tokenem; jeśli nie jest administratorem, zgłasza Unauthorized, które warstwa HTTP Home Assistant zamienia na 401 Unauthorized. Dokumentacja REST API również oznacza ten punkt końcowy jako „Admin”.

Nie jest jedyny. REST API dzieli się mniej więcej tak:

Po co więc aplikacji w ogóle punkt końcowy szablonów? Bo części informacji nie ma w zwykłych punktach końcowych REST. Najwyraźniejszy przypadek to obszary: /api/states zwraca każdą encję z jej stanem i atrybutami, ale bez obszaru, do którego należy, a REST API nie ma punktu końcowego z listą obszarów. Szablon może o nie zapytać: area_id(entity_id) i area_name(...) zwracają obszar, który Home Assistant przypisuje każdej encji, na podstawie ustawienia samej encji lub jej urządzenia. Aplikacja, która chce pokazać Twój dom pokój po pokoju, tak jak robią to pulpity Home Assistant, renderuje więc szablon i potrzebuje do tego administratora.

Czy dawanie aplikacji uprawnień administratora to dobry pomysł?

Zalecenia bezpieczeństwa Home Assistant mówią, by dawać dostęp administratora tylko kontom, które go potrzebują. Aplikacja wymagająca /api/template jest takim przypadkiem, a Ty masz dwie rozsądne możliwości:

• Utwórz token jako swój własny użytkownik-administrator. Najprostsza opcja. Token jest widoczny w Twoim profilu pod swoją nazwą, a jego usunięcie odbiera dostęp tylko tej jednej aplikacji.
• Utwórz osobnego użytkownika-administratora dla aplikacji w sekcji Ustawienia › Osoby, zaloguj się raz jako ten użytkownik i utwórz tam token. Informacja o ostatnim użyciu jest wtedy oddzielona od Twojej, a później możesz wyłączyć całego użytkownika. Zostaw go aktywnego, dopóki aplikacja z niego korzysta: tokeny dezaktywowanego użytkownika przestają działać. Nie zaznaczaj Local access only (tylko dostęp lokalny), jeśli aplikacja łączy się też spoza domu, z powodu opisanego niżej w sekcji o błędzie 401.

Tak czy inaczej, token zasługuje na taką samą troskę jak hasło: token administratora może w Home Assistant wszystko, co możesz Ty.

„Działa, ale nic nie pokazuje”: błąd 401 na /api/template

Gdy aplikacja łączy się poprawnie, a mimo to nic nie pokazuje, przyczyną jest prawie zawsze token użytkownika, który nie jest administratorem. Test połączenia przechodzi, bo większość aplikacji testuje przez GET /api/, a ten punkt końcowy przyjmuje każdy ważny token. Stany też da się odczytać. Zawodzi tylko zapytanie o szablon, z błędem 401, a aplikacja, która buduje listę urządzeń z tego szablonu, zostaje bez niczego do pokazania.

Kolejność zdarzeń od strony aplikacji:

1. GET /api/ z tokenem: 200, {"message": "API running."}. Aplikacja zgłasza „połączono”.
2. GET /api/states/...: 200. Stany są.
3. POST /api/template, by przypisać encje do obszarów: 401. Brak obszarów, więc brak pokoi, więc pusty ekran.

Mylące jest to, że nic innego nie wygląda źle. Adres jest dobry, token jest ważny, Home Assistant działa. Nawet akcje mogą działać: POST /api/services/... jest dostępne dla zwykłych użytkowników, więc tym samym tokenem nadal można z aplikacji przełączyć światło.

Co pokazuje Home Assistant

Home Assistant liczy każdy wysłany błąd 401 jako nieudane logowanie, także ten z kontroli uprawnień administratora. Do jego dziennika trafia ostrzeżenie zaczynające się od „Login attempt or request with invalid authentication from …”, z adresem, z którego przyszło zapytanie (w domu zwykle Twój telefon lub serwer), a interfejs webowy pokazuje powiadomienie Login attempt failed (nieudana próba logowania). Jeśli masz włączone blokowanie adresów IP po określonej liczbie prób logowania, wystarczająco wiele takich błędów 401 zablokuje ten adres: od tej pory dostaje on na wszystko 403 Forbidden, dopóki nie usuniesz go z ip_bans.yaml i nie uruchomisz ponownie Home Assistant.

Jeśli więc widzisz powtarzające się powiadomienia „Login attempt failed” wskazujące na Twój własny telefon, jednym z wyjaśnień, obok usuniętego tokenu, jest aplikacja z tokenem zwykłego użytkownika, która wywołuje punkt końcowy zarezerwowany dla administratorów.

Jak AmazHA to wykrywa i jak o tym mówi

AmazHA, która odczytuje Twoje obszary przez /api/template, celowo sprawdza ten przypadek, zamiast zostawiać Cię z pustym zegarkiem:

• Gdy dotkniesz Połącz, telefon najpierw sprawdza adres przez GET /api/, a potem wysyła do /api/template jeden banalny szablon, {{ 1 }}. Jeśli ten szablon zostanie odrzucony z kodem 401, 403 lub 400, token zostaje oznaczony jako nienależący do administratora. Ekran Home Assistant pokazuje wtedy Połączono ✓ z bursztynowym wierszem pod spodem: „Połączono, ale ten token nie ma uprawnień administratora, więc zegarek nie może wczytać encji. Utwórz długoterminowy token na koncie Home Assistant z rolą Administrator i wklej go powyżej.”
• Na zegarku, gdy nie da się wczytać pokoi, bo szablon obszarów jest odrzucany, ekran główny pokazuje baner Wymagany token admina · „Token nie ma uprawnień administratora — użyj konta administratora Home Assistant”, zamiast ogólnego Offline.
• W raporcie dla pomocy technicznej, który możesz wysłać z ustawień AmazHA, wiersz „HA token” mówi, czy token rozpoznano jako token administratora, nigdy nie zawierając samego tokenu.

Rozwiązanie jest zawsze takie samo: utwórz nowy długoterminowy token po zalogowaniu się jako administrator, wklej go i dotknij jeszcze raz Połącz. Krok 5 poradnika Gdy coś nie działa pokazuje to na wideo.

Jak sprawdzić, czy użytkownik jest administratorem

Otwórz Ustawienia › Osoby, a potem kartę Użytkownicy. W kolumnie Grupa administrator ma wpis Administratorzy; po otwarciu użytkownika widać przełącznik Administrator (z opisem, że administratorzy mogą zarządzać użytkownikami, urządzeniami, automatyzacjami i pulpitami).

Jest szybszy test: jeśli na pasku bocznym konta, na którym jesteś zalogowany, w ogóle nie ma pozycji Ustawienia, ten użytkownik nie jest administratorem. Home Assistant rejestruje swój panel konfiguracji jako dostępny tylko dla administratorów, więc zwykli użytkownicy go nie widzą. W takim przypadku wyloguj się, zaloguj jako administrator i tam utwórz token.

Sprawdź to sam za pomocą curl

Każdy token sprawdzisz w minutę z komputera w tej samej sieci, dwoma poleceniami curl: jednym na /api/, które przechodzi z każdym ważnym tokenem, i jednym na /api/template, które przechodzi tylko z tokenem administratora. Przykłady używają 192.168.1.50:8123 jako adresu Home Assistant; zamień go na swój. Działają w takiej postaci w terminalu macOS lub Linuksa.

Aby token nie trafił do historii powłoki, najpierw wczytaj go do zmiennej. Wklej token, gdy polecenie czeka, i naciśnij Enter:

read -rs HA_TOKEN

Test 1: czy token jest ważny?

curl -s -w "\nHTTP %{http_code}\n" \
  -H "Authorization: Bearer $HA_TOKEN" \
  http://192.168.1.50:8123/api/

Ważny token odpowiada {"message":"API running."} i HTTP 200. Uważaj na ukośnik na końcu: punkt końcowy to /api/, nie /api.

Test 2: czy token należy do administratora?

curl -s -w "\nHTTP %{http_code}\n" -X POST \
  -H "Authorization: Bearer $HA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"template": "{{ 1 }}"}' \
  http://192.168.1.50:8123/api/template

Token administratora dostaje wyrenderowany szablon, 1, i HTTP 200. Token zwykłego użytkownika dostaje HTTP 401.

Jak czytać oba wyniki razem:

Dwa zastrzeżenia. Po pierwsze, to testuje token z Twojego komputera; aplikacja na telefonie może docierać do Home Assistant inną drogą, zwłaszcza poza domem. Po drugie, sam udany test 1 niewiele dowodzi dla aplikacji, które potrzebują obszarów: to dokładnie ten test, który przechodzi token zwykłego użytkownika.

Błąd 401 przy „Local access only”

Użytkownik z włączonym Local access only może logować się tylko z Twojej sieci lokalnej, a Home Assistant stosuje tę samą zasadę do jego tokenów. Zapytanie z adresu spoza Twojej sieci albo takie, które przychodzi przez Home Assistant Cloud, jest odrzucane z błędem 401, choć ten sam token świetnie działa w domu. Jeśli aplikacja działa w Twoim Wi-Fi, a poza domem dostaje 401, otwórz użytkownika w Ustawienia › Osoby i spójrz na ten przełącznik, zanim zaczniesz podejrzewać adres zdalny. O samym adresie zdalnym przeczytasz w artykule Home Assistant poza domem na Twoim zegarku.

Problemy z wklejaniem

Token, który wygląda dobrze, nadal może być błędny, bo to, co wkleiłeś, nie zawsze jest tym, co dał Ci Home Assistant. Home Assistant porównuje token znak po znaku, więc jeden znak za dużo lub za mało oznacza nieważny token i błąd 401. Typowi winowajcy:

Lekarstwo jest dla wszystkich takie samo: skopiuj token jeszcze raz przyciskiem kopiowania w oknie i wklej go bezpośrednio. Jeśli okno jest już zamknięte, tokenu nie da się odzyskać; utwórz nowy i usuń stary wpis.

Co AmazHA czyści, a czego odmawia

AmazHA sama radzi sobie z przypadkami, które da się naprawić, zarówno przy zapisywaniu tokenu, jak i ponownie, gdy telefon odczytuje go do zapytania:

• Usuwane: spacje, podziały wierszy, znaki o zerowej szerokości, twarde spacje, znaczniki kolejności bajtów, miękkie dywizy i znaczniki kierunku tekstu, w dowolnym miejscu tokenu. Żaden z nich nie może być częścią tokenu Home Assistant, który składa się z liter, cyfr, -, _ i kropek.
• Obcinane z końców: proste i typograficzne cudzysłowy, grawisy i cudzysłowy ostrokątne.
• Usuwany z początku: wklejony Bearer (pisany dowolnie wielkimi i małymi literami), bo AmazHA dodaje to słowo sama.

Czyszczenie nie naprawi widocznego znaku, którego nie zawiera żaden token, zwykle … z uciętej kopii. AmazHA nie zgaduje: w ogóle nie wysyła takiego tokenu, więc żadne zapytanie nie dociera do Home Assistant i nie jest liczone żadne nieudane logowanie. Ekran Home Assistant w ustawieniach pokazuje Nieprawidłowy token z wyjaśnieniem: „Token zawiera znak, którego token Home Assistanta nie może mieć — zwykle to ucięta kopia (…). Skopiuj ponownie cały token z profilu Home Assistanta › Bezpieczeństwo i wklej go powyżej.” Zegarek pokazuje Sprawdź token · „Zawiera nieprawidłowy znak — wklej go ponownie”. To krok 6 poradnika Gdy coś nie działa.

Dbaj o bezpieczeństwo

Traktuj każdy długoterminowy token jak hasło, które nie wygasa przez 10 lat: jeden token na aplikację, nazwa, która mówi, o którą aplikację chodzi, i usunięcie go w dniu, w którym przestajesz z tej aplikacji korzystać. Konkretnie:

• Jeden token na aplikację lub urządzenie. Jeśli dasz ten sam token trzem programom, nie unieważnisz go dla jednego, nie psując dwóch pozostałych, i nie będziesz wiedzieć, który z nich wysyła zapytania.
• Nazwij go jak aplikację. „AmazHA”, „Skrypt kopii zapasowej”, „Tablet na ścianie”. Nazwa to wszystko, co później zobaczysz na liście; sam token nigdy nie zostanie ponownie pokazany.
• Co jakiś czas przejrzyj listę. Każdy wpis pokazuje, kiedy go utworzono, a po pierwszym użyciu także kiedy i skąd użyto go ostatnio. Token, którego nikt nie używał od miesięcy, to kandydat do usunięcia.
• Unieważniaj przez usunięcie. Na karcie Bezpieczeństwo usuń token po jego nazwie. Aplikacja, która go używała, przy następnym zapytaniu dostaje błąd 401; nic innego się nie zmienia.
• Jeśli token mógł wyciec, usuń go i utwórz nowy. Usunięcie to jedyny sposób na unieważnienie pojedynczego tokenu; nowy wpiszesz do aplikacji w minutę.
• Nigdy nie wklejaj tokenu do zgłoszenia do pomocy technicznej, posta na forum ani zrzutu ekranu. Diagnostyka dobrej aplikacji nigdy go nie potrzebuje.

Usunięcie wszystkich tokenów odświeżania z tej samej karty wylogowuje Twoje urządzenia, ale zostawia bieżącą sesję i Twoje długoterminowe tokeny, jak mówi okno potwierdzenia w Home Assistant. Długoterminowe tokeny unieważnia się pojedynczo.

W AmazHA

AmazHA potrzebuje dokładnie jednego długoterminowego tokenu, od administratora, wpisanego raz w ustawieniach AmazHA w aplikacji Zepp; ten jeden token obsługuje adres lokalny i zdalny i zostaje w Twoim telefonie. Pola połączenia są dostępne po odblokowaniu pełnej wersji (jednorazowe odblokowanie, bez abonamentu: zobacz Odblokuj pełną wersję). Potem:

1. Utwórz token jako administrator, jak opisano wyżej (kroki 1–3 poradnika Połącz Home Assistant).
2. W aplikacji Zepp przejdź do Profil › Twój zegarek › Aplikacje › AmazHA › Ustawienia, a potem dotknij Home Assistant (krok 4).
3. W polu Lokalny URL (LAN) wpisz adres, którego używasz w domu, na przykład http://192.168.1.50:8123, a jeśli chcesz, by zegarek działał też poza domem, w polu Zdalny URL adres zewnętrzny. Każde z pól może zostać puste.
4. Wklej token w polu Token długoterminowy (krok 7).
5. Dotknij Połącz. Gdy ustawione są oba adresy, wynik pokazuje każdy z nich, LAN i Zdalny; przy jednym adresie widać Połączono ✓. Jeśli token nie należy do administratora, pod spodem pojawia się opisany wyżej bursztynowy wiersz.

Jeden token, dwa adresy

Do adresu zdalnego nie potrzebujesz drugiego tokenu. Token należy do użytkownika, a nie do adresu: ten sam token jest ważny niezależnie od tego, czy zapytanie dociera do Home Assistant przez Twoje Wi-Fi, czy z zewnątrz. W domu AmazHA używa adresu lokalnego; zdalny jest tylko na czas, gdy telefon jest poza domem. Jedynym wyjątkiem jest opisany wyżej użytkownik z Local access only, którego token jest z założenia odrzucany z zewnątrz.

Dokąd trafia token, a dokąd nie

Zegarek nigdy nie łączy się z Home Assistant bezpośrednio. Robi to Twój telefon, przez aplikację Zepp, i tam, w telefonie, przechowywany jest token. Jest wysyłany tylko do Twojego serwera Home Assistant, w nagłówku Authorization zapytań wysyłanych przez telefon; nigdy nie trafia na zegarek, który dostaje przez połączenie Bluetooth z telefonem tylko to, co pokazuje. AmazHA nie ma własnego serwera, przez który token mógłby przechodzić, a raport dla pomocy technicznej nigdy go nie zawiera.

Co telefon robi z tokenem, zapytanie po zapytaniu:

Ostatni wiersz to funkcja czujników zegarka, która wysyła tętno, kroki, baterię i inne dane z Twojego Amazfita do Home Assistant jako urządzenie integracji Mobile App: opisuje ją artykuł Wyślij dane z Amazfita do Home Assistant.

Gdy AmazHA mówi coś o tokenie

Mały kod pod napisem Offline jest dla pomocy technicznej: jeśli do nas piszesz, zdjęcie zegarka mówi dokładnie, co zawiodło. Wszystkie pozostałe komunikaty, które może pokazać zegarek, opisuje poradnik Gdy coś nie działa.