Интеграция Home Assistant с Authentik и Keycloak: компонент hass-oidc-auth

313

На данный момент 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):

1. Откройте HACS -> Integrations.
2. Добавьте пользовательский репозиторий: christiaangoossens/hass-oidc-auth.
3. Установите интеграцию «OpenID Connect».
4. Перезагрузите Home Assistant.

После установки настройка производится только через YAML.

---

Настройка (Configuration)

Конфигурация добавляется в файл configuration.yaml. Компонент поддерживает два режима работы клиента: Public (рекомендуемый для большинства) и Confidential.

1. Базовая конфигурация (Public Client)

Этот вариант проще и безопаснее для статических конфигов, так как не требует хранения секрета клиента.

• 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:

3. Управление ролями (RBAC)

Вы можете управлять правами доступа внутри Home Assistant, используя группы из вашего IdP.

Если параметр roles.user задан, пользователи без этой группы не смогут войти. Если не задан — пускает всех аутентифицированных.

4. Кастомный маппинг полей (Claims)

Если ваш провайдер отдает нестандартные поля (например, sAMAccountName вместо preferred_username), их можно переназначить:

---

Продвинутые сценарии

Миграция существующих пользователей

Если у вас уже есть настроенные пользователи в HA и вы хотите переключить их на SSO без потери истории и настроек дашбордов, используйте функцию автоматического связывания.

1. Включите опцию временно:
   
   Default

   auth_oidc: features: automatic_user_linking: true

   1 2 3 4

   auth_oidc:   features:     automatic_user_linking: true

2. Убедитесь, что username в IdP совпадает с username в Home Assistant.
3. Выполните вход через OIDC. Система свяжет внешнюю учетку с локальной.
4. Важно: После миграции отключите эту опцию (false), так как она игнорирует локальный MFA и может быть небезопасна при совпадении имен.

Работа с самоподписанными сертификатами (Self-Hosted Lab)

Если ваш Authentik/Keycloak работает по HTTPS с самоподписанным сертификатом или CA локальной лаборатории, HA может выдавать ошибку SSL: CERTIFICATE_VERIFY_FAILED.

Решение 1 (Правильное): Указать путь к CA сертификату.

Решение 2 (Тестовое, небезопасно): Отключить проверку TLS.

---

Использование

Вход в систему

После настройки и перезагрузки, на странице входа Home Assistant может не появиться кнопка OIDC сразу (зависит от версии фронтенда и кэша).

1. Для инициализации входа используйте специальный URL:
   https://<ВАШ_HA_URL>/auth/oidc/welcome
   или
   https://<ВАШ_HA_URL>/auth/oidc/login (для прямого редиректа).
2. После первого входа интеграция попытается внедрить JS-код, чтобы добавить кнопку «Войти через OIDC» на стандартный экран логина HA.

Создание пользователей

По умолчанию, если пользователь входит через OIDC и его нет в базе HA:

• Создается новый системный пользователь.
• Автоматически создается сущность «Человек» (Person), привязанная к этому пользователю (можно отключить через features.automatic_person_creation: false).

Пример для Authentik

Для Authentik конфигурация со стороны HA минимальна, так как он хорошо поддерживает стандарты:

В самом Authentik нужно создать Provider типа «OAuth2/OpenID Provider» и Application, привязанный к нему.

Читайте про локальные умные дома:
🌐 Сайт
📱 Телеграм
📰 Дзен

Даже просто подбор, перевод и оформление статей требуют времени. А самостоятельный обзор устройств требует еще и финансовых вложений. Если Вы хотите больше обзоров, Вы можете помочь автору.