Como é que o Home Assistant autentica sessões locais e remotas?
O Home Assistant normalmente não cria um sistema de autenticação para a LAN e outro para o acesso remoto. O utilizador autoriza-se na instância do Home Assistant, as aplicações recebem tokens e esses tokens autenticam sessões de API ou WebSocket, quer o pedido chegue através de um URL local, do Home Assistant Cloud, de uma VPN ou de um proxy inverso.
O que muda entre a utilização local e remota é sobretudo o caminho de rede: DNS, TLS, proxy, túnel e acessibilidade pública. Manter a rota e a identidade separadas é importante, porque um URL remoto avariado pode parecer um problema de início de sessão, mesmo quando as credenciais e os tokens do utilizador do Home Assistant continuam válidos.
As aplicações autorizam-se uma vez e recebem tokens de acesso e de atualização
O fluxo de autenticação de aplicações do Home Assistant gera um código de autorização e, em seguida, um token de acesso e um token de atualização. O token de acesso, de curta duração, é utilizado nas chamadas à API; o token de atualização permite à aplicação pedir um novo token de acesso sem solicitar ao utilizador que inicie sessão em todas as sessões.
A atual documentação da API de autenticação descreve o fluxo de autorização, token de acesso, token de atualização e token Bearer HTTP. Quando um token de acesso deixa de ser válido, um pedido à API HTTP devolve 401 e o cliente deve atualizar o token ou voltar a autorizar-se.
Isto separa a autorização de longo prazo de um utilizador da curta duração de uma credencial de API específica.
As sessões WebSocket autenticam-se antes de começar a transmissão de estados em tempo real
A interface e muitas aplicações mantêm um WebSocket aberto para que o Home Assistant possa transmitir atualizações de estados e eventos sem consultar o servidor a cada alteração.
A API WebSocket do Home Assistant define uma fase de autenticação explícita: o servidor envia auth_required, o cliente devolve um token de acesso e apenas uma resposta auth_ok coloca a ligação na fase de comandos.
Um token inválido termina essa sessão. Um tempo limite de rede antes do início da troca de autenticação é uma falha diferente de uma resposta auth_invalid depois de o servidor ter recebido o token.
O acesso remoto altera a forma como o cliente chega ao Home Assistant
Por predefinição, o Home Assistant é local. O acesso remoto pode ser disponibilizado através do Home Assistant Cloud, de uma VPN, de um proxy inverso ou de um caminho direto devidamente protegido. Cada opção altera o encaminhamento e a exposição, mas o destino continua a ser a mesma instância do Home Assistant.
O guia atual de acesso remoto distingue rotas através da Cloud, VPN, proxy inverso e reencaminhamento de portas. Os proxies inversos também introduzem um limite de confiança, porque o Home Assistant tem de saber qual o proxy autorizado a fornecer informações encaminhadas sobre os pedidos.
É por isso que uma alteração no router, no DNS, no certificado ou no proxy pode interromper o acesso remoto sem ser necessário recriar utilizadores.
As sessões locais e remotas podem ter riscos de rede diferentes
Uma ligação à LAN pode permanecer dentro de uma rede doméstica de confiança, enquanto uma ligação remota pode atravessar a Internet pública ou uma rede sobreposta. Um design remoto seguro acrescenta, por isso, encriptação, reforço da segurança do proxy, políticas de VPN e autenticação multifator ao mesmo sistema de contas do Home Assistant.
Não interprete “mesmo modelo de autenticação” como “mesma exposição de rede”. Uma porta pública direta, um túnel cloud gerido e uma VPN privada apresentam superfícies de ataque diferentes, mesmo quando os três acabam por enviar tokens de acesso do Home Assistant.
O guia de segurança do acesso remoto da ZimaSpace fornece o contexto mais amplo sobre os limites de rede para decidir qual o caminho que deve transportar essas sessões autenticadas.
Separe as falhas de rota das falhas de autenticação
| Sintoma | Camada provável | Primeira distinção |
|---|---|---|
| O nome de anfitrião remoto não é resolvido | DNS / rota | A autenticação ainda não começou |
| Erro de TLS ou do proxy antes do início de sessão | Caminho de entrada remoto | Teste o acesso local direto |
| A API do Home Assistant devolve HTTP 401 | Token/autenticação | Atualize o token ou volte a autorizar o cliente |
| O WebSocket devolve auth_invalid | Token/autenticação | Valide a autorização do cliente |
| O acesso local funciona, mas a rota remota falha | DNS/VPN/proxy/NAT | Não reponha os utilizadores primeiro |
O modelo mental mais simples é: identidade primeiro, token de sessão depois e rota de rede por último. Os clientes locais e remotos podem entrar através de caminhos de rede muito diferentes, mas continuam a precisar de uma autorização válida do Home Assistant quando chegam à instância.
Perguntas frequentes
O acesso remoto ao Home Assistant requer uma palavra-passe ou conta diferente?
Não. Normalmente, os clientes remotos autenticam-se no mesmo sistema de utilizadores do Home Assistant. O método remoto altera a forma como o cliente chega à instância, não a base de dados de utilizadores responsável pela conta.
Devo eliminar os tokens quando apenas o URL remoto deixa de funcionar?
Não como primeiro passo. Primeiro confirme que o DNS, a VPN, o proxy, o TLS ou o NAT chegam ao Home Assistant. Reponha ou volte a autorizar os tokens quando o próprio Home Assistant rejeitar a autenticação, e não apenas porque o caminho de rede está indisponível.
Produtos recomendados
Centro de Tecnologia e IA
Mais para Ler
Estado em tempo de execução vs. estado persistente no Home Assistant: o que tem de sobreviver ao reinício?
O Home Assistant não persiste todos os valores em tempo real; a configuração, os registos, os estados restaurados selecionados, o histórico e os dados...
Porque é que as consultas ao histórico do Home Assistant podem ficar mais lentas à medida que os dados do Recorder aumentam?
O crescimento do gravador pode aumentar o custo das consultas do Histórico quando o intervalo solicitado abrange mais linhas, as falhas de cache aumentam...
Porque é que o Home Assistant reconstrói um estado diferente após reiniciar um contentor?
Reiniciar o contentor não equivale à perda de estado: o Home Assistant reconstrói o estado de execução a partir da configuração persistente, das integrações,...
