GitLab CI Secrets mit Vault statt nur Protected Variables verwalten

1. Das Grundproblem statischer CI/CD-Variablen

Jede in GitLab als Protected oder Masked markierte Variable ist im Kern ein einzelner Text-Wert, der in der Projekt- oder Gruppenkonfiguration gespeichert und bei jedem passenden Pipeline-Lauf in die Job-Umgebung geladen wird. Solange dieser Wert nicht manuell rotiert wird, bleibt er ueber Monate oder Jahre unveraendert derselbe, was ihn zu einem attraktiven Ziel macht: Wer ihn einmal abgreift, etwa ueber ein kompromittiertes Runner-System oder ein zu freizuegig konfiguriertes Debug-Logging, besitzt ein dauerhaft gueltiges Credential.

Fuer viele Anwendungsfaelle, etwa einen einzelnen API-Schluessel fuer einen unkritischen Drittanbieter-Service, ist dieses Risiko akzeptabel. Sobald es aber um Datenbank-Zugangsdaten, SSH-Deploy-Keys fuer Produktionsserver oder Composer-Auth-Tokens fuer kommerzielle Magento-Erweiterungen geht, wiegt ein dauerhaft gueltiges, statisches Geheimnis deutlich schwerer, weil ein einziger Leak potenziell unbegrenzt lange ausnutzbar bleibt, bis jemand die Rotation manuell anstoesst.

2. Wie GitLab Protected und Masked Variables funktionieren, und wo die Grenzen liegen

Protected Variables stehen ausschliesslich in Pipelines zur Verfuegung, die auf geschuetzten Branches oder Tags laufen, was verhindert, dass ein beliebiger Feature-Branch versehentlich Zugriff auf produktive Secrets erhaelt. Masked Variables wiederum sorgen dafuer, dass der Wert in den Job-Logs durch Sternchen ersetzt wird, sofern der Wert bestimmte Formatregeln erfuellt, etwa keine Zeilenumbrueche enthaelt und eine Mindestlaenge hat.

Beide Mechanismen schuetzen jedoch nur den Transportweg und die Sichtbarkeit, nicht die Lebensdauer des Geheimnisses selbst. Ein einmal in den Projekteinstellungen hinterlegter Datenbank-Benutzername mit Passwort bleibt exakt dieser eine Benutzer mit exakt diesem einen Passwort, unabhaengig davon, wie oft die Pipeline laeuft. Es gibt in der GitLab-Variable selbst keinen Mechanismus fuer Ablaufzeiten, automatische Rotation oder eine Protokollierung, welcher konkrete Pipeline-Lauf das Secret zu welchem Zeitpunkt tatsaechlich genutzt hat.

3. Was HashiCorp Vault grundsaetzlich anders macht

Vault verwaltet Geheimnisse nicht als statische Werte, sondern kann sie ueber sogenannte Secrets Engines dynamisch zur Laufzeit ausstellen. Bei der Database Secrets Engine etwa erzeugt Vault bei jeder Anfrage einen frischen Datenbank-Benutzer mit zufaellig generiertem Passwort und einer festgelegten Lease-Zeit, nach deren Ablauf Vault den Benutzer automatisch wieder aus der Datenbank entfernt, ganz ohne manuelles Eingreifen.

Dadurch veraendert sich das Sicherheitsmodell grundlegend: Selbst wenn ein Angreifer ein ausgestelltes Credential abgreift, ist es nach kurzer Zeit automatisch wertlos. Zusaetzlich fuehrt Vault ein vollstaendiges Audit-Log jeder Ausstellung und jedes Zugriffs, sodass sich im Nachhinein exakt nachvollziehen laesst, welche Pipeline zu welchem Zeitpunkt welches Credential erhalten hat, was fuer Compliance-Anforderungen wie PCI DSS oder ISO 27001 einen erheblichen Unterschied macht.

4. Die native GitLab Vault Integration ueber JWT/OIDC ID Tokens

Seit GitLab 15.7 lassen sich JWT-basierte ID-Tokens direkt in jedem Job erzeugen, die kryptografisch signiert sind und Claims wie Projekt, Branch und Pipeline-ID enthalten. Vault kann ueber seine JWT/OIDC-Auth-Methode so konfiguriert werden, dass es diesen Token verifiziert und darauf basierend, ganz ohne vorab in GitLab hinterlegtes statisches Vault-Token, eine kurzlebige Vault-Sitzung fuer genau diesen Job ausstellt.

Die Zuordnung, welche Vault-Policy ein Job erhaelt, erfolgt dabei ueber Bound Claims in Vault, etwa eine Einschraenkung auf ein bestimmtes GitLab-Projekt oder einen bestimmten geschuetzten Branch. Dadurch bekommt ein Job aus einem Feature-Branch automatisch weniger Rechte als ein Job, der auf dem geschuetzten main-Branch laeuft, ohne dass dafuer irgendwo ein separates, manuell verwaltetes Credential existieren muesste.

deploy_production:
  stage: deploy
  id_tokens:
    VAULT_ID_TOKEN:
      aud: https://vault.mironsoft.internal
  variables:
    VAULT_ADDR: https://vault.mironsoft.internal
  secrets:
    DB_PASSWORD:
      vault:
        engine:
          name: database
          path: database
        path: creds/magento-readwrite
        field: password
      token: $VAULT_ID_TOKEN
  script:
    - bin/magento setup:upgrade --keep-generated
  rules:
    - if: '$CI_COMMIT_BRANCH == "main"'

5. Beispiel: Dynamische Datenbank-Credentials fuer den Deploy-Job

In der klassischen Variante wird ein einziger MySQL-Benutzer mit vollen Rechten dauerhaft als Protected Variable hinterlegt, der von jedem Deploy-Job verwendet wird. Mit der Vault Database Secrets Engine erzeugt Vault dagegen bei jedem Pipeline-Lauf einen frischen Benutzer, dessen Rechte exakt auf die fuer setup:upgrade noetigen Operationen begrenzt sind, und dessen Lease-Zeit typischerweise wenige Stunden betraegt, ausreichend fuer die Laufzeit des Deploy-Jobs, aber nicht laenger.

Der Job selbst muss dafuer kaum angepasst werden: Statt die Zugangsdaten aus einer vordefinierten Umgebungsvariable zu lesen, ruft das secrets:-Keyword in der Job-Definition die Werte direkt von Vault ab und stellt sie als Umgebungsvariable bereit, sodass bin/magento setup:upgrade unveraendert funktioniert, nur eben mit einem Credential, das nach Ablauf der Lease-Zeit automatisch nicht mehr funktioniert.

# Vault Database Secrets Engine fuer MySQL konfigurieren
vault secrets enable database

vault write database/config/magento-mysql \
    plugin_name=mysql-database-plugin \
    connection_url="{{username}}:{{password}}@tcp(db.internal:3306)/" \
    allowed_roles="magento-readwrite" \
    username="vault-admin" \
    password="initial-admin-password"

vault write database/roles/magento-readwrite \
    db_name=magento-mysql \
    creation_statements="CREATE USER '{{name}}'@'%' IDENTIFIED BY '{{password}}'; \
        GRANT SELECT, INSERT, UPDATE, DELETE ON magento.* TO '{{name}}'@'%';" \
    default_ttl="2h" \
    max_ttl="4h"

6. Betrieb: Policies, Auth-Methoden und Rotation im Alltag

Im Vault-Betrieb selbst sollten Policies so granular wie moeglich definiert werden, im Idealfall eine eigene Policy pro Pipeline-Zweck, etwa eine fuer Datenbank-Migrationen und eine separate fuer den Zugriff auf Composer-Auth-Tokens, statt einer einzigen, breiten Policy fuer alle CI-Jobs. Neben der JWT/OIDC-Methode unterstuetzt Vault auch AppRole-Auth, was fuer Runner-Umgebungen sinnvoll sein kann, in denen kein natives GitLab-JWT verfuegbar ist, etwa bei selbstgehosteten Runnern in isolierten Netzwerken.

Fuer statische Secrets, die aus technischen Gruenden nicht dynamisch ausgestellt werden koennen, etwa API-Schluessel externer SaaS-Dienste, bietet Vault ueber die KV-Secrets-Engine trotzdem einen zentralen, versionierten und auditierten Speicherort, der immerhin die Nachvollziehbarkeit erheblich verbessert, auch wenn die Lebensdauer des Wertes selbst weiterhin manuell rotiert werden muss.

7. Aufwand gegen Nutzen: Wann sich Vault fuer ein Magento-Projekt lohnt

Der Betrieb eines eigenen Vault-Clusters, inklusive Unsealing-Strategie, Hochverfuegbarkeit und Backup-Konzept, ist selbst ein nicht triviales Infrastrukturprojekt, das Personalzeit und laufenden Betriebsaufwand bindet. Fuer ein einzelnes kleines Magento-Projekt mit wenigen Entwicklern und ueberschaubarer Secrets-Anzahl steht dieser Aufwand haeufig in keinem guten Verhaeltnis zum Sicherheitsgewinn gegenueber sorgfaeltig verwalteten Protected Variables mit regelmaessiger manueller Rotation.

Sobald jedoch mehrere Teams, mehrere Magento-Instanzen oder strenge Compliance-Vorgaben wie PCI DSS im Spiel sind, kippt die Rechnung deutlich: Ein zentraler Vault-Cluster, der fuer alle Projekte gemeinsam betrieben wird, amortisiert sich schnell, weil die Betriebskosten auf viele Nutzer verteilt werden, waehrend der Sicherheitsgewinn durch kurzlebige Credentials und lueckenloses Audit-Log pro Projekt gleich bleibt.

8. Migrationsstrategie: Schrittweise von Protected Variables zu Vault

Ein sinnvoller Einstieg ist, nicht alle Secrets auf einmal umzustellen, sondern mit dem sensibelsten Wert zu beginnen, in einem Magento-Projekt haeufig die Datenbank-Zugangsdaten fuer den Produktions-Deploy-Job. Dieser eine Job wird auf die Vault-Integration umgestellt, waehrend alle anderen Jobs unveraendert mit Protected Variables weiterlaufen, sodass sich Erfahrung mit der Integration aufbauen laesst, ohne das gesamte Deployment auf einmal zu riskieren.

Erst wenn sich die JWT/OIDC-Integration im Produktivbetrieb bewaehrt hat, folgen schrittweise weitere Secrets wie Composer-Auth-Tokens oder SSH-Deploy-Keys. Die folgende Tabelle fasst zusammen, welche Eigenschaften Protected Variables und Vault jeweils mitbringen und wo die Grenze fuer eine sinnvolle Migration typischerweise verlaeuft.

9. Praxisempfehlung: Vault und Protected Variables gezielt kombinieren statt gegeneinander auszuspielen

In der Praxis ist die Entscheidung selten ein reines Entweder-oder. Fuer ein einzelnes kleines Magento-Projekt ohne dediziertes Betriebsteam bleiben sorgfaeltig gepflegte Protected und Masked Variables mit einer festen, dokumentierten Rotationsfrist, etwa vierteljaehrlich, meist die pragmatischere Wahl, weil sich der Betriebsaufwand eines eigenen Vault-Clusters kaum rechtfertigen laesst. Unkritische Werte wie ein API-Schluessel fuer einen externen Bilddienst muessen dabei nicht zwingend in Vault wandern, nur weil das Werkzeug technisch verfuegbar ist.

Sobald jedoch bereits ein Vault-Cluster fuer andere Projekte im Unternehmen betrieben wird oder mehrere Magento-Instanzen mit getrennten Produktions- und Staging-Datenbanken existieren, lohnt es sich, Vault konsequent als einzige Quelle der Wahrheit fuer alle sensiblen Credentials zu etablieren, statt fallweise zwischen beiden Ansaetzen zu wechseln. Diese Konsistenz erspart dem Team die wiederkehrende Diskussion, welches Secret welchen Schutzmechanismus verdient, und macht Audits gegenueber Kunden oder Zertifizierungsstellen deutlich einfacher.

10. Zusammenfassung

11. FAQ: Vault statt Protected Variables: Das Wichtigste auf einen Blick