Saltar al contenido principal

Secretos externos

Disponibilidad de la función​

  • La función de secretos externos está disponible en las modalidades Enterprise Self-Hosted y Enterprise Cloud.
  • n8n admite los siguientes proveedores de secretos: AWS Secrets Manager, Azure Key Vault, GCP Secrets Manager y HashiCorp Vault.
  • A partir de la versión 2.10.0 de n8n, puedes conectar múltiples bóvedas (vaults) por proveedor de secretos. En versiones anteriores, solo se admitía una bóveda por proveedor.
  • n8n no admite HashiCorp Vault Secrets.

Infisical ha quedado obsoleto​

Infisical ha quedado obsoleto. A partir de la versión 2.10.0, ya no podrás conectar nuevas bóvedas de Infisical, aunque las conexiones existentes se mantendrán temporalmente.

Puedes utilizar el almacenamiento de secretos externos para gestionar las credenciales de n8n.

Por defecto, n8n almacena todas las credenciales cifradas en su base de datos y restringe el acceso a ellas. Con la función de secretos externos, puedes almacenar información sensible en una bóveda externa y permitir que n8n la cargue cuando sea necesario. Esto añade una capa adicional de seguridad y te permite gestionar de forma centralizada las credenciales utilizadas en múltiples entornos de n8n.

Conectar n8n a tu almacén de secretos​

Nota: n8n solo admite valores de secretos en formato de texto plano y no admite objetos JSON.

  1. En n8n, ve a Configuración > Secretos externos.

  2. Haz clic en Agregar bóveda de secretos.

  3. Introduce un nombre único para tu bóveda. Este será el primer segmento utilizado al hacer referencia a la bóveda en expresiones de credenciales (por ejemplo, en {{ $secrets.<nombre_bóveda>.<clave> }}).

  4. Selecciona un proveedor de secretos compatible.

  5. Introduce las credenciales de tu proveedor:

    • Azure Key Vault: proporciona el nombre de la bóveda, ID de inquilino (tenant ID), ID de cliente y secreto de cliente. Consulta la documentación de Azure sobre cómo registrar una aplicación en Microsoft Entra ID y crear una entidad de servicio. n8n solo admite valores de secreto de una sola línea.

    • AWS Secrets Manager: proporciona tu ID de clave de acceso, clave de acceso secreta y región. El usuario de IAM debe tener los permisos secretsmanager:ListSecrets, secretsmanager:BatchGetSecretValue y secretsmanager:GetSecretValue.

      Para otorgar a n8n acceso a todos los secretos en AWS Secrets Manager, puedes adjuntar la siguiente política al usuario de IAM. También puedes limitar el alcance para conceder acceso únicamente a secretos específicos.

      Debes permitir secretsmanager:ListSecrets en todos los recursos para que n8n pueda descubrir los secretos disponibles. Sin embargo, los permisos secretsmanager:BatchGetSecretValue y secretsmanager:GetSecretValue sí otorgan acceso a los valores de los secretos, por lo que debes restringirlos a los ARN específicos que deseas compartir con n8n. Asegúrate de usar la región y el ID de cuenta correctos en cada ARN. Puedes encontrar esta información en la página de detalles del secreto en la consola de AWS.

      Para más ejemplos de políticas de IAM, consulta la documentación de AWS.

    • HashiCorp Vault: proporciona la URL de tu instancia de Vault y selecciona tu método de autenticación. Introduce los detalles de autenticación. Opcionalmente, puedes especificar un namespace.

    • Google Cloud Platform (GCP): proporciona el archivo de clave de la cuenta de servicio (en formato JSON) de una cuenta de servicio con al menos los roles Secret Manager Secret Accessor y Secret Manager Secret Viewer. Para más información sobre cuentas de servicio, consulta la documentación de Google sobre cuentas de servicio.

  6. Guarda tu configuración.

  7. Mientras la bóveda esté conectada, podrás hacer referencia a sus secretos en tus credenciales.

Compartir bóvedas​

Por defecto, las bóvedas de secretos son globales: todos los usuarios de la instancia pueden usar credenciales que hagan referencia a secretos de dicha bóveda.

Los administradores de la instancia pueden restringir una bóveda a un proyecto específico. Una vez asignada a un proyecto, solo las credenciales de ese proyecto podrán hacer referencia a sus secretos. Puedes vincular la bóveda a un único proyecto o mantenerla en modo global.

Configurar el ámbito de uso compartido:​

  1. En n8n, ve a Configuración > Secretos externos.
  2. Localiza la bóveda que deseas configurar y selecciona Editar.
  3. En Compartir, elige una de las siguientes opciones:
    • Global: comparte esta bóveda en toda la instancia de n8n, permitiendo que cualquier credencial de la instancia haga referencia a sus secretos.
    • Proyecto: restringe esta bóveda a un proyecto específico. Solo las credenciales de ese proyecto podrán acceder a sus secretos.
  4. Guarda tu configuración.

Usar secretos en credenciales de n8n​

Para usar un secreto almacenado en una credencial de n8n:

  1. Crea una nueva credencial o abre una existente.
  2. En el campo donde deseas usar el secreto:
    1. Pasa el cursor sobre el campo.
    2. Selecciona Expresión.
  3. En el campo, introduce la expresión que hace referencia al nombre del secreto:
{{ $secrets.<nombre_bóveda>.<nombre_secreto> }}

Reemplaza <nombre_bóveda> con el nombre que diste a la bóveda al agregarla, y <nombre_secreto> con el nombre del secreto tal como aparece en tu bóveda.

Usar secretos externos en entornos de n8n​

La función de control de código fuente y entornos de n8n, respaldada por Git, te permite crear distintos entornos de n8n. Sin embargo, esta función no admite el uso de credenciales diferentes entre instancias.

Puedes superar esta limitación conectando cada instancia de n8n a una bóveda o entorno diferente mediante secretos externos. Por ejemplo, si tienes dos instancias —una para desarrollo y otra para producción—, puedes crear en tu proveedor de secretos un proyecto con dos entornos (dev y prod), generar un token para cada uno, y luego:

  • Conectar tu instancia de desarrollo con el token del entorno de desarrollo.
  • Conectar tu instancia de producción con el token del entorno de producción.

De este modo, cada entorno usará sus propias credenciales sin conflictos.

Usar secretos externos en proyectos (RBAC)​

Para usar secretos externos en un proyecto con RBAC (Control de Acceso Basado en Roles), debes incluir al propietario de la instancia o a un administrador de la instancia como miembro del proyecto.

Además, puedes usar la función de bóvedas compartidas para restringir una bóveda a un proyecto específico. Las bóvedas asignadas a un proyecto solo podrán usarse en las credenciales de dicho proyecto.

Solución de problemas​

Usa secretos externos solo en credenciales propiedad del propietario o administrador de la instancia​

Debido a sus privilegios elevados, los propietarios y administradores de la instancia pueden actualizar credenciales pertenecientes a otros usuarios mediante expresiones de secretos. Aunque esto puede parecer funcionar correctamente en la vista previa, los secretos no se resolverán durante la ejecución en producción si la credencial no pertenece al propietario o administrador.

Por lo tanto, usa secretos externos únicamente en credenciales que pertenezcan al propietario o administrador de la instancia. Esto garantiza que los secretos se resuelvan correctamente en entornos de producción.