External Secrets Integration
Relevant source files
The following files were used as context for generating this wiki page:
External Secrets Integration is an Enterprise Edition (EE) feature in n8n designed to manage sensitive information by delegating storage and retrieval to specialized external providers. Instead of storing credentials locally within the n8n database, this system allows workflows to fetch secrets dynamically from providers like HashiCorp Vault. This integration ensures that sensitive data remains within secure, audited environments while remaining accessible for automated processes.
The system is structured as a modular provider-based architecture, where a core service manages the lifecycle and selection of different secret backends. This allows for centralized credential management and improves security hygiene by utilizing industry-standard secret management tools.
Sources: packages/cli/src/modules/external-secrets.ee/external-secrets.service.ee.ts, packages/cli/src/modules/external-secrets.ee/providers/vault.ts
Core Architecture and Service Logic
The integration is driven by the ExternalSecretsService, which acts as the primary orchestrator for all secret-related operations. It manages the registration of providers, handles the resolution of secret references, and ensures that the correct backend is queried when a secret is requested.
Secret Resolution Flow
When a node or credential requires a secret, the service identifies the appropriate provider based on the configured environment or specific reference. The following diagram illustrates the high-level flow of a secret request.
The diagram shows how the ExternalSecretsService acts as a middle layer between n8n components and external security backends.
Sources: packages/cli/src/modules/external-secrets.ee/external-secrets.service.ee.ts:10-45
Provider Implementation: HashiCorp Vault
The HashiCorp Vault provider is a specific implementation of the external secrets interface. it handles the connection details, authentication, and the actual retrieval of key-value pairs from the Vault server.
Authentication and Connectivity
The Vault provider supports standard connectivity requirements including:
- Server URL: The endpoint where the Vault instance is hosted.
- Authentication: Typically utilizes tokens or role-based access to authenticate the n8n instance.
- Pathing: Secrets are retrieved using specific paths, allowing for granular organization within the Vault KV (Key-Value) store.
Data Retrieval Sequence
The retrieval process involves a synchronous call to the Vault API to fetch the latest version of a secret.
This sequence ensures that secrets are fetched just-in-time and are not persisted longer than necessary in n8n memory.
Sources: packages/cli/src/modules/external-secrets.ee/providers/vault.ts:5-30
Configuration and Management
External secrets are configured via the n8n settings, where administrators can define the global or project-specific providers.
Key Components
| Component | Description |
|---|---|
ExternalSecretsService | The main EE module managing external backend integrations. |
VaultProvider | Specialized class for interacting with HashiCorp Vault. |
SecretReference | A structured string or object pointing to a specific secret (e.g., vault:path/to/secret#key). |
Sources: packages/cli/src/modules/external-secrets.ee/external-secrets.service.ee.ts:50-100, packages/cli/src/modules/external-secrets.ee/providers/vault.ts:1-15
Security Considerations
As an Enterprise feature, the external secrets integration adheres to strict security protocols:
- No Local Persistence: Secrets fetched from external providers are generally not stored in the n8n database, reducing the risk of data leakage via database backups.
- Audit Logging: Interactions with external providers are logged, providing a clear trail of which secrets were accessed and by which workflow.
- Encrypted Transit: All communications between n8n and the external secret providers are performed over encrypted channels (HTTPS).
Sources: AGENTS.md, packages/cli/src/modules/external-secrets.ee/external-secrets.service.ee.ts
Conclusion
The External Secrets Integration provides a robust framework for enterprise-grade secret management. By offloading sensitive data to dedicated providers like Vault, n8n instances can maintain high security standards while ensuring that automated workflows have seamless access to necessary credentials. This architecture supports scalability and centralized security policy enforcement across the entire automation platform.