На данный момент Home Assistant «из коробки» не поддерживает внешний OIDC (кроме использования платных решений Nabu Casa или сложных прокси-схем с заголовками). Компонент hass-oidc-auth решает проблему, позволяя подключить HA к вашему центральному Identity Provider (IdP), например Authentik, Keycloak, Authelia или Pocket ID.
Ключевые возможности
- SSO (Single Sign-On): Единый вход во все сервисы умного дома.
- Управление ролями: Автоматическое назначение прав администратора или пользователя в HA на основе групп в вашем IdP.
- Provisioning: Автоматическое создание пользователей и сущностей Person при первом входе.
- Связывание аккаунтов: Возможность миграции существующих локальных пользователей HA на OIDC-аккаунты.
Важно: Проект находится в стадии Alpha. Разработчик предупреждает о возможных ошибках, поэтому использование в критически важных (production) средах требует осторожности.
Установка
Внимание:
Дзен не умеет корректно отображать скрипты. Для сохранения структуры скрипта рекомендуем читать оригинал статьи на сайте:
Установка выполняется стандартно через HACS (Home Assistant Community Store):
- Откройте HACS -> Integrations.
- Добавьте пользовательский репозиторий: christiaangoossens/hass-oidc-auth.
- Установите интеграцию «OpenID Connect».
- Перезагрузите Home Assistant.
После установки настройка производится только через YAML.
Настройка (Configuration)
Конфигурация добавляется в файл configuration.yaml. Компонент поддерживает два режима работы клиента: Public (рекомендуемый для большинства) и Confidential.
1. Базовая конфигурация (Public Client)
Этот вариант проще и безопаснее для статических конфигов, так как не требует хранения секрета клиента.
Default
auth_oidc:
client_id: "home-assistant" # ID, который вы создали в Authentik/Keycloak
discovery_url: "https://auth.example.com/application/o/home-assistant/.well-known/openid-configuration"
display_name: "Войти через Authentik" # Надпись на кнопке входа
- discovery_url: Ссылка на автоконфигурацию провайдера. Обычно заканчивается на .well-known/openid-configuration.
- Callback URL: При настройке провайдера (IdP) укажите Redirect URI в формате:
https://<ВАШ_HA_URL>/auth/oidc/callback
2. Конфигурация с секретом (Confidential Client)
Если ваш IdP требует client secret (например, некоторые настройки Keycloak), добавьте его через secrets:
Default
auth_oidc:
client_id: "home-assistant"
client_secret: !secret oidc_client_secret
discovery_url: "..."
3. Управление ролями (RBAC)
Вы можете управлять правами доступа внутри Home Assistant, используя группы из вашего IdP.
Default
auth_oidc:
# ... базовые настройки ...
roles:
admin: "ha_admins" # Пользователи из этой группы IdP станут админами в HA
user: "ha_users" # Обязательная группа для обычного доступа
Если параметр roles.user задан, пользователи без этой группы не смогут войти. Если не задан — пускает всех аутентифицированных.
4. Кастомный маппинг полей (Claims)
Если ваш провайдер отдает нестандартные поля (например, sAMAccountName вместо preferred_username), их можно переназначить:
Default
auth_oidc:
claims:
username: "uid" # Поле логина
display_name: "fullName" # Поле отображаемого имени
groups: "roles" # Поле, где лежат группы пользователя
Продвинутые сценарии
Миграция существующих пользователей
Если у вас уже есть настроенные пользователи в HA и вы хотите переключить их на SSO без потери истории и настроек дашбордов, используйте функцию автоматического связывания.
- Включите опцию временно:Defaultauth_oidc:features:automatic_user_linking: true
- Убедитесь, что username в IdP совпадает с username в Home Assistant.
- Выполните вход через OIDC. Система свяжет внешнюю учетку с локальной.
- Важно: После миграции отключите эту опцию (false), так как она игнорирует локальный MFA и может быть небезопасна при совпадении имен.
Работа с самоподписанными сертификатами (Self-Hosted Lab)
Если ваш Authentik/Keycloak работает по HTTPS с самоподписанным сертификатом или CA локальной лаборатории, HA может выдавать ошибку SSL: CERTIFICATE_VERIFY_FAILED.
Решение 1 (Правильное): Указать путь к CA сертификату.
Default
auth_oidc:
network:
tls_ca_path: /config/my-local-ca.pem
Решение 2 (Тестовое, небезопасно): Отключить проверку TLS.
Default
auth_oidc:
network:
tls_verify: false
Использование
Вход в систему
После настройки и перезагрузки, на странице входа Home Assistant может не появиться кнопка OIDC сразу (зависит от версии фронтенда и кэша).
- Для инициализации входа используйте специальный URL:
https://<ВАШ_HA_URL>/auth/oidc/welcome
или
https://<ВАШ_HA_URL>/auth/oidc/login (для прямого редиректа). - После первого входа интеграция попытается внедрить JS-код, чтобы добавить кнопку «Войти через OIDC» на стандартный экран логина HA.
Создание пользователей
По умолчанию, если пользователь входит через OIDC и его нет в базе HA:
- Создается новый системный пользователь.
- Автоматически создается сущность «Человек» (Person), привязанная к этому пользователю (можно отключить через features.automatic_person_creation: false).
Пример для Authentik
Для Authentik конфигурация со стороны HA минимальна, так как он хорошо поддерживает стандарты:
Default
auth_oidc:
client_id: "ha-client"
discovery_url: "https://authentik.lan/application/o/home-assistant/.well-known/openid-configuration"
roles:
admin: "Admins" # Группа в Authentik
В самом Authentik нужно создать Provider типа «OAuth2/OpenID Provider» и Application, привязанный к нему.