Tokens de acesso de longa duração do Home Assistant: criar um, porquê de admin e «liga, mas não mostra nada»

A resposta curta

Um token de acesso de longa duração substitui a palavra-passe para apps e scripts: cria-o no seu perfil do Home Assistant, no separador Segurança, em Tokens de acesso de longa duração, e o Home Assistant só o mostra uma vez. É válido durante 10 anos. Algumas apps precisam do token de um administrador, porque partes da API, como /api/template, recusam qualquer outro utilizador com um 401.

O resto deste artigo percorre cada peça: o que é o token, onde o encontrar, como o copiar sem o estragar, porque é que a questão do administrador importa, como testar um token com dois comandos curl e como manter os tokens sob controlo. O exemplo prático é o AmazHA, uma app Home Assistant para relógios Amazfit, porque passa por todos estes pontos: precisa de um token, precisa do token de um administrador e tem de lidar com tokens que chegam estragados por um copiar e colar.

O que é um token de acesso de longa duração

Um token de acesso de longa duração é uma credencial que permite a um programa agir como o seu utilizador do Home Assistant sem passar pelo ecrã de início de sessão. Quando inicia sessão na interface web, o Home Assistant entrega ao seu browser um token de acesso curto (30 minutos) e um token de atualização que o renova. Um script, uma app de telemóvel ou uma app de relógio não conseguem fazer esse início de sessão com facilidade, por isso o Home Assistant oferece um segundo tipo de token: um que cria à mão, copia uma vez e entrega ao programa.

Na prática, contam três propriedades:

• É válido durante 10 anos. A própria documentação da API de autenticação do Home Assistant diz que os tokens de longa duração são válidos durante 10 anos, e a página do perfil repete-o: cada token é válido durante 10 anos a partir da criação.
• É mostrado uma vez. O Home Assistant não guarda o próprio token, por isso não o pode voltar a mostrar. Se o perder, cria um novo.
• É o utilizador que o criou. Um token tem as permissões do utilizador que o criou, nem mais nem menos. Um token criado por um administrador é administrador em todos os pedidos que assina; um token criado por um utilizador normal é um utilizador normal.

O token viaja num cabeçalho HTTP em cada pedido:

Authorization: Bearer <your token>

É tudo o que um cliente tem de fazer. Não há nome de utilizador, nem palavra-passe, nem sessão: qualquer pedido com um token válido nesse cabeçalho é aceite como esse utilizador.

Onde o encontrar

Os tokens de acesso de longa duração criam-se no seu próprio perfil de utilizador, no separador Segurança. Na app Home Assistant ou num browser:

1. Abra o menu lateral (o menu ≡ num telemóvel) e toque no seu nome, em baixo.
2. No seu perfil, abra o separador Segurança.
3. Mais abaixo nesse separador está a secção Tokens de acesso de longa duração, com a lista dos tokens que já tem e um botão Criar token.

A documentação do Home Assistant para utilizadores diz o mesmo: Perfil do utilizador › Segurança, a página onde também muda a palavra-passe, configura a autenticação multifator e gere os tokens de atualização.

«Não o encontro»

O motivo mais comum é o separador. O perfil abre nas definições gerais (idioma, tema e afins); a secção dos tokens está no separador Segurança. Muitos guias antigos dizem para descer até ao fundo da página do perfil, o que era verdade antes de o perfil ser dividido em separadores.

Mais dois motivos:

• Está à procura do token de outra pessoa. Cada utilizador vê e gere apenas os seus próprios tokens. Um token criado por outra pessoa da casa não aparece no seu perfil, e não o pode apagar a partir daí.
• Tem sessão iniciada com outro utilizador que não o que pensa. Veja o nome em baixo, no menu lateral. Se uma app precisar do token de um administrador (mais sobre isso abaixo), confirme que esse nome pertence a um administrador antes de o criar.

Criá-lo e copiá-lo

Criar um token são quatro toques; é ao copiá-lo que as coisas correm mal. Os passos:

1. No separador Segurança, em Tokens de acesso de longa duração, toque em Criar token.
2. O Home Assistant pede-lhe um nome para o token. Use o nome da app, por exemplo AmazHA. Os nomes têm de ser únicos entre os seus tokens.
3. A janela seguinte mostra o token com um aviso para o copiar já, porque não voltará a ser mostrado. Copie-o agora, completo.
4. Feche a janela. O token aparece agora na lista com o seu nome e o dia em que foi criado.

Um token é uma longa sequência de letras, algarismos, - e _, em três partes separadas por pontos. O seu comprimento é a razão da maioria dos problemas de cópia: não cabe numa linha, por isso uma seleção descuidada apanha só parte dele, e algumas apps encurtam no ecrã uma sequência longa com reticências (…) e depois copiam o que mostram.

Hábitos práticos que evitam problemas:

• Use o botão de copiar da janela, e não uma seleção manual.
• Cole-o diretamente na app que precisa dele. Um desvio por um chat, um email ou uma app de notas pode acrescentar caracteres invisíveis, aspas tipográficas ou quebras de linha.
• Não acrescente Bearer à frente, a não ser que a app peça explicitamente o cabeçalho inteiro. Quase todas as apps acrescentam essa palavra sozinhas.
• Se precisar dele noutro dispositivo, crie lá um segundo token em vez de andar a enviar o primeiro.

Porque é que algumas apps precisam do token de um administrador

Algumas apps precisam do token de um administrador porque o Home Assistant reserva alguns endpoints da API aos administradores, e um token só pode fazer o que o seu utilizador pode fazer. O exemplo mais claro é o endpoint de templates, POST /api/template, que processa um template Jinja no servidor e devolve o resultado.

No código-fonte do Home Assistant, a vista que o serve, APITemplateView em homeassistant/components/api/__init__.py, tem o seu método post decorado com @require_admin. Esse decorador verifica o utilizador por trás do token; se o utilizador não for administrador, lança Unauthorized, que a camada HTTP do Home Assistant transforma em 401 Unauthorized. A documentação da API REST também marca o endpoint como «Admin».

Não é o único. A API REST divide-se mais ou menos assim:

Então, porque é que uma app precisaria do endpoint de templates? Porque há informação que não está nos endpoints REST simples. O caso mais claro são as áreas: /api/states devolve todas as entidades com o seu estado e os seus atributos, mas não a área a que pertencem, e a API REST não tem nenhum endpoint que liste as áreas. Um template pode pedi-las: area_id(entity_id) e area_name(...) devolvem a área que o Home Assistant atribui a cada entidade, pela definição da própria entidade ou pela do seu dispositivo. Uma app que queira mostrar a sua casa divisão a divisão, como fazem os painéis do Home Assistant, processa portanto um template, e precisa de um administrador para isso.

Dar direitos de administrador a uma app é boa ideia?

O próprio conselho de segurança do Home Assistant é dar acesso de administrador só às contas que precisam dele. Uma app que precisa de /api/template é um desses casos, e tem duas formas razoáveis de o resolver:

• Crie o token com o seu próprio utilizador administrador. A opção mais simples. O token aparece no seu perfil com o seu nome, e apagá-lo revoga apenas essa app.
• Crie um utilizador administrador separado para a app em Configuração › Pessoas, inicie sessão uma vez com esse utilizador e crie lá o token. As informações de «última utilização» ficam separadas das suas, e mais tarde pode desativar o utilizador inteiro. Mantenha-o ativo enquanto a app o usar: os tokens de um utilizador desativado deixam de funcionar. Não marque Local access only (apenas acesso local) se a app também se ligar de fora de casa, pela razão explicada na secção sobre o 401 mais abaixo.

Em qualquer dos casos, o token merece o cuidado que dá a uma palavra-passe: o token de um administrador pode fazer tudo o que você pode fazer no Home Assistant.

«Liga, mas não mostra nada»: o 401 em /api/template

Quando uma app se liga com sucesso e mesmo assim não mostra nada, a causa é quase sempre um token de um utilizador que não é administrador. O teste de ligação passa, porque a maioria das apps testa com GET /api/ e esse endpoint aceita qualquer token válido. Os estados também se leem. Só o pedido de template falha, com um 401, e uma app que monta a sua lista de dispositivos a partir desse template fica sem nada para mostrar.

A sequência, do lado da app:

1. GET /api/ com o token: 200, {"message": "API running."}. A app indica «ligado».
2. GET /api/states/...: 200. Os estados estão lá.
3. POST /api/template para associar entidades a áreas: 401. Sem áreas, sem divisões, e o ecrã fica vazio.

O que confunde é que mais nada parece errado. O endereço está certo, o token é válido, o Home Assistant está a funcionar. Até as ações podem funcionar: POST /api/services/... está aberto aos utilizadores normais, por isso uma luz pode continuar a ser ligada a partir da app com o mesmo token.

O que o Home Assistant mostra

O Home Assistant conta cada 401 que envia como um início de sessão falhado, incluindo o da verificação de administrador. O registo recebe um aviso que começa por «Login attempt or request with invalid authentication from …», com o endereço de onde veio o pedido (em casa, normalmente o seu telemóvel ou o seu servidor), e a interface web mostra uma notificação Login attempt failed (tentativa de início de sessão falhada). Se tiver ativado o bloqueio de IP com um número de tentativas antes do bloqueio, um número suficiente desses 401 bloqueia esse endereço: a partir daí recebe 403 Forbidden em tudo, até o retirar de ip_bans.yaml e reiniciar o Home Assistant.

Por isso, se vir notificações repetidas de início de sessão falhado a apontar para o seu próprio telemóvel, uma app com o token de um utilizador normal a chamar um endpoint reservado aos administradores é uma explicação, além de um token que foi apagado.

Como o AmazHA o deteta e o diz

O AmazHA, que lê as suas áreas através de /api/template, verifica este caso de propósito, em vez de o deixar com um relógio vazio:

• Quando toca em Ligar, o telemóvel começa por verificar o endereço com GET /api/ e depois envia um template trivial, {{ 1 }}, para /api/template. Se esse template for recusado com um 401, um 403 ou um 400, o token é assinalado como não sendo de um administrador. O ecrã Home Assistant mostra então Ligado ✓ com uma linha âmbar por baixo: «Ligado, mas este token não tem permissões de administrador, por isso o relógio não consegue carregar as tuas entidades. Cria um token de longa duração num utilizador do Home Assistant com o papel Administrator e cola-o acima.»
• No relógio, quando as divisões não podem ser carregadas porque o template das áreas é recusado, o ecrã inicial mostra o banner É preciso token admin · «O teu token não tem permissões de admin — usa um utilizador admin do Home Assistant», em vez de um Offline genérico.
• No relatório de suporte que pode enviar a partir das definições do AmazHA, uma linha «HA token» indica se o token foi reconhecido como sendo de um administrador, sem nunca incluir o token.

A solução é a mesma em todos os casos: crie um novo token de longa duração com sessão iniciada como administrador, cole-o e toque de novo em Ligar. O passo 5 de Quando algo corre mal mostra-o no vídeo.

Como verificar se um utilizador é administrador

Abra Configuração › Pessoas e depois o separador Utilizadores. A coluna Grupo diz Administradores para um administrador; ao abrir um utilizador, aparece o interruptor Administrador («Administrators can manage users, devices, automations and dashboards.», ou seja, os administradores podem gerir utilizadores, dispositivos, automações e painéis).

Há um teste mais rápido: se o menu lateral da conta com que tem sessão iniciada não tiver nenhuma entrada Configuração, esse utilizador não é administrador. O Home Assistant regista o seu painel de configuração como reservado aos administradores, por isso os utilizadores normais nunca o veem. Nesse caso, termine a sessão, inicie sessão como administrador e crie lá o token.

Verifique-o você mesmo com curl

Pode testar qualquer token num minuto a partir de um computador na mesma rede, com dois comandos curl: um contra /api/, que qualquer token válido passa, e outro contra /api/template, que só o token de um administrador passa. Os exemplos usam 192.168.1.50:8123 como endereço do Home Assistant; substitua-o pelo seu. Funcionam tal como estão num terminal macOS ou Linux.

Para manter o token fora do histórico da shell, leia-o primeiro para uma variável. Cole o token quando o comando ficar à espera e depois carregue em Enter:

read -rs HA_TOKEN

Teste 1: o token é válido?

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

Um token válido responde {"message":"API running."} e HTTP 200. Atenção à barra final: o endpoint é /api/, não /api.

Teste 2: o token é de um administrador?

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

O token de um administrador recebe o template processado, 1, e HTTP 200. O token de um utilizador normal recebe HTTP 401.

Como ler os dois resultados em conjunto:

Duas ressalvas. Primeiro, isto testa o token a partir do seu computador; uma app no seu telemóvel pode seguir outro caminho até ao Home Assistant, sobretudo fora de casa. Segundo, um teste 1 aprovado sozinho prova muito pouco para as apps que precisam das áreas: é exatamente o teste que o token de um utilizador normal passa.

O 401 de «Local access only»

Um utilizador com Local access only (apenas acesso local) ativado só pode iniciar sessão a partir da sua rede local, e o Home Assistant aplica a mesma regra aos tokens desse utilizador. Um pedido vindo de um endereço fora da sua rede, ou que chegue através do Home Assistant Cloud, é recusado com um 401, mesmo que o mesmo token funcione perfeitamente em casa. Se uma app funcionar no seu Wi-Fi e falhar com um 401 fora de casa, abra o utilizador em Configuração › Pessoas e veja esse interruptor antes de suspeitar do endereço remoto. Para o próprio endereço remoto, veja o Home Assistant fora de casa no seu relógio.

Problemas ao colar

Um token que parece certo pode estar errado, porque o que colou nem sempre é o que o Home Assistant lhe deu. O Home Assistant compara o token carácter a carácter, por isso um único carácter a mais ou a menos é um token inválido e um 401. Os culpados habituais:

A cura é a mesma para todos: copie o token de novo com o botão de copiar da janela e cole-o diretamente. Se a janela já estiver fechada, o token perdeu-se; crie um novo e apague a entrada antiga.

O que o AmazHA limpa, e o que recusa

O AmazHA trata sozinho os casos que têm solução, tanto quando guarda o token como de novo quando o telemóvel o lê para fazer um pedido:

• Removidos: espaços, quebras de linha, caracteres de largura zero, espaços não separáveis, marcas de ordem de bytes, hífenes condicionais e marcas de direção, em qualquer ponto do token. Nenhum deles pode fazer parte de um token do Home Assistant, que é feito de letras, algarismos, -, _ e pontos.
• Retiradas das pontas: aspas retas e tipográficas, acentos graves e aspas angulares.
• Retirado do início: um Bearer colado (com quaisquer maiúsculas ou minúsculas), porque o AmazHA acrescenta essa palavra sozinho.

O que a limpeza não consegue resolver é um carácter visível que nenhum token contém, normalmente as … de uma cópia que ficou cortada. O AmazHA não adivinha: recusa-se a enviar esse token, por isso nenhum pedido chega ao Home Assistant e não é contado nenhum início de sessão falhado. O ecrã Home Assistant nas definições mostra Token inválido, com a explicação «O token contém um carácter que um token do Home Assistant não pode ter — normalmente uma cópia cortada (…). Copia outra vez o token completo a partir do teu perfil do Home Assistant › Segurança e cola-o acima.» O relógio mostra Verifica o token · «Tem um carácter inválido — cola-o outra vez». É o passo 6 de Quando algo corre mal.

Mantê-lo seguro

Trate cada token de longa duração como uma palavra-passe que não expira durante 10 anos: um token por app, um nome que diga de que app se trata, e apague-o no dia em que deixar de usar essa app. Em concreto:

• Um token por app ou dispositivo. Se der o mesmo token a três programas, não pode revogar um sem estragar os outros dois, e não consegue saber qual deles está a fazer os pedidos.
• Dê-lhe o nome da app. «AmazHA», «Script de cópia de segurança», «Tablet da parede». O nome é tudo o que vê mais tarde na lista; o próprio token nunca volta a ser mostrado.
• Veja a lista de vez em quando. Cada entrada mostra quando foi criada e, depois de usada, quando e de onde foi usada pela última vez. Um token que ninguém usa há meses é candidato a ser apagado.
• Revogue apagando. No separador Segurança, apague o token pelo nome. A app que o usava falha no pedido seguinte, com um 401; nada mais é tocado.
• Se um token pode ter sido divulgado, apague-o e crie um novo. Apagar é a única forma de revogar um único token; o substituto entra na app num minuto.
• Nunca cole um token num pedido de suporte, numa publicação de fórum ou numa captura de ecrã. Os diagnósticos de uma boa app nunca precisam dele.

Apagar todos os tokens de atualização a partir do mesmo separador termina a sessão nos seus dispositivos, mas mantém a sessão atual e os seus tokens de longa duração, como diz a janela de confirmação do Home Assistant. Os tokens de longa duração revogam-se um a um.

No AmazHA

O AmazHA precisa de exatamente um token de longa duração, de um administrador, introduzido uma vez nas definições do AmazHA dentro da app Zepp; esse único token serve para o endereço local e para o remoto, e fica no seu telemóvel. Os campos da ligação ficam disponíveis depois de desbloquear a versão completa (um desbloqueio único, sem subscrição: veja Desbloquear a versão completa). Depois:

1. Crie o token como administrador, como acima (passos 1–3 de Ligar o Home Assistant).
2. Na app Zepp, vá a Perfil › o seu relógio › Apps › AmazHA › Definições e toque em Home Assistant (passo 4).
3. Introduza o seu endereço de casa em URL local (LAN), por exemplo http://192.168.1.50:8123, e, se quiser que o relógio também funcione fora de casa, o endereço externo em URL remoto. Qualquer um dos campos pode ficar vazio.
4. Cole o token em Token de acesso de longa duração (passo 7).
5. Toque em Ligar. Com os dois endereços definidos, o resultado mostra cada um, LAN e Remoto; com um só endereço, diz Ligado ✓. Se o token não for de um administrador, aparece por baixo a linha âmbar descrita acima.

Um token, dois endereços

Não precisa de um segundo token para o endereço remoto. Um token pertence a um utilizador, não a um endereço: o mesmo token é válido quer o pedido chegue ao Home Assistant pelo seu Wi-Fi quer venha de fora. Em casa, o AmazHA usa o endereço local; o remoto é só para quando o telemóvel está fora. A única exceção é o utilizador com Local access only descrito acima, cujo token é recusado a partir de fora por definição.

Para onde vai o token, e para onde não vai

O relógio nunca fala diretamente com o Home Assistant. Quem fala é o seu telemóvel, através da app Zepp, e o token fica guardado aí, no telemóvel. Só é enviado para o seu servidor Home Assistant, no cabeçalho Authorization dos pedidos do próprio telemóvel; nunca é enviado para o relógio, que recebe apenas o que mostra através da sua ligação Bluetooth com o telemóvel. O AmazHA não tem nenhum servidor próprio por onde o token possa passar, e o relatório de suporte nunca o inclui.

O que o telemóvel faz com o token, pedido a pedido:

A última linha é a função de sensores do relógio, que envia o ritmo cardíaco, os passos, a bateria e mais dados do seu Amazfit para o Home Assistant, como um dispositivo da integração Mobile App: Enviar os dados do seu Amazfit para o Home Assistant explica-a.

Quando o AmazHA diz algo sobre o token

O pequeno código por baixo de Offline existe para o suporte: se nos escrever, uma fotografia do relógio diz exatamente o que falhou. Para todas as outras mensagens que o relógio pode mostrar, veja Quando algo corre mal.