Home Assistant는 로컬 및 원격 세션을 어떻게 인증하나요?

에바 왕

IceWhale author

에바 왕 는 기술 작가 그리고 이자 ZimaSpace의 상주 장인입니다. 평생을 기술에 열정을 가진 사람으로서 홈랩과 오픈소스 소프트웨어에 열정을 가지고 있으며,복잡한 기술 개념을 쉽게 이해할 수 있는 실습 가이드로 번역하는 데 전문성을 가지고 있습니다.에바는 셀프 호스팅이 어렵지 않고 재미있어야 한다고 믿습니다. 그녀의 튜토리얼을 통해 커뮤니티가 하드웨어 설정의 신비를 풀도록돕고 있습니다. 첫 NAS 구축부터 Docker 컨테이너 마스터링까지.

How Does Home Assistant Authenticate Local and Remote Sessions?

Home Assistant는 일반적으로 LAN용 인증 시스템과 원격 액세스용 인증 시스템을 별도로 만들지 않습니다. 사용자는 Home Assistant 인스턴스에서 인증하고, 애플리케이션은 토큰을 받습니다. 이후 해당 토큰은 요청이 로컬 URL, Home Assistant Cloud, VPN 또는 리버스 프록시를 통해 들어오는지와 관계없이 API 또는 WebSocket 세션을 인증합니다.

로컬 사용과 원격 사용 사이에서 달라지는 부분은 주로 네트워크 경로입니다. 여기에는 DNS, TLS, 프록시, 터널링, 외부 접근 가능 여부가 포함됩니다. 경로와 ID를 분리해 유지하는 것이 중요한 이유는, Home Assistant 사용자의 자격 증명과 토큰이 여전히 유효하더라도 원격 URL이 작동하지 않으면 로그인 문제처럼 보일 수 있기 때문입니다.

애플리케이션은 한 번 인증하고 액세스 토큰과 리프레시 토큰을 받습니다

Home Assistant의 애플리케이션 인증 흐름은 인증 코드를 생성한 다음 액세스 토큰과 리프레시 토큰을 발급합니다. 수명이 짧은 액세스 토큰은 API 호출에 사용되고, 리프레시 토큰을 사용하면 애플리케이션이 매 세션마다 사용자에게 로그인을 요청하지 않고 새 액세스 토큰을 받을 수 있습니다.

최신 인증 API 문서에는 인증, 액세스 토큰, 리프레시 토큰 및 HTTP Bearer 토큰 흐름이 설명되어 있습니다. 액세스 토큰이 유효하지 않게 되면 HTTP API 요청은 401을 반환하며, 클라이언트는 토큰을 갱신하거나 다시 인증해야 합니다.

이를 통해 사용자의 장기적인 인증 권한과 특정 API 자격 증명의 짧은 수명을 분리할 수 있습니다.

WebSocket 세션은 실시간 상태 스트리밍이 시작되기 전에 인증합니다

프런트엔드와 여러 애플리케이션은 Home Assistant가 변경 사항마다 서버를 폴링하지 않고도 상태 및 이벤트 업데이트를 스트리밍할 수 있도록 WebSocket 연결을 열어 둡니다.

Home Assistant의 WebSocket API는 명시적인 인증 단계를 정의합니다. 서버가 auth_required를 보내면 클라이언트가 액세스 토큰을 반환하고, auth_ok 응답이 있어야만 연결이 명령 단계로 전환됩니다.

유효하지 않은 토큰은 해당 세션을 종료합니다. 인증 교환이 시작되기 전에 발생하는 네트워크 시간 초과는 서버가 토큰을 받은 후 반환하는 auth_invalid 응답과는 다른 문제입니다.

원격 액세스는 클라이언트가 Home Assistant에 연결하는 방식을 바꿉니다

기본적으로 Home Assistant는 로컬에서 사용됩니다. 원격 액세스는 Home Assistant Cloud, VPN, 리버스 프록시 또는 의도적으로 보안을 적용한 직접 연결 경로를 통해 제공할 수 있습니다. 각 방식은 라우팅과 노출 범위를 변경하지만, 목적지는 여전히 동일한 Home Assistant 인스턴스입니다.

최신 원격 액세스 가이드는 Cloud, VPN, 리버스 프록시 및 포트 포워딩 경로를 구분해 설명합니다. 리버스 프록시는 신뢰 경계도 추가합니다. Home Assistant가 전달된 요청 정보를 제공하도록 허용된 프록시를 알고 있어야 하기 때문입니다.

따라서 사용자를 새로 만들 필요 없이도 라우터, DNS, 인증서 또는 프록시를 변경하는 것만으로 원격 액세스가 중단될 수 있습니다.

Featured

ZimaCube 2 개인용 클라우드 홈 NAS

ZimaCube2

로컬 세션과 원격 세션은 네트워크 위험도가 다를 수 있습니다

LAN 연결은 신뢰할 수 있는 홈 네트워크 내부에 머무를 수 있지만, 원격 연결은 공용 인터넷이나 오버레이 네트워크를 통과할 수 있습니다. 따라서 안전한 원격 설계에서는 동일한 Home Assistant 계정 시스템을 기반으로 암호화, 프록시 강화, VPN 정책 및 다중 인증을 추가합니다.

“동일한 인증 모델”을 “동일한 네트워크 노출”로 해석해서는 안 됩니다. 직접 공개 포트를 사용하는 방식, 관리형 클라우드 터널, 프라이빗 VPN은 모두 최종적으로 Home Assistant 액세스 토큰을 제출하더라도 서로 다른 공격 표면을 만듭니다.

ZimaSpace의 원격 액세스 보안 가이드에서는 인증된 세션을 어떤 경로로 전달할지 결정하는 데 필요한 보다 폭넓은 네트워크 경계를 설명합니다.

경로 오류와 인증 오류를 구분하세요

증상	가능성이 높은 계층	첫 번째 구분 기준
원격 호스트 이름이 확인되지 않음	DNS / 경로	인증이 시작되지 않음
로그인 전에 TLS 또는 프록시 오류 발생	원격 진입 경로	직접 로컬 액세스 테스트
Home Assistant API에서 HTTP 401 반환	토큰/인증	클라이언트 토큰 갱신 또는 재인증
WebSocket에서 auth_invalid 반환	토큰/인증	클라이언트 인증 상태 확인
로컬은 작동하지만 원격 경로는 실패	DNS/VPN/프록시/NAT	먼저 사용자를 초기화하지 않기

가장 이해하기 쉬운 모델은 ID를 먼저 확인하고, 그다음 세션 토큰을 확인한 뒤, 마지막으로 네트워크 경로를 확인하는 것입니다. 로컬 클라이언트와 원격 클라이언트는 서로 매우 다른 네트워크 경로로 진입할 수 있지만, 인스턴스에 도달한 후에는 모두 유효한 Home Assistant 인증이 필요합니다.

자주 묻는 질문

Home Assistant에 원격으로 액세스하려면 다른 비밀번호나 계정이 필요한가요?

아니요. 원격 클라이언트는 일반적으로 동일한 Home Assistant 사용자 시스템을 통해 인증합니다. 원격 방식은 클라이언트가 인스턴스에 연결하는 방법을 바꿀 뿐, 해당 계정을 관리하는 사용자 데이터베이스를 바꾸지 않습니다.

원격 URL만 작동하지 않을 때 토큰을 삭제해야 하나요?

첫 단계로 토큰을 삭제할 필요는 없습니다. 먼저 DNS, VPN, 프록시, TLS 또는 NAT를 통해 Home Assistant에 도달하는지 확인하세요. 네트워크 경로를 사용할 수 없다는 이유만으로 토큰을 초기화하거나 재인증하지 말고, Home Assistant 자체가 인증을 거부할 때 토큰을 초기화하거나 재인증해야 합니다.