One Time Service

Home Assistant Add-on

Gitlab Github Add-on Repo

Führe Services mit einem einmaligen Token außerhalb von Home Assistant aus!

Mit „One Time Service“ können öffentlich zugängliche Tokens zur einmaligen Verwendung erstellt werden, die einen Home Assistant-Service ohne Authentifizierung ausführen. Das ist z.B. für Hausbesucher sinnvoll, die diese i.d.R. kein Konto auf der Home Assistant-Instanz haben.

Mögliche Use-cases:

  • Besucher können sich die Haustür selbst öffnen, wenn niemand zu Hause ist
  • Nachbarn können in Notfällen Benachrichtungen zu schicken, indem ein intelligentes RGB-Licht auf rot geschaltet wird
  • Nachbarn können den Staubsaugerroboter starten, wenn alle im Urlaub sind

Installation und Konfiguration

Supervisor addon add repository

Dieser Button fügt dem konfigurierten Home Assistant die Add-on-Repository unter https://git.leon.wtf/leon/leon.wtf-home-assistant-addons hinzu. Im Add-on Store taucht dann “One Time Service” auf, welches von dort aus wie jedes andere Add-on installiert, konfiguriert und geupdatet werden kann.

Das Add-on stellt einen separaten Port mit Webserver zur Verfügung (standardmäßig 1337/tcp), der von einem Reverse-Proxy verwendet werden kann, um es im Internet bereitzustellen. Währenddessen kann der Home Assistant selbst hinter der Firewall bleiben. Dem Add-on muss der vom Reverse-Proxy festgelegte Hostname über die Konfigurationsvariable public_token_base_url mitgegeben werden. Auf Basis dieser Base-URL erstellt One Time Service die One Time Tokens, welche verteilt werden können.

Funktionsweise

Nachdem das Add-on installiert wurde, kann das Dashboard in der Seitenleiste von Home Assistant angezeigt werden. Das Dashboard zeigt alle konfigurierten Service Calls und Tokens an.

Ein Service Call kann ein möglicherweise komplexer Aufruf eines Home Assistant-Services sein, der zur besseren Wiederverwendbarkeit innerhalb des Add-ons definiert wird. Ein Service Call kann von mehreren Tokens gleichzeitig verwendet werden. Er wird mithilfe von Home Assistants nativer YAML-Syntax definiert, kann also z.B. direkt aus den Entwicklerwerkzeugen kopiert werden.

Ein Token ist so konfiguriert, dass es einen zuvor erstellten Service Call ausführt. Er kann optional mit einem Kommentar, einer Begrenzung für die Ausführungsanzahl und/oder einer Ablaufzeit versehen werden. Der Token verweist auf das öffentliche Einlöseportal, auf welchem der jeweilige Service ausgeführt werden kann und der konfigurierte Kommentar, sowie die verbleibende Ausführungsanzahl angezeigt wird.

Definition eines neuen Service Calls

Service call creation

Erstellen eines neuen Tokens aus einem Service Call

Token creation

Öffentliches Einlöseportal

Token submission portal

One Time Service kann sogar so konfiguriert werden, dass Benachrichtigungen an eine Home Assistant Notify-Entität gesendet werden sollen, sobald ein Token verwendet wurde.

Einsicht in die Entwicklung

Für die Entwicklung des Add-ons wurde im Backend Go eingesetzt. Das Dashboard ist in React geschrieben, während das öffentliche Einlöseportal in Plain-HTML und JavaScript geschrieben ist. Für Styling wurde Pico CSS eingesetzt.

Home Assistant Add-ons sind unter der Haube nur Docker Container, welche durch den Home Assistant Supervisor verwaltet werden. Da Docker Container auf den Betriebssystemkernel zurückgreifen, sind sie – im Gegensatz zu virtuellen Maschinen – architekturabhängig. Das ist vor allen Dingen bei Home Assistant ein Problem, da dieser auf mehreren Architekturen ausgeführt wird. Dazu gehören full-size Computer mit x86/amd64, aber auch z.B. der Raspberry Pi mit armv7/armv8, jeweils als 32- und 64-bit-Variante. Es ist dementsprechend notwendig, das Add-on für all diese Architekturen bereitzustellen.

Damit der Ganze Build-Prozess nicht bei jeder Änderung von Hand durchgeführt werden muss, werden Gitlab CI/CD Pipelines für das Bauen der Docker Images verwendet. Da ich keine Multi-Architecture-Runtimes zur Verfügung habe, muss auf Cross-Compilation zurückgegriffen werden. Glücklicherweise erlaubt Docker das mit dem neuen BuildKit. Mit docker buildx kann ein Builder erzeugt werden, der ein Multiarch-Manifest für mehrere Architekturen erzeugen kann. Aktuell wird das Image registry.git.leon.wtf/leon/one-time-service/multiarch für linux/amd64, linux/arm64 und linux/arm/v7 erzeugt. Home Assistant erkennt und installiert die zu verwendende Architektur automatisch!

Zu BuildKit folgt in Kürze auch ein Blog-Eintrag!