Cómo proteger contraseñas de Home Assistant con secrets.yaml

Proteger contraseñas de Home Assistant con secrets.yaml es una de las mejoras más importantes que puedes aplicar cuando tu instalación empieza a crecer. Automatizaciones, scripts, sensores, bases de datos, dispositivos ESPHome y complementos como Zigbee2MQTT pueden acabar almacenando contraseñas, tokens o credenciales directamente en diferentes archivos de configuración.

Eso es precisamente lo que descubrí durante una auditoría de mi instalación con Codex. Había información sensible repartida por distintos archivos y, en el caso de ESPHome, todavía quedaban 21 contraseñas escritas directamente en texto plano.

En este artículo te explico el método que utilicé para localizar esas credenciales, trasladarlas a archivos específicos, revisar cada modificación y comprobar que Home Assistant continuaba funcionando después de cada cambio.

Importante: secrets.yaml permite separar la información privada del resto de la configuración, pero no cifra su contenido. Cualquier persona con acceso al archivo puede leer sus valores. También debes proteger el acceso al sistema, las copias de seguridad y el repositorio donde guardes tu configuración.

Vídeo completo de la reparación.

En el vídeo puedes ver todo el proceso real: análisis inicial, migración de credenciales, validación de Home Assistant, revisión de ESPHome, configuración de Zigbee2MQTT y cuarentena de archivos antiguos.

Contenido del artículo

Qué es secrets.yaml en Home Assistant
Por qué debes proteger tus contraseñas y tokens
Cómo audité Home Assistant con Codex
Cómo mover credenciales a secrets.yaml
Cómo proteger la contraseña de Recorder
Contraseñas y secretos en ESPHome
Credenciales de Zigbee2MQTT
Archivos históricos y copias antiguas
Cómo validar los cambios
Errores que debes evitar
Preguntas frecuentes

Qué es secrets.yaml en Home Assistant

secrets.yaml es un archivo que permite centralizar información sensible utilizada por la configuración YAML de Home Assistant. En lugar de escribir una contraseña, un token o una clave directamente en cada archivo, puedes guardar el valor privado en un único lugar y utilizar una referencia con !secret.

Este sistema puede utilizarse para separar datos como:

Contraseñas de servicios e integraciones.
Tokens de acceso.
Claves de API.
Usuarios y credenciales.
Direcciones privadas de servidores.
Cadenas de conexión a bases de datos.
Claves utilizadas por dispositivos o complementos.

Por ejemplo, una contraseña escrita directamente en un archivo podría tener este aspecto:

rest:
  - authentication: basic
    username: usuario
    password: "MI_CONTRASEÑA_REAL"

Después de mover el valor privado a secrets.yaml, la configuración principal quedaría así:

rest:
  - authentication: basic
    username: usuario
    password: !secret rest_password

Y el valor real se almacenaría únicamente en secrets.yaml:

rest_password: "MI_CONTRASEÑA_REAL"

De esta forma, puedes compartir el primer fragmento para pedir ayuda o documentar tu instalación sin revelar directamente la contraseña.

Por qué proteger contraseñas de Home Assistant con secrets.yaml

Centralizar las credenciales no convierte automáticamente tu instalación en invulnerable, pero reduce varios riesgos habituales y facilita mucho el mantenimiento.

Reduce las exposiciones accidentales

Es muy habitual copiar una automatización, compartir un archivo YAML en un foro o publicar una captura de pantalla para pedir ayuda. Si la contraseña está escrita directamente en el archivo, podría terminar expuesta sin que te des cuenta.

Cuando utilizas !secret, el fragmento compartido solo contiene el nombre de la referencia y no el valor privado.

Facilita las auditorías

Cuando los datos sensibles están repartidos por decenas de archivos, resulta difícil saber cuántas credenciales existen, dónde se utilizan y cuáles han dejado de ser necesarias.

Una estructura ordenada permite revisar con más facilidad:

Qué contraseñas siguen activas.
Qué servicios utilizan cada credencial.
Qué tokens deberían renovarse.
Qué claves pertenecen a integraciones antiguas.
Qué referencias ya no se utilizan.

Simplifica los cambios

Si una misma credencial aparece en varios archivos, cambiarla manualmente en todos ellos aumenta la posibilidad de cometer errores. Una referencia centralizada permite modificar el valor desde un único punto, siempre que la configuración esté correctamente organizada.

Mejora la organización de la instalación

Una instalación mantenida durante años puede acumular archivos de prueba, copias antiguas, configuraciones que ya no se utilizan y credenciales olvidadas. Revisar periódicamente estos elementos ayuda a diferenciar la configuración activa del contenido histórico.

Cómo audité Home Assistant con Codex

Codex puede analizar una estructura de archivos, localizar patrones y proponer modificaciones. Sin embargo, no conviene concederle permiso para cambiar toda la instalación sin supervisión.

La inteligencia artificial debe utilizarse como asistente. La responsabilidad de revisar los cambios, proteger los datos y validar el funcionamiento sigue siendo del administrador de Home Assistant.

1. Crear una copia de seguridad completa

Antes de modificar cualquier archivo, crea una copia de seguridad completa de Home Assistant. También es recomendable guardar una copia fuera del dispositivo principal.

Comprueba que la copia de seguridad se ha creado correctamente.
Descárgala o guárdala en otra ubicación segura.
Conserva la clave necesaria para restaurarla.
Anota los cambios que vas a realizar.
No borres copias anteriores hasta confirmar que todo funciona.

Una copia de seguridad que nunca se ha comprobado no debe considerarse una garantía absoluta. El objetivo es tener un procedimiento de recuperación claro antes de tocar la configuración.

2. Pedir un análisis sin modificar archivos

La primera tarea que pedí a Codex fue revisar la instalación sin escribir ningún cambio. El objetivo era obtener un inventario de posibles datos sensibles antes de decidir qué debía modificarse.

Un prompt inicial puede seguir esta estructura:

Analiza la configuración de Home Assistant y localiza posibles contraseñas,
tokens, claves de API, usuarios, cadenas de conexión y otros datos sensibles.

No modifiques ningún archivo.

Indica:
- archivo y línea aproximada;
- tipo de dato detectado;
- si ya utiliza !secret;
- nivel de riesgo;
- propuesta de migración.

No muestres los valores completos de ninguna credencial.

Esta fase permite revisar el plan antes de conceder permisos de escritura.

3. Clasificar los resultados

No todas las coincidencias encontradas tienen que ser contraseñas reales. Un análisis automático también puede marcar:

Comentarios dentro de los archivos.
Ejemplos de configuración.
Nombres de variables.
Referencias que ya utilizan !secret.
Archivos de prueba o copias antiguas.
Valores generados automáticamente.
Datos pertenecientes a complementos con otra forma de configuración.

Cada coincidencia debe revisarse dentro de su contexto antes de moverla o eliminarla.

4. Trabajar por pequeñas tandas

En lugar de migrar todos los secretos de una sola vez, dividí el proceso en bloques:

Configuración principal de Home Assistant.
Automatizaciones y scripts.
Credenciales de Recorder y de la base de datos.
Dispositivos ESPHome.
Configuración de Zigbee2MQTT.
Archivos históricos y copias antiguas.

Después de cada tanda revisé las diferencias, validé la configuración y comprobé el funcionamiento de los elementos afectados. Este método permite identificar rápidamente qué cambio ha provocado un posible error.

Cómo mover credenciales a secrets.yaml

Para proteger contraseñas de Home Assistant con secrets.yaml, primero debes asignar un nombre descriptivo a cada valor sensible.

Por ejemplo:

mqtt_username: "USUARIO_PRIVADO"
mqtt_password: "CONTRASEÑA_PRIVADA"
database_url: "CADENA_DE_CONEXIÓN_PRIVADA"
camera_api_token: "TOKEN_PRIVADO"

Después, sustituye los valores originales por sus referencias:

username: !secret mqtt_username
password: !secret mqtt_password
token: !secret camera_api_token

Utiliza nombres claros y relacionados con el servicio. Referencias como password1, clave2 o token_nuevo dificultarán el mantenimiento cuando la instalación siga creciendo.

Cómo proteger la contraseña de Recorder y la base de datos

Las cadenas de conexión de bases de datos suelen incluir varios datos sensibles dentro de una sola línea: usuario, contraseña, servidor, puerto y nombre de la base de datos.

Una configuración directa podría tener esta estructura:

recorder:
  db_url: mysql://usuario:contraseña@servidor/base_de_datos

Para evitar que esa cadena quede expuesta dentro de configuration.yaml, puedes trasladarla a secrets.yaml:

recorder:
  db_url: !secret recorder_database_url

Y guardar el valor completo en el archivo de secretos:

recorder_database_url: "mysql://usuario:contraseña@servidor/base_de_datos"

Después de este cambio, comprueba que Recorder inicia correctamente, que no aparecen errores de conexión y que el historial de las entidades continúa registrándose.

Contraseñas y secretos en ESPHome

ESPHome también utiliza archivos YAML y permite separar información sensible mediante referencias a secretos. Esto resulta especialmente útil para las contraseñas Wi-Fi, las claves de la API, las contraseñas OTA y otras credenciales utilizadas por los dispositivos.

Un archivo de dispositivo puede utilizar referencias como estas:

wifi:
  ssid: !secret wifi_ssid
  password: !secret wifi_password

api:
  encryption:
    key: !secret esphome_api_key

ota:
  password: !secret esphome_ota_password

Y el archivo de secretos correspondiente contendría los valores reales:

wifi_ssid: "NOMBRE_DE_LA_RED"
wifi_password: "CONTRASEÑA_WIFI"
esphome_api_key: "CLAVE_PRIVADA"
esphome_ota_password: "CONTRASEÑA_OTA"

En mi auditoría se localizaron 32 referencias relacionadas con contraseñas dentro de ESPHome. Once ya utilizaban correctamente !secret, pero todavía quedaban 21 contraseñas escritas directamente en los archivos de los dispositivos.

La migración se realizó por grupos y las configuraciones afectadas se validaron individualmente. De esta forma, si aparecía un error, era posible identificar rápidamente qué dispositivo o referencia lo había provocado.

No añadas el archivo de secretos de ESPHome a un repositorio público. Revisa también las copias, exportaciones y archivos antiguos que puedan contener las mismas credenciales.

Cómo proteger las credenciales de Zigbee2MQTT

Zigbee2MQTT mantiene su propia configuración y no siempre gestiona los secretos exactamente igual que Home Assistant o ESPHome. El método disponible puede depender de cómo esté instalado, del complemento utilizado y de la versión de la configuración.

Durante la auditoría revisé especialmente:

Dirección del servidor MQTT.
Usuario de MQTT.
Contraseña de MQTT.
Clave de red Zigbee.
Tokens o credenciales del frontend.
Rutas y parámetros privados.

Antes de copiar una referencia !secret dentro de la configuración de Zigbee2MQTT, confirma que el método es compatible con tu instalación. En algunos entornos puede ser necesario utilizar variables de entorno, opciones del complemento u otro sistema específico.

Después de aplicar los cambios, reinicia Zigbee2MQTT y revisa los registros. Debes confirmar que:

La conexión con MQTT se establece correctamente.
El coordinador Zigbee se inicia.
Los dispositivos vuelven a aparecer.
Las automatizaciones relacionadas continúan funcionando.
No se han generado errores de autenticación.

Revisar archivos históricos y copias antiguas

Uno de los puntos más fáciles de olvidar son los archivos que ya no forman parte de la configuración activa. Aunque Home Assistant no los cargue, pueden seguir almacenando contraseñas o tokens todavía válidos.

Algunos ejemplos habituales son:

configuration_old.yaml
automations_backup.yaml
scripts_copia.yaml
config_pruebas.yaml
esphome_dispositivo_antiguo.yaml

En lugar de eliminarlos inmediatamente, puedes moverlos a una carpeta de cuarentena fuera de la configuración activa. Después de comprobar que la instalación funciona correctamente, decide si deben eliminarse o almacenarse de forma segura.

También debes revisar:

Repositorios Git privados o públicos.
Copias guardadas en el ordenador.
Archivos comprimidos antiguos.
Capturas de pantalla.
Mensajes enviados a foros o grupos.
Copias de seguridad almacenadas en servicios externos.

Si una credencial ha sido publicada o compartida, moverla a secrets.yaml no corrige la exposición anterior. En ese caso, debes revocarla o sustituirla.

Cómo validar los cambios sin romper Home Assistant

Mover una contraseña a secrets.yaml no garantiza que la referencia se haya escrito correctamente. Un error en el nombre, la ruta, la indentación o el formato puede impedir que una integración se cargue.

Después de cada bloque de modificaciones sigue este proceso:

Revisa exactamente qué líneas se han añadido, eliminado o modificado.
Confirma que ningún valor privado aparece en la respuesta de Codex.
Comprueba que todas las referencias existen en el archivo de secretos correcto.
Valida la configuración de Home Assistant.
Reinicia únicamente cuando sea necesario.
Revisa los registros después del reinicio.
Prueba las automatizaciones, dispositivos e integraciones afectadas.
Continúa con el siguiente bloque solo cuando el anterior sea estable.

También puedes pedir a Codex que revise las diferencias sin mostrar los valores privados:

Revisa únicamente los cambios realizados en esta tanda.

Comprueba:
- referencias !secret inexistentes;
- errores de indentación;
- nombres duplicados;
- valores que hayan quedado escritos directamente;
- archivos modificados fuera del alcance autorizado.

No muestres el contenido de ninguna contraseña, token o clave.

Errores que debes evitar durante la migración

Permitir que Codex modifique toda la instalación

Una auditoría debería comenzar con permisos de lectura. Autoriza modificaciones únicamente para tareas concretas, archivos conocidos y bloques pequeños.

Migrar todos los secretos de una sola vez

Si modificas decenas de archivos y aparece un error, localizar el origen será mucho más difícil. Trabaja por grupos y valida cada uno antes de continuar.

No revisar las diferencias

Antes de aceptar cualquier modificación automática, revisa las líneas cambiadas. La IA puede interpretar incorrectamente una variable, modificar un archivo equivocado o crear una referencia incompatible.

Confundir separación con cifrado

secrets.yaml sigue siendo un archivo de texto legible. Protege frente a exposiciones accidentales, pero no frente a una persona que ya tenga acceso al sistema de archivos.

Subir secrets.yaml a Git

Comprueba que los archivos de secretos estén excluidos del control de versiones. Revisa también el historial del repositorio: eliminar el archivo actual no garantiza que las credenciales hayan desaparecido de commits anteriores.

No revisar los registros

Que Home Assistant se inicie no significa que todas las integraciones funcionen. Comprueba los registros, el historial, ESPHome, MQTT, Zigbee2MQTT y las automatizaciones relacionadas.

Resultado de la auditoría

Después de completar el proceso:

Las credenciales quedaron mejor centralizadas.
Las 21 contraseñas directas de ESPHome fueron sustituidas por referencias.
La conexión de la base de datos se revisó y migró.
Zigbee2MQTT se comprobó después de modificar su configuración.
Los archivos históricos quedaron separados de la configuración activa.
Cada bloque fue validado antes de continuar con el siguiente.

La mejora más importante no fue simplemente utilizar inteligencia artificial. Lo verdaderamente importante fue establecer un método de trabajo seguro:

Analizar, revisar, modificar por bloques, validar y documentar.

Vídeos relacionados

Cómo instalar e integrar Codex en Visual Studio Code

Auditoría completa de Home Assistant utilizando Codex

Home Assistant y VS Code: el paso que te falta para editarlo todo

Preguntas frecuentes sobre secrets.yaml

¿secrets.yaml cifra las contraseñas?

No. El archivo separa los valores privados del resto de la configuración, pero continúa almacenándolos como texto legible. Debes proteger el acceso al sistema, las copias de seguridad y cualquier equipo desde el que edites los archivos.

¿Puedo utilizar !secret en automations.yaml?

Puede utilizarse en configuraciones YAML compatibles con esta etiqueta. Después de sustituir un valor, valida siempre la configuración y prueba la automatización afectada.

¿ESPHome utiliza el mismo secrets.yaml que Home Assistant?

ESPHome puede trabajar con su propio archivo de secretos. Antes de compartir valores entre diferentes entornos, revisa qué credenciales necesita realmente cada uno y evita conceder acceso innecesario a todos los secretos de la instalación.

¿Codex puede realizar toda la migración automáticamente?

Puede localizar patrones y proponer modificaciones, pero no deberías aplicar cambios masivos sin supervisión. Revisa cada diferencia, trabaja por bloques y valida después de cada tanda.

¿Debo cambiar las contraseñas que encuentre?

Si una credencial ha aparecido en un repositorio, una captura de pantalla, un foro, una copia compartida o cualquier ubicación no controlada, lo recomendable es revocarla y crear una nueva. Trasladarla a secrets.yaml no elimina una exposición anterior.

¿Qué ocurre si Home Assistant no arranca después del cambio?

Revisa el nombre de la referencia, la indentación, la ubicación del archivo y los registros. Si no puedes identificar rápidamente el problema, restaura el último bloque modificado o utiliza la copia de seguridad creada antes de comenzar.

Conclusión

Proteger contraseñas de Home Assistant con secrets.yaml ayuda a mantener una configuración más ordenada y reduce la posibilidad de publicar accidentalmente contraseñas, tokens o claves privadas.

Codex puede acelerar la búsqueda de datos sensibles y ayudar a preparar las modificaciones, pero no sustituye una estrategia de seguridad. El proceso debe ser reversible, supervisado y dividido en pequeñas fases.

Antes de cambiar nada, crea una copia de seguridad. Después, analiza sin modificar, revisa cada resultado, migra únicamente los valores necesarios y valida todos los servicios afectados. La instalación no está reparada hasta que Home Assistant, ESPHome, la base de datos, MQTT y Zigbee2MQTT continúan funcionando correctamente.

Si quieres que continúe documentando las mejoras encontradas durante esta auditoría, déjamelo en los comentarios del vídeo y suscríbete a Tecnoyfoto para ver más contenido práctico sobre Home Assistant, automatización e inteligencia artificial.

Descuentos en domótica SONOFF