Symfony Secrets und Vault Management mit HashiCorp Vault

1. Warum .env-Dateien für Secrets in Produktion nicht ausreichen

Die meisten Symfony-Anwendungen starten mit Secrets in einer .env.local-Datei: Datenbankpasswort, API-Schlüssel, JWT-Signaturschlüssel, alles im Klartext auf der Festplatte des Servers oder im Docker-Image. Dieses Muster funktioniert für die lokale Entwicklung gut, wird aber in Produktion schnell zum Problem. Jeder, der Zugriff auf den Server, das Image oder ein Backup bekommt, sieht alle Secrets auf einen Blick, ohne dass jemals ein Zugriff protokolliert würde. Genau hier setzt Vault Management an.

Ein zweites Problem statischer Secrets ist die Rotation. Wird ein Datenbankpasswort kompromittiert, muss es in jeder .env-Datei auf jedem Server manuell ausgetauscht werden, was in größeren Infrastrukturen Stunden dauert und leicht vergessen wird. Vault Management mit HashiCorp Vault löst beide Probleme gleichzeitig: Secrets werden zentral verwaltet, niemals im Klartext auf der Festplatte abgelegt, und können pro Anwendung und pro Zeitfenster automatisch neu ausgestellt werden, ohne dass ein Mensch eingreifen muss.

Der Übergang von statischen zu dynamischen Secrets ist der Kerngedanke hinter modernem Vault Management. Statt eines einzigen, dauerhaft gültigen Datenbankpassworts erhält jede Symfony-Instanz ein eigenes, zeitlich begrenztes Credential, das nach Ablauf automatisch ungültig wird. Selbst wenn ein Angreifer ein solches Credential abfängt, ist der Schaden auf das enge Zeitfenster begrenzt, in dem es gültig war.

2. HashiCorp Vault Grundlagen: Secrets Engines und Policies

HashiCorp Vault organisiert Secrets über sogenannte Secrets Engines, von denen jede eine andere Art von Secret verwaltet. Die KV-Engine (Key-Value) speichert statische Secrets wie API-Schlüssel, die Database-Engine erzeugt dynamische Datenbank-Credentials bei Bedarf, und die PKI-Engine stellt kurzlebige TLS-Zertifikate aus. Für Vault Management in einer Symfony-Anwendung sind meist die KV-Engine für statische Konfigurationswerte und die Database-Engine für Datenbankzugänge relevant.

Der Zugriff auf Secrets wird über Policies gesteuert, geschrieben in HashiCorp Configuration Language. Eine Policy definiert exakt, welche Pfade eine Identität lesen, schreiben oder verwalten darf. Für Symfony bedeutet das: Jede Anwendungsumgebung, etwa Staging und Produktion, bekommt eine eigene Policy, die ausschließlich Lesezugriff auf die für diese Umgebung relevanten Secret-Pfade gewährt. Dieses Least-Privilege-Prinzip ist ein zentraler Baustein von seriösem Vault Management und verhindert, dass ein kompromittierter Staging-Zugang auch Produktions-Secrets offenlegt.

#!/usr/bin/env bash
# vault-setup.sh — enable engines and write a least-privilege policy
set -euo pipefail

# Enable the KV v2 engine for static application secrets
vault secrets enable -path=symfony-app kv-v2

# Enable the database engine for dynamic credentials
vault secrets enable -path=symfony-db database

# Write a policy restricted to this application's own path
cat <<'EOF' | vault policy write symfony-prod-read -
path "symfony-app/data/prod/*" {
  capabilities = ["read"]
}
path "symfony-db/creds/prod-readonly" {
  capabilities = ["read"]
}
EOF

echo "[OK] Vault engines and policy configured for Symfony production"

3. Symfony an Vault anbinden: Secrets zur Laufzeit laden

Für die Anbindung von Symfony an Vault gibt es zwei grundsätzlich verschiedene Strategien. Die erste lädt Secrets direkt beim Anwendungsstart über einen Vault-Client innerhalb von PHP, üblicherweise als eigener Environment-Variable-Prozessor, der Symfonys eingebautes Secrets-System erweitert. Die zweite lässt Secrets von außen, etwa über einen Vault Agent oder Sidecar, als Datei oder Environment-Variable bereitstellen, sodass die Symfony-Anwendung selbst nichts von Vault wissen muss.

Der zweite Ansatz ist für die meisten Teams der pragmatischere Einstieg in Vault Management, weil er die Anwendung von der Vault-Client-Bibliothek entkoppelt und keine PHP-Extension oder zusätzliche Composer-Abhängigkeit für die Vault-API benötigt. Der Vault Agent authentifiziert sich selbstständig gegen Vault, rendert die abgerufenen Secrets in eine Datei nach einem konfigurierten Template und aktualisiert diese Datei automatisch, sobald das zugrunde liegende Secret rotiert. Symfony liest die Werte anschließend ganz normal über Environment-Variablen ein.

<?php
// config/services.yaml equivalent — reading Vault-provided values
// via Symfony's standard environment variable resolution.
// The actual file at APP_SECRETS_FILE is written by the Vault Agent
// and updated automatically whenever the underlying secret rotates.

declare(strict_types=1);

namespace App\Kernel;

use Symfony\Component\DependencyInjection\ContainerBuilder;
use Symfony\Component\Dotenv\Dotenv;

final class VaultSecretsLoader
{
    /**
     * Loads secrets rendered by the Vault Agent into a local file
     * and exposes them as environment variables for Symfony.
     */
    public static function load(string $secretsFile): void
    {
        if (!is_readable($secretsFile)) {
            throw new \RuntimeException(
                sprintf('Vault-rendered secrets file not found: %s', $secretsFile)
            );
        }

        (new Dotenv())->usePutenv(true)->load($secretsFile);
    }
}

4. Dynamische Datenbank Credentials statt statischer Passwörter

Der größte Sprung im Reifegrad von Vault Management gelingt mit dynamischen Datenbank-Credentials. Statt eines einzigen, für alle Symfony-Instanzen gemeinsamen Datenbankbenutzers erzeugt Vault bei jeder Anfrage einen frischen, eindeutigen Benutzer mit einer festgelegten Time-to-Live, etwa eine Stunde. Läuft diese Zeit ab, entfernt Vault den Datenbankbenutzer automatisch wieder, ganz ohne manuellen Cleanup.

Für die Datenbank bedeutet das: Statt eines Passworts, das über Monate oder Jahre unverändert bleibt, existieren jederzeit nur wenige, kurzlebige Zugänge, die eindeutig einer bestimmten Anwendungsinstanz und einem bestimmten Zeitfenster zugeordnet werden können. Im Audit Log lässt sich damit exakt nachvollziehen, welche Instanz zu welchem Zeitpunkt welchen Datenbankzugang genutzt hat, was forensische Analysen nach einem Sicherheitsvorfall erheblich vereinfacht. Diese Rückverfolgbarkeit ist einer der stärksten Vorteile, den Vault Management gegenüber statischen Secrets bietet.

#!/usr/bin/env bash
# fetch-db-credentials.sh — request short-lived database credentials
# valid for one hour, automatically revoked afterward by Vault
set -euo pipefail

RESPONSE=$(vault read -format=json symfony-db/creds/prod-readonly)

DB_USER=$(echo "$RESPONSE" | jq -r '.data.username')
DB_PASS=$(echo "$RESPONSE" | jq -r '.data.password')
LEASE_ID=$(echo "$RESPONSE" | jq -r '.lease_id')
LEASE_TTL=$(echo "$RESPONSE" | jq -r '.lease_duration')

echo "[OK] Issued credential ${DB_USER}, valid for ${LEASE_TTL}s (lease: ${LEASE_ID})"

# Written to the location the Symfony application reads DATABASE_URL from
printf 'DATABASE_URL="mysql://%s:%s@db.internal:3306/shop"\n' "$DB_USER" "$DB_PASS" \
  > /run/secrets/database.env

5. Secret Rotation ohne Anwendungsneustart

Statische Secrets in einer .env-Datei erfordern nach jeder Rotation einen Neustart der Anwendung, damit der neue Wert geladen wird. Bei Vault Management über den Vault Agent entfällt dieser Neustart, weil der Agent die gerenderte Secrets-Datei im laufenden Betrieb aktualisiert und die Anwendung die Datei bei Bedarf, etwa bei der nächsten Datenbankverbindung, erneut einliest, statt den alten Wert dauerhaft im Speicher zu halten.

Für lang laufende PHP-FPM-Worker ist dabei wichtig, dass Datenbankverbindungen nicht über die gesamte Lebensdauer des Worker-Prozesses offen gehalten werden, sondern regelmäßig neu aufgebaut werden, etwa nach jeweils einigen hundert Requests über pm.max_requests. So greift jede neue Verbindung automatisch auf die aktuell gültigen, rotierten Credentials zu, ohne dass eine explizite Rotation-Logik in der Anwendung selbst implementiert werden müsste. Diese Kombination aus Vault Agent und regelmäßig recycelten Worker-Prozessen macht Rotation für Vault Management praktisch unsichtbar für die Anwendung.

6. Secrets in Kubernetes: Vault Agent Injector und Sidecar

In Kubernetes-Umgebungen bietet Vault einen Injector, der Pods automatisch um einen Vault Agent Sidecar-Container erweitert, sobald bestimmte Annotationen im Pod-Manifest vorhanden sind. Der Sidecar authentifiziert sich über die Kubernetes-Service-Account-Identität des Pods gegen Vault, ganz ohne dass ein zusätzliches Token manuell verteilt werden müsste. Für Vault Management in Kubernetes ist dieser Ansatz der praktikabelste Weg, Secrets ohne Umweg über Kubernetes-eigene, standardmäßig unverschlüsselte Secrets-Objekte bereitzustellen.

Die abgerufenen Secrets landen in einem gemeinsamen, In-Memory-Volume, das nur für den eigentlichen Symfony-Container sichtbar ist, nicht für andere Pods im selben Namespace. Das reduziert die Angriffsfläche gegenüber Kubernetes Secrets erheblich, die standardmäßig lediglich Base64-kodiert und ohne native Rotation gespeichert werden. Ein sauber konfigurierter Vault Agent Injector macht Vault Management zu einem nahtlosen Teil des Kubernetes-Deployments, ohne dass Entwickler die Symfony-Anwendung selbst anpassen müssen.

# k8s/deployment.yaml — annotations for the Vault Agent Injector
apiVersion: apps/v1
kind: Deployment
metadata:
  name: symfony-app
spec:
  template:
    metadata:
      annotations:
        vault.hashicorp.com/agent-inject: "true"
        vault.hashicorp.com/role: "symfony-prod"
        vault.hashicorp.com/agent-inject-secret-database.env: "symfony-db/creds/prod-readonly"
        vault.hashicorp.com/agent-inject-template-database.env: |
          {{- with secret "symfony-db/creds/prod-readonly" -}}
          DATABASE_URL="mysql://{{ .Data.username }}:{{ .Data.password }}@db.internal:3306/shop"
          {{- end -}}
    spec:
      serviceAccountName: symfony-app
      containers:
        - name: symfony-app
          image: registry.mironsoft.de/symfony-app:1.4.2

7. Audit Log und Zugriffskontrolle mit Policies

Jede Anfrage an Vault, ob erfolgreich oder abgelehnt, landet im Audit Log, inklusive Identität des Anfragenden, angefragtem Pfad und Zeitstempel. Für Vault Management in regulierten Branchen ist dieses lückenlose Protokoll oft ein Compliance-Muss, weil es exakt beantwortet, wer wann auf welches Secret zugegriffen hat, etwas, das eine .env-Datei prinzipbedingt nicht leisten kann.

Policies sollten so eng wie möglich geschnitten sein: Eine Symfony-Produktionsumgebung braucht ausschließlich Lesezugriff auf ihre eigenen Secret-Pfade, niemals Schreibzugriff und niemals Zugriff auf die Pfade anderer Umgebungen oder Anwendungen. Dieses Least-Privilege-Prinzip begrenzt den Schaden, falls doch einmal ein Token kompromittiert wird, weil selbst ein gestohlenes Token nur die eng begrenzten Rechte der zugehörigen Policy mitbringt, nicht mehr. Ohne dieses konsequente Prinzip verliert Vault Management einen wesentlichen Teil seines Sicherheitsgewinns.

#!/usr/bin/env bash
# enable-audit-log.sh — every request against Vault, allowed or denied,
# is written to this log with identity, path and timestamp
set -euo pipefail

vault audit enable file file_path=/vault/logs/audit.log

# Verify the audit device is active
vault audit list -detailed

echo "[OK] Audit logging enabled — every Vault Management access is now traceable"

8. Lokale Entwicklung versus Produktion: Vault Dev Server

Für die lokale Entwicklung ist der vollständige Aufwand von Vault Management mit Cluster-Setup, Unseal-Prozess und TLS-Zertifikaten meist unverhältnismäßig. HashiCorp Vault bietet dafür einen Dev-Server-Modus, der In-Memory läuft, automatisch entsperrt startet und in Sekunden einsatzbereit ist. Entwickler können damit lokal exakt dieselben Vault-Pfade und Policies nutzen wie in Produktion, ohne die Produktionsinfrastruktur nachzubauen.

Wichtig ist, den Dev-Server niemals versehentlich in Produktion laufen zu lassen, da er Daten ausschließlich im Arbeitsspeicher hält und bei jedem Neustart komplett zurückgesetzt wird. Ein sauberer Vault Management-Workflow trennt deshalb klar zwischen dem Dev-Server für lokale Entwicklung und Continuous Integration einerseits und einem produktiv betriebenen, hochverfügbaren Vault-Cluster mit persistentem Storage-Backend andererseits.

9. Vault Management im Vergleich zu .env und Kubernetes Secrets

Die folgende Tabelle stellt drei verbreitete Ansätze für Secrets in Symfony-Anwendungen gegenüber.

Der Mehraufwand für den Betrieb eines Vault-Clusters zahlt sich für Vault Management in Umgebungen mit echten Compliance-Anforderungen oder hohem Sicherheitsbedarf klar aus. Für kleinere Projekte mit geringerem Risiko kann eine Übergangslösung mit Kubernetes Secrets und externem Secret-Store-Operator ein sinnvoller Zwischenschritt sein, bevor ein vollständiges Vault-Setup aufgebaut wird.

10. Zusammenfassung

Vault Management mit HashiCorp Vault ersetzt statische Passwörter in .env-Dateien durch dynamische, kurzlebige Credentials, die automatisch rotieren und lückenlos protokolliert werden. Der Vault Agent Injector bringt diese Secrets in Kubernetes ohne Codeänderung an der Symfony-Anwendung selbst zum Einsatz, während die Database-Engine Datenbankzugänge erzeugt, die nach Ablauf ihrer Time-to-Live automatisch ungültig werden.

Least-Privilege-Policies begrenzen den Schaden bei einem kompromittierten Token auf einen eng definierten Pfad, und das vollständige Audit Log beantwortet forensische Fragen, die eine .env-Datei prinzipbedingt nicht beantworten kann. Der zusätzliche Betriebsaufwand für Vault Management zahlt sich für jede Anwendung mit echten Sicherheits- oder Compliance-Anforderungen aus, weil Secrets damit erstmals wirklich verwaltet statt nur irgendwo abgelegt werden.

11. FAQ: Symfony Secrets und Vault Management