ZimaOS에는 이제 문서화된 OpenAPI가 제공되지만, /v1/users/login을 호출하고 반환된 액세스 토큰을 재사용하던 2024년의 이전 방식은 영구 API 키 시스템이 아니라 세션 인증 방식으로 간주해야 합니다. IceWhale은 해당 스레드에서 영구 토큰을 지원하지 않는다고 명시했습니다.
현재 OpenAPI 문서는 개인 액세스 토큰 UI보다 생성된 클라이언트와 서비스 엔드포인트에 중점을 둡니다. Home Assistant 같은 자동화에서는 인증을 로컬에서 처리하고 로그인 엔드포인트를 공개적으로 노출하지 않으며, 세션 토큰이 만료되면 다시 인증하도록 통합을 설계하세요.
현재 OpenAPI 사양 사용
현재 ZimaOS OpenAPI 가이드는 개발자에게 IceWhale의 OpenAPI 저장소를 안내하며, 스토리지 및 기타 서비스를 위한 생성된 클라이언트를 보여 줍니다.
기존 로그인 엔드포인트는 액세스 토큰을 반환했음
원본 스레드에서 사용자는 /v1/users/login으로 자격 증명을 POST하고 응답에서 액세스 토큰을 확인했습니다. 이후 IceWhale은 영구 토큰을 지원하지 않는다고 밝혔습니다.
임시 토큰을 영구적으로 하드코딩하지 말 것
세션 토큰은 만료되거나 로그인 또는 보안 설정 변경으로 무효화될 수 있습니다. 자격 증명이나 갱신된 세션 상태를 안전하게 저장하고 인증 실패를 명시적으로 처리하세요.
신뢰할 수 있는 네트워크에서 API 사용
내부 ZimaOS API 엔드포인트를 공용 인터넷에 포트 포워딩하지 마세요. 먼저 LAN, VPN 또는 ZimaClient/비공개 네트워크를 통해 서버에 연결하세요.
로그인 API를 개발하기 전에 기존 ZimaOS 빌드 업데이트
ZimaOS는 1.5.0 이하 버전에서 /v1/users/login에 영향을 주는 심각한 인증 우회 취약점이 있었으며, 1.5.3에서 패치되었습니다. 항상 최신 안정 릴리스를 기준으로 개발하세요.
ZimaOS 로그인 보안 권고에 해당 보안 경계가 설명되어 있습니다.
Home Assistant에서 최소 권한 사용
온도, CPU, 전력 또는 디스크 메트릭을 수집하는 경우 통합에 필요한 데이터만 요청하세요. 꼭 필요한 경우가 아니라면 사용자, 스토리지 또는 시스템 설정을 변경할 수 있는 자동화를 함께 구축하지 마세요.
API 버전 변경에 대비
현재 가이드에는 /v2/local_storage와 같은 버전이 지정된 서비스 경로가 언급되어 있습니다. 모든 2024년 엔드포인트가 앞으로도 계속 권장되는 인터페이스라고 가정하지 마세요. 현재 OpenAPI 스키마에서 클라이언트를 생성하거나 업데이트하세요.
비공개 액세스 가이드에서 더 안전한 네트워크 모델을 확인할 수 있습니다.
401 응답 시 다시 인증
견고한 통합은 HTTP 401 또는 세션 만료 응답을 동일한 토큰으로 반복 재시도할 신호가 아니라 새 세션을 얻어야 한다는 신호로 처리해야 합니다. 로그인 장애로 인해 요청이 무한 반복되지 않도록 재시도 횟수를 제한하세요.
로그에 토큰을 기록하지 말 것
Home Assistant 디버그 로그, 셸 기록, 스크린샷 및 Git 저장소는 토큰이 유출되기 쉬운 장소입니다. 진단 정보를 공개적으로 공유하기 전에 인증 헤더와 JSON 로그인 응답을 삭제하거나 마스킹하세요.
사용하는 API 계약 고정
통합에서 생성된 OpenAPI 클라이언트를 사용하는 경우 스키마와 버전을 코드와 함께 보관하고, 다시 생성하기 전에 upstream 변경 사항을 검토하세요. 이렇게 하면 엔드포인트나 응답 형식이 변경되었을 때 자동화가 조용히 중단되지 않고 변경 사실을 명확히 확인할 수 있습니다.
FAQ
ZimaOS에서 영구 API 토큰을 생성할 수 있나요?
IceWhale의 원본 답변에서는 영구 토큰을 지원하지 않는다고 했으며, 현재 공개 문서에도 개인 액세스 토큰 UI가 설명되어 있지 않습니다.
기존 액세스 토큰은 어떻게 얻었나요?
포럼 사용자는 /v1/users/login에 성공적으로 POST한 후 토큰을 얻었습니다.
API를 인터넷에 공개해야 하나요?
아니요. 신뢰할 수 있는 비공개 네트워크에서 사용하고 현재 지원되는 방식으로 인증하세요.
Home Assistant 통합을 구축할 수 있나요?
가능합니다. 다만 토큰 만료, API 버전 변경 및 최소 권한 액세스를 고려해 설계하세요.
