Zugangsdaten in Home Assistant mit secrets.yaml schützen¶
Veröffentlicht am 22. August 2026 · Geschätzte Lesezeit: 4 Minuten
Mit secrets.yaml trennst du Passwörter, Token und API-Schlüssel von deiner normalen YAML-Konfiguration. Home Assistant ersetzt beim Einlesen jede !secret-Referenz durch den passenden lokalen Wert. Das schützt vor versehentlichem Teilen der Hauptkonfiguration, verschlüsselt die Geheimnisse aber nicht. Die Umstellung eines ersten Eintrags dauert etwa 15 Minuten.
Voraussetzungen
- Administratorzugriff auf Home Assistant
- Zugriff auf den Konfigurationsordner, zum Beispiel über File editor oder Studio Code Server
- Mindestens ein in YAML eingetragener geheimer Wert
- Ein aktuelles vollständiges Home-Assistant-Backup
1. Vollständiges Backup erstellen¶
Erstelle unter Einstellungen → System → Backups ein vollständiges Backup und lade eine Kopie auf ein geschütztes, getrenntes Gerät herunter. Darin befinden sich später auch die Geheimnisse aus secrets.yaml.
Backup vertraulich behandeln
Ein Home-Assistant-Backup kann Passwörter, Schlüssel und persönliche Verlaufsdaten enthalten. Verwende die angebotene Verschlüsselung, bewahre das Backup geschützt auf und teile es nicht öffentlich.
2. Geheime Werte erkennen¶
Öffne configuration.yaml im Konfigurationsordner. Kandidaten sind beispielsweise Passwörter, lange Token oder API-Schlüssel, die direkt in einem YAML-Abschnitt stehen.
Dieses Beispiel zeigt nur Platzhalter. <api-benutzer> und <api-passwort> stehen für Werte, die ausschließlich in deiner eigenen Installation vorhanden sind.
rest:
- resource: https://example.invalid/api
authentication: basic
username: "<api-benutzer>"
password: "<api-passwort>"
Nicht jede Integration verwendet YAML
Viele aktuelle Integrationen werden vollständig in der Oberfläche eingerichtet. Deren gespeicherte Zugangsdaten lassen sich nicht einfach durch !secret in configuration.yaml ersetzen. Diese Anleitung gilt für Werte, die tatsächlich in YAML stehen.
3. secrets.yaml anlegen¶
Öffne im selben Ordner wie configuration.yaml die Datei secrets.yaml oder lege sie dort neu an. Verwende verständliche Namen ohne Leerzeichen. Ersetze die beiden markierten Platzhalter ausschließlich in deiner lokalen Datei durch deine echten Werte.
Anführungszeichen sind bei Passwörtern sinnvoll, besonders wenn sie Zeichen wie #, : oder { enthalten. Die Datei wird nicht mit !include eingebunden: Home Assistant sucht !secret-Werte automatisch in secrets.yaml.
4. Konfiguration auf !secret umstellen¶
Ersetze in configuration.yaml nur die bisherigen Klartextwerte. Einrückung und restlicher Abschnitt bleiben unverändert.
rest:
- resource: https://example.invalid/api
authentication: basic
username: !secret rest_api_user
password: !secret rest_api_password
Der Name hinter !secret muss exakt dem Schlüssel in secrets.yaml entsprechen. An dieser Stelle gehören keine Anführungszeichen um die gesamte !secret-Anweisung.
5. Konfiguration prüfen und neu laden¶
Speichere beide Dateien. Öffne anschließend in Home Assistant Entwicklerwerkzeuge → YAML und starte die Konfigurationsprüfung. Je nach Installation findest du die Prüfung auch unter Einstellungen → System.
Starte Home Assistant erst neu, wenn die Prüfung keinen Fehler meldet. Prüfe danach, ob die betroffene Integration weiterhin Daten empfängt oder Befehle ausführt.
Typische Meldungen und Ursachen:
Secret ... not defined: Der Name fehlt insecrets.yamloder ist anders geschrieben.- YAML-Fehler: Einrückung, Doppelpunkt oder Anführungszeichen sind fehlerhaft.
- Datei nicht gefunden:
secrets.yamlliegt nicht im Konfigurationsordner oder hat einen falschen Namen. - Integration nicht verfügbar: Der neue Wert wurde falsch kopiert oder die Integration unterstützt diese YAML-Stelle nicht.
6. Datei vor Git und Freigaben schützen¶
Falls du deine Konfiguration mit Git verwaltest, ergänze im Stamm des Projekts die Datei .gitignore. Der folgende Block verhindert, dass secrets.yaml und lokale Sicherungskopien neu eingecheckt werden.
Prüfe trotzdem vor jeder Veröffentlichung die vorgemerkten Git-Dateien. War secrets.yaml bereits Teil eines Commits, reicht .gitignore nicht aus: Entferne die Datei aus der Versionsgeschichte und ersetze alle darin enthaltenen Schlüssel beim jeweiligen Dienst.
secrets.yaml ist nicht verschlüsselt
Die Trennung verhindert vor allem versehentliches Teilen. Jeder mit Dateizugriff auf den Home-Assistant-Konfigurationsordner kann die Werte weiterhin lesen. Begrenze deshalb Benutzerzugänge und Dateifreigaben auf das notwendige Maß.
7. Änderungen, Backup und Rückweg¶
Ändert sich ein Passwort oder Token, bearbeitest du nur den passenden Wert in secrets.yaml, prüfst die Konfiguration erneut und lädst die betroffene Integration neu oder startest Home Assistant neu.
Falls Home Assistant nach der Umstellung nicht startet, öffne die Konfigurationsdateien über deinen bisherigen Dateizugriff und korrigiere zuerst die gemeldete Zeile. Reicht das nicht, stellst du das vollständige Backup aus Schritt 1 wieder her. Bewahre die ursprünglichen Werte bis zur erfolgreichen Funktionsprüfung ausschließlich in deinem Passwortmanager auf, nicht in einer zweiten ungeschützten YAML-Datei.
8. Quellen und Video¶
Die Funktionsweise von !secret, der Speicherort und die Suche in übergeordneten Konfigurationsordnern sind in der offiziellen Home-Assistant-Dokumentation zu Storing secrets beschrieben. Hinweise zu configuration.yaml und zur Konfigurationsprüfung stehen in der allgemeinen Konfigurationsdokumentation. Eine anschauliche Ergänzung ist das öffentlich verfügbare Video Secrets and Splitting YAML. Quellen und Vorgehen wurden am 22. August 2026 geprüft.
Fertig¶
Deine YAML-Konfiguration verweist jetzt mit !secret auf getrennt gespeicherte Zugangsdaten. Die Umstellung ist erfolgreich, wenn die Konfigurationsprüfung fehlerfrei bleibt und die betroffene Integration nach dem Neustart genauso funktioniert wie zuvor.