christiaangoossens/hass-oidc-auth

🔐 Đăng nhập OIDC cho Home Assistant — bảo mật, ổn định, không cần hack core

Login vào Home Assistant bằng OpenID Connect — hoạt động "just work" mọi lúc, cho mọi người trong nhà.

hass-oidc-auth là một custom integration cho Home Assistant, triển khai client/relying party (RP) đầy đủ cho OpenID Connect. Dự án cho phép thiết lập môi trường single-sign-on (SSO) trong hệ thống self-hosted / homelab, kết nối Home Assistant với các provider phổ biến như authentik, Authelia, Pocket ID và Keycloak.

Tích hợp này tuân thủ chặt chẽ các đặc tả kỹ thuật: OpenID Connect Core, RFC 6749 (OAuth2), RFC 7519 (JWT), RFC 7636 (PKCE) và RFC 9700 (OAuth2 Security Best Practices). Ba giá trị cốt lõi là bảo mật, ổn định (tối thiểu hóa việc patch core HA để tránh break khi cập nhật), và khả năng tiếp cận (hoạt động tốt với mọi phương thức xác thực theo mặc định).

✨ Điểm nổi bật

• Tuân thủ chuẩn nghiêm ngặt: triển khai đầy đủ OIDC client/RP theo OpenID Connect Core, OAuth2, JWT, PKCE và OAuth2 Security Best Practices
• Tối thiểu hóa patch core HA: giảm rủi ro break khi cập nhật Home Assistant, đảm bảo không mất quyền truy cập
• Hỗ trợ nhiều provider: authentik, Authelia, Pocket ID, Keycloak và bất kỳ OIDC provider nào khác
• Cài đặt qua HACS: đơn giản, tìm kiếm "OpenID Connect" trong HACS là xong
• Hai chế độ cấu hình: hỗ trợ cả UI (Integrations panel) và YAML cho người dùng nâng cao
• Callback URL chuẩn: <your HA URL>/auth/oidc/callback cho cả public client và confidential client
• Tự động chuyển hướng login: mở Home Assistant (web hoặc app) sẽ tự động gửi đến trang OIDC login
• Tài liệu cấu hình chi tiết: hướng dẫn riêng cho từng provider phổ biến trong thư mục docs/provider-configurations

💡 Vì sao đáng chú ý

Điểm khác biệt của hass-oidc-auth so với nhiều integration khác là sự tập trung vào bảo mật và tuân thủ chuẩn. Thay vì tự viết một implementation nhanh gọn, dự án bám sát từng RFC và đặc tả OpenID Connect, kèm theo test suite tập trung vào bảo mật. Điều này đặc biệt quan trọng khi xử lý xác thực — một lỗ hổng nhỏ cũng có thể compromit toàn bộ hệ thống homelab.

Dự án phù hợp cho bất kỳ ai muốn thay thế đăng nhập mặc định của Home Assistant bằng SSO enterprise thông qua authentik, Authelia hoặc Keycloak — mà không cần lo lắng về việc tích hợp sẽ break sau mỗi bản cập nhật HA. Cài đặt qua HACS, cấu hình qua UI, và xong.

#HomeAssistant #OIDC #OAuth2 #OpenIDConnect #HACS #TiniX