Definición
La gestión de secretos es cómo un proyecto guarda y entrega los datos que dan acceso a algo: claves de API, contraseñas de base de datos, tokens de servicios externos, credenciales de pasarelas de pago.
La regla es única y no admite matices: un secreto nunca se escribe en el código.
Y el motivo va más allá de que alguien lo lea. El código se copia, se comparte con colaboradores, se sube a un repositorio, se envía en un correo, acaba en una copia de seguridad. Cada uno de esos sitios se convierte en una copia del secreto que ya no controlas.
Dónde van entonces
Variables de entorno. Lo mínimo razonable. El secreto vive en la configuración del servidor, fuera del repositorio, y la aplicación lo lee al arrancar.
Fichero de configuración excluido del control de versiones. Un .env o un fichero local, siempre listado en .gitignore, con un .env.example sin valores reales para documentar qué hace falta.
Gestor de secretos. Servicios dedicados que guardan, cifran, versionan y auditan quién accede a qué. Aportan de verdad cuando hay varios entornos y varias personas.
Lo importante no es cuál eliges, sino que el secreto y el código no viajen juntos.
Ejemplo práctico
En una auditoría de un portal de clientes apareció el caso de manual: una clave de API escrita directamente en el código de un fichero del servidor, junto a la lógica que la usaba.
Lo que aprendí de ese hallazgo: lo grave no era la línea, sino su alcance. Esa clave daba acceso al sistema de facturación completo —clientes, documentos, precios— y estaba en un fichero que se había copiado, versionado y compartido durante meses. Arreglarlo no es borrar la línea: es rotar la clave, porque hay que asumir que está comprometida.
Y ahí está la parte incómoda: un secreto filtrado no se desfiltra. Puedes borrar el commit, y el historial sigue teniéndolo; puedes reescribir el historial, y sigue en los clones que otros ya tienen. La única acción que cierra el problema es invalidar el secreto y generar uno nuevo.
El segundo aprendizaje, sobre prevención: la defensa que mejor funciona es la que no depende de acordarse. Tres medidas baratas:
.gitignore desde el primer día, con los ficheros de configuración local ya excluidos antes de que existan.
Un .env.example que documente las variables necesarias sin valores. Evita el «no arranca y nadie sabe qué falta».
Un análisis automático que busque patrones de clave antes de aceptar un cambio. Es lo único que detiene un despiste a las once de la noche.
Y una advertencia sobre el frontend: cualquier cosa que llegue al navegador es pública. Una clave en el JavaScript de la página es visible con dos clics, por mucho que esté minificada. Si un servicio externo requiere una clave secreta, la llamada tiene que salir desde tu servidor, nunca desde el navegador.
Errores comunes
- Claves escritas en el código.
- Subir el
.enval repositorio. - Borrar el commit y creer que ya está, sin rotar la clave.
- Clave secreta en el frontend.
- La misma clave en desarrollo y en producción.
- Claves con todos los permisos cuando bastaría con lectura. Ver principio de mínimo privilegio.
- No rotar nunca. Si nunca has cambiado una clave, no sabes si el sistema sobrevive a hacerlo.
- Compartir secretos por correo o chat, donde quedan indexados para siempre.
Cuándo revisarlo
Al empezar cualquier proyecto, al integrar cualquier servicio externo y en toda auditoría de seguridad.
La comprobación que lleva dos minutos: busca en el repositorio las palabras key, token, password y secret. Si aparece un valor real, tienes trabajo — y empieza por rotarlo, no por borrarlo.
