Långlivade åtkomsttokens i Home Assistant: skapa en, varför admin krävs och ”fungerar men visar inget”

Det korta svaret

En långlivad åtkomsttoken ersätter lösenordet för appar och skript: du skapar den i din Home Assistant-profil, på fliken Säkerhet, under Långlivade åtkomsttokens, och Home Assistant visar den bara en gång. Den är giltig i 10 år. Vissa appar behöver en token från en administratör, eftersom delar av API:t, som /api/template, nekar alla andra användare med en 401.

Resten av artikeln går igenom varje del: vad token är, var du hittar den, hur du kopierar den utan att förstöra den, varför frågan om admin spelar roll, hur du testar en token med två curl-kommandon och hur du håller ordning på dina tokens. Exemplet genomgående är AmazHA, en Home Assistant-app för Amazfit-klockor, eftersom den berör varenda en av de här punkterna: den behöver en token, den behöver en administratörs token, och den måste klara tokens som har blivit förvanskade av en kopiering.

Vad en långlivad åtkomsttoken är

En långlivad åtkomsttoken är en inloggningsuppgift som låter ett program agera som din Home Assistant-användare utan att gå via inloggningsskärmen. När du loggar in i webbgränssnittet ger Home Assistant din webbläsare en kortlivad åtkomsttoken (30 minuter) och en uppdateringstoken som förnyar den. Ett skript, en telefonapp eller en klockapp kan inte enkelt köra det inloggningsflödet, så Home Assistant erbjuder en andra sorts token: en som du skapar för hand, kopierar en gång och ger till programmet.

Tre egenskaper spelar roll i praktiken:

• Den är giltig i 10 år. Home Assistants egen dokumentation av autentiserings-API:t säger att långlivade tokens ”är giltiga i 10 år”, och profilsidan upprepar det: varje token är giltig i 10 år från det att den skapades.
• Den visas en gång. Home Assistant sparar inte själva token, så den kan inte visa den igen. Tappar du bort den skapar du en ny.
• Den är användaren som skapade den. En token bär behörigheterna hos användaren som skapade den, varken mer eller mindre. En token som skapats av en administratör är administratör för varje förfrågan den signerar; en token som skapats av en vanlig användare är en vanlig användare.

Token skickas i ett HTTP-huvud med varje förfrågan:

Authorization: Bearer <your token>

Det är allt en klient behöver göra. Det finns inget användarnamn, inget lösenord och ingen session: varje förfrågan med en giltig token i det huvudet godtas som den användaren.

Var du hittar den

Du skapar långlivade åtkomsttokens i din egen användarprofil, på fliken Säkerhet. I Home Assistant-appen eller i en webbläsare:

1. Öppna sidomenyn (menyn ≡ på en telefon) och tryck på ditt namn längst ned.
2. Öppna fliken Säkerhet i din profil.
3. Längre ned på den fliken finns avsnittet Långlivade åtkomsttokens, med listan över de tokens du redan har och knappen Skapa token.

Home Assistants användardokumentation beskriver det på samma sätt: User profile › Security, sidan där du också byter lösenord, ställer in tvåfaktorsautentisering och hanterar uppdateringstokens.

”Jag hittar den inte”

Den vanligaste orsaken är fliken. Profilen öppnas på sina allmänna inställningar (språk, tema och liknande); avsnittet med tokens finns på fliken Säkerhet. Många äldre guider säger att du ska scrolla längst ned på profilsidan, vilket stämde innan profilen delades upp i flikar.

Två andra orsaker:

• Du letar efter någon annans token. Varje användare ser och hanterar bara sina egna tokens. En token som en annan person i hushållet har skapat syns inte i din profil, och du kan inte ta bort den därifrån.
• Du är inloggad som en annan användare än du tror. Kontrollera namnet längst ned i sidomenyn. Om en app behöver en administratörs token (mer om det nedan), se till att namnet tillhör en administratör innan du skapar den.

Skapa och kopiera den

Att skapa en token tar fyra tryck; det är när den kopieras som det går fel. Stegen:

1. På fliken Säkerhet, under Långlivade åtkomsttokens, trycker du på Skapa token.
2. Home Assistant ber dig ge token ett namn. Använd appens namn, till exempel AmazHA. Namnen måste vara unika bland dina tokens.
3. Nästa dialogruta visar token med varningen att du ska kopiera din åtkomsttoken eftersom den inte kommer att visas igen. Kopiera den nu, hela.
4. Stäng dialogrutan. Token visas nu i listan under sitt namn, med den dag den skapades.

En token är en lång sträng av bokstäver, siffror, - och _, i tre delar åtskilda av punkter. Längden är orsaken till de flesta kopieringsproblem: den får inte plats på en rad, så en slarvig markering tar bara en del av den, och vissa appar förkortar en lång sträng på skärmen med en ellips (…) och kopierar sedan det de visar.

Praktiska vanor som undviker problem:

• Använd kopieringsknappen i dialogrutan, inte en manuell markering.
• Klistra in den direkt i appen som behöver den. En omväg via en chatt, ett mejl eller en anteckningsapp kan lägga till osynliga tecken, typografiska citattecken eller radbrytningar.
• Lägg inte till Bearer framför den om inte appen uttryckligen ber om hela huvudet. Nästan varje app lägger till det ordet själv.
• Om du behöver den på en annan enhet, skapa en andra token där i stället för att skicka runt den första.

Varför vissa appar behöver en administratörs token

Vissa appar behöver en administratörs token eftersom Home Assistant reserverar några API-slutpunkter för administratörer, och en token kan bara göra det som dess användare kan göra. Det tydligaste exemplet är mallslutpunkten, POST /api/template, som renderar en Jinja-mall på servern och returnerar resultatet.

I Home Assistants källkod har vyn som betjänar den, APITemplateView i homeassistant/components/api/__init__.py, sin post-metod dekorerad med @require_admin. Den dekoratorn kontrollerar användaren bakom token; om användaren inte är administratör kastar den Unauthorized, som Home Assistants HTTP-lager gör om till 401 Unauthorized. Dokumentationen av REST-API:t markerar också slutpunkten som ”Admin”.

Den är inte den enda. REST-API:t delar sig ungefär så här:

Varför skulle en app alls behöva mallslutpunkten? Därför att viss information inte finns i de vanliga REST-slutpunkterna. Det tydligaste fallet är områden: /api/states returnerar varje entitet med dess läge och attribut, men inte området den hör till, och REST-API:t har ingen slutpunkt som listar områden. En mall kan fråga efter dem: area_id(entity_id) och area_name(...) returnerar det område som Home Assistant fastställer för varje entitet, via entitetens egen inställning eller dess enhets. En app som vill visa ditt hem rum för rum, så som Home Assistants instrumentpaneler gör, renderar därför en mall, och behöver en administratör för det.

Är det klokt att ge en app administratörsbehörighet?

Home Assistants egna säkerhetsråd är att bara ge administratörsåtkomst till konton som behöver den. En app som behöver /api/template är ett sådant fall, och du har två rimliga sätt att hantera det:

• Skapa token som din egen administratörsanvändare. Det enklaste alternativet. Token listas under din profil med sitt namn, och om du tar bort den återkallas bara den appen.
• Skapa en separat administratörsanvändare för appen i Inställningar › Personer, logga in som den användaren en gång och skapa token där. Dess uppgifter om ”senast använd” hålls åtskilda från dina, och du kan stänga av hela användaren senare. Låt den vara aktiv så länge appen använder den: tokens för en inaktiverad användare slutar fungera. Kryssa inte i Local access only om appen också ansluter utanför hemmet, av skälet i avsnittet om 401 nedan.

Hur du än gör förtjänar token samma omsorg som ett lösenord: en administratörs token kan göra allt du kan göra i Home Assistant.

”Den fungerar men visar ingenting”: 401 på /api/template

När en app ansluter utan problem och ändå inte visar något är orsaken nästan alltid en token från en användare som inte är administratör. Anslutningstestet går igenom, eftersom de flesta appar testar med GET /api/, och den slutpunkten godtar varje giltig token. Lägena går också att läsa. Bara mallförfrågan misslyckas, med en 401, och en app som bygger sin enhetslista från den mallen har till slut ingenting att visa.

Förloppet, sett från appen:

1. GET /api/ med token: 200, {"message": "API running."}. Appen rapporterar ”ansluten”.
2. GET /api/states/...: 200. Lägena finns där.
3. POST /api/template för att koppla entiteter till områden: 401. Inga områden, alltså inga rum, alltså en tom skärm.

Det som gör det förvirrande är att inget annat ser fel ut. Adressen är rätt, token är giltig, Home Assistant är igång. Till och med åtgärder kan fungera: POST /api/services/... är öppen för vanliga användare, så en lampa kan fortfarande slås om från appen med samma token.

Vad Home Assistant visar

Home Assistant räknar varje 401 den skickar som ett misslyckat inloggningsförsök, även den från administratörskontrollen. Loggen får en varning som börjar med ”Login attempt or request with invalid authentication from …” och anger adressen som förfrågan kom från (hemma oftast din telefon eller din server), och webbgränssnittet visar aviseringen Login attempt failed (inloggningsförsöket misslyckades). Om du har slagit på IP-blockering med ett visst antal inloggningsförsök innan blockeringen, kommer tillräckligt många sådana 401 att blockera den adressen: från och med då får den 403 Forbidden på allt, tills du tar bort den från ip_bans.yaml och startar om Home Assistant.

Ser du alltså upprepade aviseringar om misslyckade inloggningsförsök som pekar på din egen telefon, är en app med en vanlig användares token som anropar en slutpunkt reserverad för administratörer en förklaring, förutom en token som har tagits bort.

Hur AmazHA upptäcker det och säger det

AmazHA, som läser dina områden via /api/template, letar avsiktligt efter det här fallet i stället för att lämna dig med en tom klocka:

• När du trycker på Anslut kontrollerar telefonen först adressen med GET /api/ och skickar sedan en trivial mall, {{ 1 }}, till /api/template. Om den mallen nekas med en 401, en 403 eller en 400, flaggas token som inte en administratörs. Skärmen Home Assistant visar då Ansluten ✓ med en orange rad under: ”Ansluten, men denna token har inte administratörsbehörighet, så klockan kan inte läsa in dina entiteter. Skapa en långlivad token från en Home Assistant-användare med rollen Administrator och klistra in den ovan.”
• På klockan, när rummen inte kan läsas in eftersom områdesmallen nekas, visar hemskärmen bannern Admin-token krävs · ”Din token saknar adminbehörighet — använd en Home Assistant-adminanvändare”, i stället för ett allmänt Offline.
• I supportrapporten som du kan skicka från AmazHA-inställningarna säger raden ”HA token” om token kändes igen som en administratörs, utan att någonsin innehålla själva token.

Lösningen är densamma i alla fall: skapa en ny långlivad token medan du är inloggad som administratör, klistra in den och tryck på Anslut igen. Steg 5 i När något krånglar visar det i videon.

Så kontrollerar du att en användare är administratör

Öppna Inställningar › Personer och sedan fliken Användare. Kolumnen Grupp säger Administratörer för en administratör; öppnar du en användare ser du reglaget Administratör (administratörer kan hantera användare, enheter, automationer och instrumentpaneler).

Det finns ett snabbare test: om sidomenyn för kontot du är inloggad med inte har något Inställningar alls, är den användaren inte administratör. Home Assistant registrerar sin konfigurationspanel som reserverad för administratörer, så vanliga användare ser den aldrig. Logga i så fall ut, logga in som administratör och skapa token där.

Kontrollera det själv med curl

Du kan testa vilken token som helst på en minut från en dator i samma nätverk, med två curl-kommandon: ett mot /api/, som varje giltig token klarar, och ett mot /api/template, som bara en administratörs token klarar. Exemplen använder 192.168.1.50:8123 som adress till Home Assistant; byt ut den mot din. De körs som de står i en terminal på macOS eller Linux.

För att hålla token borta från skalets historik läser du först in den i en variabel. Klistra in token när kommandot väntar och tryck sedan på Enter:

read -rs HA_TOKEN

Test 1: är token giltig?

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

En giltig token svarar {"message":"API running."} och HTTP 200. Tänk på snedstrecket på slutet: slutpunkten är /api/, inte /api.

Test 2: tillhör token en administratör?

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

En administratörs token får den renderade mallen, 1, och HTTP 200. En vanlig användares token får HTTP 401.

Så läser du de två resultaten tillsammans:

Två förbehåll. För det första testar detta token från din dator; en app på din telefon kan ta en annan väg till Home Assistant, särskilt när du inte är hemma. För det andra bevisar ett godkänt test 1 ensamt mycket lite för appar som behöver områden: det är just det test som en vanlig användares token klarar.

401:an från ”Local access only”

En användare som har Local access only påslaget kan bara logga in från ditt lokala nätverk, och Home Assistant tillämpar samma regel på den användarens tokens. En förfrågan från en adress utanför ditt nätverk, eller en som kommer via Home Assistant Cloud, nekas med en 401, även om samma token fungerar perfekt hemma. Om en app fungerar på ditt wifi och misslyckas med en 401 när du är borta, öppna användaren i Inställningar › Personer och titta på det reglaget innan du misstänker fjärradressen. För själva fjärradressen, läs Home Assistant när du är borta, på klockan.

Problem vid inklistring

En token som ser rätt ut kan ändå vara fel, eftersom det du klistrade in inte alltid är det som Home Assistant gav dig. Home Assistant jämför token tecken för tecken, så ett enda tecken för mycket eller för lite blir en ogiltig token och en 401. De vanliga bovarna:

Botemedlet är detsamma för alla: kopiera token igen med dialogrutans kopieringsknapp och klistra in den direkt. Om dialogrutan redan är stängd är token borta; skapa en ny och ta bort den gamla posten.

Vad AmazHA rensar, och vad den nekar

AmazHA hanterar själv de fall som går att åtgärda, både när du sparar token och igen när telefonen läser den för att göra en förfrågan:

• Tas bort: blanksteg, radbrytningar, tecken med noll bredd, hårda blanksteg, byte-ordningsmarkeringar, mjuka bindestreck och riktningsmarkeringar, var som helst i token. Inget av dem kan vara en del av en Home Assistant-token, som består av bokstäver, siffror, -, _ och punkter.
• Skalas bort från ändarna: raka och typografiska citattecken, grava accenter och gåsögon.
• Tas bort från början: ett inklistrat Bearer (med vilka versaler som helst), eftersom AmazHA lägger till det ordet själv.

Det som rensning inte kan åtgärda är ett synligt tecken som ingen token innehåller, oftast … från en kopia som blev avklippt. AmazHA gissar inte: den vägrar att skicka den token alls, så ingen förfrågan når Home Assistant och inget misslyckat inloggningsförsök räknas. Skärmen Home Assistant i inställningarna visar Ogiltig token, med förklaringen ”Token innehåller ett tecken som en Home Assistant-token inte kan ha — oftast en avklippt kopia (…). Kopiera hela token igen från din Home Assistant-profil › Säkerhet och klistra in den ovan.” Klockan visar Kontrollera token · ”Den innehåller ett ogiltigt tecken — klistra in den igen”. Det är steg 6 i När något krånglar.

Håll den säker

Behandla varje långlivad token som ett lösenord som inte går ut på 10 år: en token per app, ett namn som säger vilken app, och ta bort den samma dag som du slutar använda appen. Konkret:

• En token per app eller enhet. Om du ger samma token till tre program kan du inte återkalla en utan att bryta de andra två, och du kan inte se vilket av dem som anropar.
• Döp den efter appen. ”AmazHA”, ”Backupskript”, ”Väggplatta”. Namnet är allt du ser i listan senare; själva token visas aldrig igen.
• Titta på listan då och då. Varje post visar när den skapades och, när den väl har använts, när och varifrån den senast användes. En token som ingen har använt på flera månader är en kandidat för borttagning.
• Återkalla genom att ta bort. På fliken Säkerhet tar du bort token med dess namn. Appen som använde den misslyckas vid sin nästa förfrågan, med en 401; inget annat berörs.
• Om en token kan ha läckt, ta bort den och skapa en ny. Att ta bort är det enda sättet att återkalla en enskild token; ersättaren läggs in i appen på en minut.
• Klistra aldrig in en token i en supportförfrågan, ett foruminlägg eller en skärmbild. En bra apps diagnostik behöver den aldrig.

Om du tar bort alla uppdateringstokens från samma flik loggas dina enheter ut, men den aktuella sessionen och dina långlivade tokens finns kvar, som Home Assistants bekräftelsedialog säger. Långlivade tokens återkallas en i taget.

I AmazHA

AmazHA behöver exakt en långlivad token, från en administratör, som anges en gång i AmazHA-inställningarna i Zepp-appen; den enda token gäller både för den lokala adressen och för fjärradressen, och den stannar på din telefon. Anslutningsfälten blir tillgängliga när fullversionen är upplåst (en engångsupplåsning, ingen prenumeration: se Lås upp fullversionen). Sedan:

1. Skapa token som administratör, som ovan (steg 1–3 i Anslut Home Assistant).
2. I Zepp-appen går du till Profil › din klocka › Appar › AmazHA › Inställningar och trycker sedan på Home Assistant (steg 4).
3. Ange din adress hemma i Lokal URL (LAN), till exempel http://192.168.1.50:8123, och, om du vill att klockan ska fungera när du är borta också, den externa adressen i Fjärr-URL. Båda fälten får vara tomma.
4. Klistra in token i Långlivad åtkomsttoken (steg 7).
5. Tryck på Anslut. Med båda adresserna angivna visar resultatet var och en, LAN och Fjärr; med en adress står det Ansluten ✓. Om token inte tillhör en administratör visas den orange raden som beskrivs ovan under resultatet.

En token, två adresser

Du behöver ingen andra token för fjärradressen. En token hör till en användare, inte till en adress: samma token är giltig oavsett om förfrågan når Home Assistant via ditt wifi eller utifrån. Hemma använder AmazHA den lokala adressen; fjärradressen är bara till för när telefonen är borta. Det enda undantaget är användaren med Local access only som beskrivs ovan, vars token avsiktligt nekas utifrån.

Vart token går, och vart den inte går

Klockan pratar aldrig direkt med Home Assistant. Det gör din telefon, via Zepp-appen, och token sparas där, på telefonen. Den skickas bara till din Home Assistant-server, i huvudet Authorization på telefonens egna förfrågningar; den skickas aldrig till klockan, som bara får det den visar via sin Bluetooth-förbindelse med telefonen. AmazHA har ingen egen server som token skulle kunna passera, och supportrapporten innehåller den aldrig.

Vad telefonen gör med token, förfrågan för förfrågan:

Den sista raden är funktionen för klocksensorer, som skickar din Amazfits puls, steg, batteri och mer till Home Assistant som en enhet i integrationen Mobile App: Skicka din Amazfits data till Home Assistant går igenom den.

När AmazHA säger något om token

Den lilla koden under Offline finns där för supporten: om du skriver till oss talar ett foto av klockan om exakt vad som gick fel. För alla andra meddelanden som klockan kan visa, se När något krånglar.