OpenBao-Secret-Backend verwenden

Standardmäßig liest SupaCloud alle Geheimnisse aus Umgebungsvariablen. Durch Setzen von SECRET_BACKEND=openbao wird OpenBao zur maßgeblichen Quelle: Der Server lädt alle Geheimnisse auf Anwendungsebene aus dem einzelnen KV-v2-Pfad supacloud/app, bevor die Validierung der erforderlichen Geheimnisse ausgeführt wird. Umgebungsvariablen bleiben als erlaubte Überschreibung über dem Vault erhalten — sie haben immer Vorrang gegenüber dem vault-gelieferten Wert.

Automatische Erkennung

Wenn SECRET_BACKEND nicht gesetzt ist, erkennt SupaCloud das Backend automatisch: Es wählt openbao, wenn Vault-Authentifizierungsdaten vorhanden sind (VAULT_TOKEN oder das Paar OPENBAO_ROLE_ID + OPENBAO_SECRET_ID), und fällt andernfalls auf env zurück. Eine explizite Einstellung hat immer Vorrang.

Voraussetzungen

• Ein OpenBao- oder HashiCorp-Vault-kompatibler Server mit aktiviertem KV v2 am supacloud-Mount.
• Der SupaCloud-Serverprozess kann die Vault-Adresse (VAULT_ADDR) erreichen.
• Entweder ein statisches Token oder eine AppRole mit Lesezugriff auf supacloud/app und die bestehenden subsystemspezifischen Pfade (supacloud/db, supacloud/messaging, supacloud/management, supacloud/ai, supacloud/registry).

1. Vault-Authentifizierung konfigurieren

1. Statisches Token — eine einzelne Umgebungsvariable setzen:

   VAULT_ADDR=https://vault.example.com
   VAULT_TOKEN=<your-token>

2. AppRole — stattdessen Role-ID und Secret-ID setzen:

   VAULT_ADDR=https://vault.example.com
   OPENBAO_ROLE_ID=<role-id>
   OPENBAO_SECRET_ID=<secret-id>

   Der Server meldet sich beim Start an, dann erneuert eine Hintergrundschleife das Token bei etwa der Hälfte seiner TTL und meldet sich bei einem Erneuerungsfehler automatisch neu an (Issue #385). Die Richtlinie der AppRole sollte auth/token/renew-self erlauben; andernfalls deckt der Neuanmelde-Fallback dies ab.

2. Geheimnisse in supacloud/app schreiben

Alle Geheimnisse auf Anwendungsebene befinden sich in einer einzelnen KV-v2-Zuordnung, deren Schlüssel der jeweilige Name der Umgebungsvariablen ist. Einmalig schreiben; einzelne Schlüssel beim Rotieren eines Geheimnisses aktualisieren:

vault kv put supacloud/app \
  SUPACLOUD_CREDENTIAL_ENCRYPTION_KEY="base64:<32-byte key>" \
  SUPACLOUD_JWT_SECRET="<min-32-chars>"                       \
  OIDC_CLIENT_SECRET="<value>"                               \
  SUPACLOUD_MCP_CONFIRMATION_SECRET="<min-32-chars>"         \
  DISCORD_BOT_TOKEN="<value>"                                \
  STRIPE_SECRET_KEY="<value>"                                \
  STRIPE_WEBHOOK_SECRET="<value>"                            \
  SUPACLOUD_LINEAR_OAUTH_CLIENT_ID="<value>"                 \
  SUPACLOUD_LINEAR_OAUTH_CLIENT_SECRET="<value>"             \
  SUPACLOUD_NOTION_OAUTH_CLIENT_ID="<value>"                 \
  SUPACLOUD_NOTION_OAUTH_CLIENT_SECRET="<value>"

Nur die Schlüssel aufnehmen, die dein Deployment verwendet; unbekannte Schlüssel werden ignoriert.

Verschlüsselungsschlüssel für Zugangsdaten

SUPACLOUD_CREDENTIAL_ENCRYPTION_KEY muss genau 32 Byte groß sein (Base64-kodiert). Wenn du diesen Wert im Vault änderst, wird jeder in der Datenbank gespeicherte scenc:v1:-Geheimtext unleserlich — das Rotieren erfordert eine vollständige Neuverschlüsselung der Spalte und ein erneutes Deployment. Behandle ihn als unveränderlich, sobald Produktionsdaten vorhanden sind.

Der Verschlüsselungsschlüssel für Zugangsdaten wird in einen prozessinternen Halter (secret_store) geladen und nie in std::env geschrieben, sodass er nicht von Agent-Containern oder dem Code-Runner-Subprozess geerbt werden kann.

3. SECRET_BACKEND=openbao setzen

Zur Server-Umgebung (oder .env) hinzufügen:

SECRET_BACKEND=openbao

Der Server wird nun:

1. supacloud/app aus dem Vault laden und jedes AppConfig-Feld füllen, das nach dem Env-Durchlauf noch leer ist.
2. Den prozessinternen Verschlüsselungsschlüssel-Halter und die generische Secret-Map für verzögerte Aufrufstellen (Stripe, SMTP, FinTS, Edition-Lizenz) befüllen.
3. Die Validierung der erforderlichen Geheimnisse ausführen — SUPACLOUD_JWT_SECRET und der Verschlüsselungsschlüssel für Zugangsdaten werden nach der Hydration erneut geprüft (in AppConfig::validate_required), sodass ein vault-gelieferter Wert die Anforderung erfüllt. SUPACLOUD_INITIAL_ADMIN_EMAILS ist ein nicht-geheimer Produktions-Guard, der in from_env vor dem Vault-Lesen validiert wird und nicht über die supacloud/app-Map bereitgestellt werden kann.
4. Beim Start mit einer Fehlermeldung abbrechen, wenn ein erforderliches Geheimnis weder im Vault noch in der Umgebung vorhanden ist.

Einrichtung überprüfen

Im Server-Startprotokoll nach den Loaded … from OpenBao-Einträgen suchen (sowie Cached vault secret: … je Pfad), zum Beispiel:

Loaded app secrets from OpenBao
Cached vault secret: supacloud/app
Cached vault secret: supacloud/db

Fehlt ein erforderliches Geheimnis in beiden Quellen, beendet sich der Prozess mit einer Meldung, die die Variable benennt, z. B.:

SUPACLOUD_CREDENTIAL_ENCRYPTION_KEY must be set in prod so database
credential material is encrypted at rest

Auf reine Umgebungsvariablen zurückschalten

SECRET_BACKEND=env setzen (oder VAULT_TOKEN/OPENBAO_ROLE_ID entfernen, damit die automatische Erkennung auf env zurückfällt). Der Server kontaktiert OpenBao dann nicht mehr und liest alle Geheimnisse direkt aus den Umgebungsvariablen.