Dlouhodobý přístupový token Home Assistant: vytvoření, práva administrátora a „funguje, ale nic neukazuje“

Stručná odpověď

Dlouhodobý přístupový token je náhrada hesla pro aplikace a skripty: vytvoříte ho ve svém profilu Home Assistant na kartě Zabezpečení v sekci Tokeny s dlouhou životností a Home Assistant ho ukáže jen jednou. Platí 10 let. Některé aplikace potřebují token od administrátora, protože části API, například /api/template, odmítnou každého jiného uživatele s chybou 401.

Zbytek článku prochází jednotlivé části: co token je, kde ho najdete, jak ho zkopírovat a nepoškodit, proč záleží na otázce administrátora, jak token otestovat dvěma příkazy curl a jak mít tokeny pod kontrolou. Jako příklad slouží AmazHA, aplikace Home Assistant pro hodinky Amazfit, protože naráží na každý z těchto bodů: potřebuje token, potřebuje token administrátora a musí si poradit s tokeny, které kopírování a vkládání poškodilo.

Co je dlouhodobý přístupový token

Dlouhodobý přístupový token je přihlašovací údaj, který programu umožní jednat jako váš uživatel Home Assistant, aniž by procházel přihlašovací obrazovkou. Když se přihlásíte do webového rozhraní, Home Assistant předá vašemu prohlížeči krátkodobý přístupový token (30 minut) a obnovovací token, který ho prodlužuje. Skript, telefonní aplikace nebo aplikace pro hodinky tento postup přihlášení snadno projít nemohou, proto Home Assistant nabízí druhý druh tokenu: takový, který vytvoříte ručně, jednou zkopírujete a předáte programu.

V praxi jsou důležité tři vlastnosti:

• Platí 10 let. Vlastní dokumentace autentizačního API Home Assistant uvádí, že dlouhodobé tokeny „are valid for 10 years“ (platí 10 let), a stránka profilu to opakuje: každý token platí 10 let od vytvoření.
• Zobrazí se jednou. Home Assistant samotný token neukládá, takže ho nemůže znovu zobrazit. Když ho ztratíte, vytvoříte nový.
• Je to uživatel, který ho vytvořil. Token nese oprávnění uživatele, který ho vytvořil, ani víc, ani míň. Token vytvořený administrátorem je administrátorem u každého požadavku, který podepíše; token vytvořený běžným uživatelem je běžným uživatelem.

Token putuje v hlavičce HTTP s každým požadavkem:

Authorization: Bearer <your token>

To je vše, co klient musí udělat. Žádné uživatelské jméno, žádné heslo a žádná relace: každý požadavek s platným tokenem v této hlavičce je přijat jako požadavek daného uživatele.

Kde ho najdete

Dlouhodobé přístupové tokeny vytváříte ve svém vlastním uživatelském profilu, na kartě Zabezpečení. V aplikaci Home Assistant nebo v prohlížeči:

1. Otevřete postranní panel (na telefonu nabídka ≡) a dole klepněte na své jméno.
2. Ve svém profilu otevřete kartu Zabezpečení.
3. Níže na této kartě je sekce Tokeny s dlouhou životností se seznamem tokenů, které už máte, a s tlačítkem Vytvořit token.

Uživatelská dokumentace Home Assistant to popisuje stejně: User profile › Security (Uživatelský profil › Zabezpečení), stránka, kde také měníte heslo, nastavujete vícefaktorové ověřování a spravujete obnovovací tokeny.

„Nemůžu ho najít“

Nejčastějším důvodem je karta. Profil se otevře na obecných nastaveních (jazyk, motiv a podobně); sekce s tokeny je na kartě Zabezpečení. Mnoho starších návodů radí sjet na konec stránky profilu, což platilo, než se profil rozdělil na karty.

Dva další důvody:

• Hledáte token někoho jiného. Každý uživatel vidí a spravuje jen své vlastní tokeny. Token, který vytvořil jiný člen domácnosti, se ve vašem profilu neobjeví a odtud ho smazat nemůžete.
• Jste přihlášeni jako jiný uživatel, než si myslíte. Zkontrolujte jméno dole v postranním panelu. Pokud aplikace potřebuje token administrátora (víc o tom níže), ujistěte se, že to jméno patří administrátorovi, ještě než token vytvoříte.

Vytvořte ho a zkopírujte

Vytvoření tokenu zabere čtyři klepnutí; chyby vznikají při jeho správném zkopírování. Postup:

1. Na kartě Zabezpečení v sekci Tokeny s dlouhou životností klepněte na Vytvořit token.
2. Home Assistant vás požádá o název tokenu. Použijte název aplikace, například AmazHA. Názvy musí být mezi vašimi tokeny jedinečné.
3. Další dialog ukáže token s upozorněním, že si ho máte zkopírovat, protože se znovu nezobrazí. Zkopírujte ho hned, celý.
4. Zavřete dialog. Token se teď objeví v seznamu pod svým názvem a s datem vytvoření.

Token je dlouhý řetězec písmen, číslic, - a _, ve třech částech oddělených tečkami. Jeho délka je důvodem většiny potíží s kopírováním: nevejde se na jeden řádek, takže nepozorný výběr zachytí jen jeho část, a některé aplikace dlouhý řetězec na obrazovce zkrátí třemi tečkami (…) a pak zkopírují to, co zobrazují.

Praktické návyky, které potížím předejdou:

• Použijte tlačítko kopírování v dialogu, ne ruční výběr.
• Vložte ho rovnou do aplikace, která ho potřebuje. Oklika přes chat, e-mail nebo aplikaci na poznámky může přidat neviditelné znaky, typografické uvozovky nebo zalomení řádků.
• Nepřidávejte před něj Bearer , pokud aplikace výslovně nežádá celou hlavičku. Téměř každá aplikace to slovo doplní sama.
• Pokud ho potřebujete na jiném zařízení, vytvořte tam druhý token, místo abyste první posílali dál.

Proč některé aplikace potřebují token administrátora

Některé aplikace potřebují token administrátora, protože Home Assistant vyhrazuje několik koncových bodů API administrátorům a token může jen to, co může jeho uživatel. Nejjasnějším příkladem je šablonový koncový bod POST /api/template, který na serveru vykreslí šablonu Jinja a vrátí výsledek.

Ve zdrojovém kódu Home Assistant má pohled, který ho obsluhuje, APITemplateView v homeassistant/components/api/__init__.py, svou metodu post označenou dekorátorem @require_admin. Ten dekorátor zkontroluje uživatele za tokenem; pokud uživatel není administrátor, vyvolá Unauthorized, což vrstva HTTP Home Assistant převede na 401 Unauthorized. Také dokumentace REST API označuje tento koncový bod jako „Admin“.

Není jediný. REST API se zhruba dělí takto:

Proč by tedy aplikace šablonový koncový bod vůbec potřebovala? Protože některé informace v běžných koncových bodech REST nejsou. Nejjasnějším případem jsou oblasti: /api/states vrací každou entitu s jejím stavem a atributy, ale ne oblast, do které patří, a REST API nemá koncový bod, který by oblasti vypsal. Šablona se na ně zeptat umí: area_id(entity_id) a area_name(...) vrátí oblast, kterou Home Assistant pro každou entitu určí, z vlastního nastavení entity nebo z jejího zařízení. Aplikace, která chce ukázat váš domov po místnostech, tak jako to dělají dashboardy Home Assistant, proto vykresluje šablonu a potřebuje k tomu administrátora.

Je dobrý nápad dát aplikaci práva administrátora?

Vlastní bezpečnostní doporučení Home Assistant radí dávat přístup administrátora jen účtům, které ho potřebují. Aplikace, která potřebuje /api/template, je takový případ a máte dvě rozumné možnosti, jak s tím naložit:

• Vytvořte token jako svůj vlastní uživatel s právy administrátora. Nejjednodušší možnost. Token je uvedený ve vašem profilu pod svým názvem a jeho smazáním zrušíte přístup jen této aplikaci.
• Vytvořte pro aplikaci samostatného uživatele s právy administrátora v části Nastavení › Osoby, jednou se jako tento uživatel přihlaste a vytvořte token tam. Jeho informace o „posledním použití“ zůstanou oddělené od vašich a celého uživatele můžete později vypnout. Dokud ho aplikace používá, nechte ho aktivního: tokeny deaktivovaného uživatele přestanou fungovat. Nezaškrtávejte Local access only (pouze místní přístup), pokud se aplikace připojuje i zvenku domova, z důvodu popsaného v sekci o chybě 401 níže.

V obou případech si token zaslouží stejnou péči jako heslo: token administrátora může v Home Assistant dělat všechno, co můžete vy.

„Funguje, ale nic neukazuje“: 401 na /api/template

Když se aplikace úspěšně připojí, a přesto nic neukazuje, je příčinou téměř vždy token od uživatele, který není administrátor. Test připojení projde, protože většina aplikací testuje přes GET /api/ a tento koncový bod přijme jakýkoli platný token. Stavy jdou také přečíst. Selže jen požadavek na šablonu, s chybou 401, a aplikace, která z této šablony sestavuje seznam zařízení, nemá co ukázat.

Postup z pohledu aplikace:

1. GET /api/ s tokenem: 200, {"message": "API running."}. Aplikace hlásí „připojeno“.
2. GET /api/states/...: 200. Stavy jsou k dispozici.
3. POST /api/template pro přiřazení entit k oblastem: 401. Žádné oblasti, takže žádné místnosti, takže prázdná obrazovka.

Matoucí je, že nic jiného nevypadá špatně. Adresa je správná, token je platný, Home Assistant běží. Fungovat mohou dokonce i akce: POST /api/services/... je otevřený i běžným uživatelům, takže se světlo dá z aplikace se stejným tokenem pořád přepnout.

Co ukazuje Home Assistant

Home Assistant počítá každou odeslanou chybu 401 jako neúspěšné přihlášení, včetně té z kontroly administrátora. Do jeho protokolu se zapíše varování začínající „Login attempt or request with invalid authentication from …“, které uvádí adresu, ze které požadavek přišel (doma obvykle váš telefon nebo server), a webové rozhraní zobrazí oznámení Login attempt failed (pokus o přihlášení se nezdařil). Pokud máte zapnuté blokování IP adres s počtem pokusů o přihlášení před zablokováním, dostatek takových chyb 401 tuto adresu zablokuje: od té chvíle dostává na všechno 403 Forbidden, dokud ji neodstraníte z ip_bans.yaml a nerestartujete Home Assistant.

Pokud tedy vidíte opakovaná oznámení o neúspěšném přihlášení, která ukazují na váš vlastní telefon, jedním z vysvětlení je aplikace s tokenem běžného uživatele, která volá koncový bod vyhrazený administrátorům, vedle tokenu, který byl smazán.

Jak to AmazHA zjistí a jak to podá

AmazHA, která načítá vaše oblasti přes /api/template, tento případ záměrně kontroluje, místo aby vás nechala s prázdnými hodinkami:

• Když klepnete na Připojit, telefon nejprve zkontroluje adresu přes GET /api/ a pak pošle na /api/template jednu triviální šablonu, {{ 1 }}. Pokud je tato šablona odmítnuta s chybou 401, 403 nebo 400, token se označí jako token, který nepatří administrátorovi. Obrazovka Home Assistant pak ukáže Připojeno ✓ a pod tím oranžový řádek: „Připojeno, ale tento token nemá oprávnění administrátora, takže hodinky nemohou načíst vaše entity. Vytvořte dlouhodobý token u uživatele Home Assistant s rolí Administrátor a vložte jej výše.“
• Na hodinkách, když místnosti nejde načíst, protože šablona oblastí je odmítnuta, ukáže domovská obrazovka banner Je potřeba admin token · „Token nemá práva administrátora — použijte účet správce Home Assistant“, místo obecného Offline.
• V hlášení pro podporu, které můžete odeslat z nastavení AmazHA, řádek „HA token“ uvádí, zda byl token rozpoznán jako token administrátora, aniž by kdy obsahoval token samotný.

Řešení je ve všech případech stejné: po přihlášení jako administrátor vytvořte nový dlouhodobý token, vložte ho a znovu klepněte na Připojit. Krok 5 návodu Když něco nefunguje to ukazuje ve videu.

Jak ověřit, že je uživatel administrátor

Otevřete Nastavení › Osoby a pak kartu Users (Uživatelé). Sloupec Group (Skupina) u administrátora uvádí Administrators (Administrátoři); po otevření uživatele uvidíte přepínač Administrator (Administrátor) s vysvětlením, že administrátoři mohou spravovat uživatele, zařízení, automatizace a dashboardy.

Existuje i rychlejší test: pokud postranní panel účtu, pod kterým jste přihlášeni, vůbec nemá položku Nastavení, tento uživatel není administrátor. Home Assistant registruje svůj konfigurační panel jako vyhrazený administrátorům, takže ho běžní uživatelé nikdy nevidí. V takovém případě se odhlaste, přihlaste se jako administrátor a token vytvořte tam.

Ověřte si to sami pomocí curl

Jakýkoli token otestujete za minutu z počítače ve stejné síti dvěma příkazy curl: jedním na /api/, který projde s jakýmkoli platným tokenem, a jedním na /api/template, který projde jen s tokenem administrátora. Příklady používají jako adresu Home Assistant 192.168.1.50:8123; nahraďte ji svou. Fungují tak, jak jsou napsané, v terminálu macOS nebo Linuxu.

Aby se token nedostal do historie shellu, načtěte ho nejprve do proměnné. Až bude příkaz čekat, vložte token a stiskněte Enter:

read -rs HA_TOKEN

Test 1: je token platný?

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

Platný token odpoví {"message":"API running."} a HTTP 200. Pozor na koncové lomítko: koncový bod je /api/, ne /api.

Test 2: patří token administrátorovi?

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 administrátora dostane vykreslenou šablonu, 1, a HTTP 200. Token běžného uživatele dostane HTTP 401.

Jak číst oba výsledky dohromady:

Dvě výhrady. Zaprvé tím testujete token z počítače; aplikace v telefonu může k Home Assistant vést jinou cestou, zvlášť mimo domov. Zadruhé samotný úspěšný test 1 u aplikací, které potřebují oblasti, dokazuje velmi málo: je to přesně ten test, kterým projde i token běžného uživatele.

Chyba 401 kvůli „Local access only“

Uživatel se zapnutou volbou Local access only se může přihlásit jen z vaší místní sítě a stejné pravidlo Home Assistant uplatňuje i na tokeny tohoto uživatele. Požadavek z adresy mimo vaši síť, nebo takový, který přijde přes Home Assistant Cloud, je odmítnut s chybou 401, přestože stejný token doma funguje bez problémů. Pokud aplikace funguje na vaší Wi-Fi a mimo domov selhává s chybou 401, otevřete uživatele v části Nastavení › Osoby a podívejte se na tento přepínač, ještě než začnete podezírat vzdálenou adresu. K samotné vzdálené adrese viz Home Assistant mimo domov na vašich hodinkách.

Problémy s vkládáním

Token, který vypadá správně, může být přesto špatně, protože to, co jste vložili, není vždy to, co vám Home Assistant dal. Home Assistant porovnává token znak po znaku, takže jediný přebývající nebo chybějící znak znamená neplatný token a chybu 401. Obvyklí viníci:

Lék je pro všechny stejný: zkopírujte token znovu tlačítkem kopírování v dialogu a vložte ho přímo. Pokud je dialog už zavřený, token je pryč; vytvořte nový a starou položku smažte.

Co AmazHA vyčistí a co odmítne

Opravitelné případy AmazHA řeší sama, jak při uložení tokenu, tak znovu, když ho telefon načítá pro požadavek:

• Odstraní: mezery, zalomení řádků, znaky nulové šířky, nezlomitelné mezery, značky pořadí bajtů, měkké spojovníky a značky směru textu, kdekoli v tokenu. Žádný z nich nemůže být součástí tokenu Home Assistant, který se skládá z písmen, číslic, -, _ a teček.
• Ořízne z okrajů: rovné i typografické uvozovky, zpětné apostrofy a francouzské uvozovky.
• Odebere ze začátku: vložené Bearer (s jakoukoli velikostí písmen), protože AmazHA to slovo doplňuje sama.

Čištění nedokáže opravit viditelný znak, který žádný token neobsahuje, typicky … z kopie, která byla useknutá. AmazHA nehádá: odmítne takový token vůbec poslat, takže k Home Assistant nedorazí žádný požadavek a nezapočítá se žádné neúspěšné přihlášení. Obrazovka Home Assistant v nastavení ukáže Neplatný token s vysvětlením „Token obsahuje znak, který token Home Assistanta mít nemůže — obvykle jde o useknutou kopii (…). Zkopírujte znovu celý token ze svého profilu Home Assistanta › Zabezpečení a vložte jej výše.“ Hodinky ukážou Zkontrolujte token · „Obsahuje neplatný znak — vložte jej znovu“. To je krok 6 návodu Když něco nefunguje.

Chraňte ho

S každým dlouhodobým tokenem zacházejte jako s heslem, které 10 let nevyprší: jeden token na aplikaci, název, který říká, o jakou aplikaci jde, a smazání v den, kdy tu aplikaci přestanete používat. Konkrétně:

• Jeden token na aplikaci nebo zařízení. Když stejný token dáte třem programům, nemůžete jeden zrušit, aniž byste rozbili zbylé dva, a nepoznáte, který z nich volá.
• Pojmenujte ho po aplikaci. „AmazHA“, „Zálohovací skript“, „Tablet na zdi“. Název je vše, co později v seznamu uvidíte; samotný token se už nikdy znovu nezobrazí.
• Občas se na seznam podívejte. U každé položky je vidět, kdy byla vytvořena, a po použití také kdy a odkud byla naposledy použita. Token, který nikdo měsíce nepoužil, je kandidátem na smazání.
• Rušte smazáním. Na kartě Zabezpečení smažte token podle jeho názvu. Aplikace, která ho používala, selže při svém dalším požadavku s chybou 401; ničeho jiného se to nedotkne.
• Pokud mohl token uniknout, smažte ho a vytvořte nový. Smazání je jediný způsob, jak zrušit jednotlivý token; náhradu do aplikace vložíte za minutu.
• Nikdy nevkládejte token do žádosti o podporu, příspěvku na fóru ani na snímek obrazovky. Diagnostika dobré aplikace ho nikdy nepotřebuje.

Smazání všech obnovovacích tokenů na stejné kartě odhlásí vaše zařízení, ale aktuální relaci a vaše dlouhodobé tokeny ponechá, jak uvádí potvrzovací dialog Home Assistant. Dlouhodobé tokeny se ruší jeden po druhém.

V AmazHA

AmazHA potřebuje přesně jeden dlouhodobý token od administrátora, zadaný jednou v nastavení AmazHA v aplikaci Zepp; tento jeden token slouží pro místní i vzdálenou adresu a zůstává ve vašem telefonu. Pole pro připojení jsou k dispozici po odemčení plné verze (jednorázové odemčení, bez předplatného: viz Odemkněte plnou verzi). Potom:

1. Vytvořte token jako administrátor, jak je popsáno výše (kroky 1–3 návodu Připojte Home Assistant).
2. V aplikaci Zepp přejděte do Profil › vaše hodinky › Aplikace › AmazHA › Nastavení a klepněte na Home Assistant (krok 4).
3. Do pole Místní URL (LAN) zadejte adresu, kterou používáte doma, například http://192.168.1.50:8123, a pokud chcete, aby hodinky fungovaly i mimo domov, zadejte adresu zvenku do pole Vzdálená URL. Kterékoli pole může zůstat prázdné.
4. Vložte token do pole Dlouhodobý přístupový token (krok 7).
5. Klepněte na Připojit. Když jsou zadané obě adresy, výsledek ukáže každou zvlášť, LAN a Vzdálený; s jednou adresou uvidíte Připojeno ✓. Pokud token nepatří administrátorovi, objeví se pod tím oranžový řádek popsaný výše.

Jeden token, dvě adresy

Pro vzdálenou adresu druhý token nepotřebujete. Token patří uživateli, ne adrese: stejný token platí, ať požadavek k Home Assistant dorazí přes vaši Wi-Fi, nebo zvenku. Doma AmazHA používá místní adresu; vzdálená slouží jen pro chvíle, kdy je telefon pryč. Jedinou výjimkou je uživatel s volbou Local access only popsaný výše, jehož token je zvenku záměrně odmítnut.

Kam token putuje a kam ne

Hodinky nikdy nekomunikují s Home Assistant přímo. Dělá to váš telefon přes aplikaci Zepp a token je uložený tam, v telefonu. Posílá se jen na váš server Home Assistant, v hlavičce Authorization vlastních požadavků telefonu; nikdy se neposílá do hodinek, které přes své spojení Bluetooth s telefonem dostávají jen to, co zobrazují. AmazHA nemá žádný vlastní server, přes který by token procházel, a hlášení pro podporu ho nikdy neobsahuje.

Co telefon s tokenem dělá, požadavek po požadavku:

Poslední řádek je funkce senzorů hodinek, která do Home Assistant posílá tep, kroky, baterii a další údaje vašich hodinek Amazfit jako zařízení integrace Mobile App: popisuje ji článek Posílejte data z hodinek Amazfit do Home Assistant.

Když AmazHA hlásí něco o tokenu

Malý kód pod nápisem Offline je tu pro podporu: pokud nám napíšete, fotka hodinek přesně řekne, co selhalo. Všechna ostatní hlášení, která hodinky mohou ukázat, najdete v návodu Když něco nefunguje.