vercel-labs/protected-vercel-deployments

Geschützte Vercel-Deployments

Verwende die vorhandene Vercel-Identität des Aufrufers und ein kurzlebiges OIDC-Token. Deaktiviere nicht die Deployment Protection, mache das Deployment nicht öffentlich und frage nicht nach einem statischen Bypass-Geheimnis.

Preview im selben Projekt

Ein lokales Entwicklungs-Token für das Zielprojekt kann auf geschützte Preview-Deployments dieses Projekts über die Standard-Selbstzugriffsregel der Trusted Sources zugreifen. Normalerweise ist keine Trusted-Sources-Konfiguration erforderlich.

Bestätige die lokale Identität und die Vercel-CLI-Version:

vc whoami
vc --version

Erfordere Vercel-CLI 53.3.0 oder neuer, bevor vc project token ausgeführt wird. Die Versionen 50.25.0 bis 53.2.x schreiben das Token nach stderr – dann wird bei der Befehlsersetzung nichts erfasst, und die Anmeldedaten können in Logs erscheinen. Wenn die installierte Version älter ist, stoppe und bitte den Benutzer, sie zu aktualisieren. Versuche nicht, das Token von stderr zu erfassen oder wiederherzustellen.

Setze das Zielprojekt und den Bereich explizit. Wenn sie nicht sicher abgeleitet werden können, frage den Benutzer. In einem Verzeichnis, dessen vorhandene .vercel/project.json-Verknüpfung mit dem Ziel verifiziert wurde, ist vc project token ohne Projektnamen ebenfalls gültig. Führe vc link nicht nur aus, um ein OIDC-Token zu erhalten: Aktuelle Vercel-CLI-Versionen ziehen beim Verlinken auch Entwicklungsvariablen in .env.local.

Erstelle eine benannte Browser-Sitzung, erstelle ein Entwicklungs-OIDC-Token mit der Vercel-CLI und injiziere es, ohne es auszugeben oder zu speichern:

export AGENT_BROWSER_SESSION="$(agent-browser session id --scope worktree --prefix vercel-preview)"
export VERCEL_PREVIEW_URL="https://my-app.vercel.app"
export VERCEL_PROJECT="my-app"
export VERCEL_SCOPE="my-team"

(
  TOKEN="$(vc project token "$VERCEL_PROJECT" --scope "$VERCEL_SCOPE")"
  test -n "$TOKEN"
  agent-browser open "$VERCEL_PREVIEW_URL" --headers \
    "{\"x-vercel-trusted-oidc-idp-token\":\"$TOKEN\"}"
)

agent-browser snapshot -i

Setze den normalen Workflow in derselben Sitzung fort. Der Header ist auf den Ziel-Origin beschränkt und gilt für das Dokument, Skripte, Styles, Schriftarten und Seitenanfragen. Wenn die Browser-Sitzung geschlossen oder neu gestartet wird, wiederhole den authentifizierten open-Befehl.

Gib das Token niemals aus, füge es nicht in Quellcode ein und speichere es nicht in einer Umgebungsdatei.

Andere Umgebungen und Aufrufer

Eine Trusted-Sources-Konfiguration ist erforderlich, wenn:

• ein lokales Entwicklungs-Token auf ein geschütztes Production-Deployment zugreifen muss;
• der Aufrufer zu einem anderen Vercel-Projekt oder -Team gehört;
• die Selbstzugriffsregeln des Zielprojekts angepasst wurden; oder
• Vercel TRUSTED_SOURCES_ENVIRONMENT_MISMATCH zurückgibt.

Es gibt keine unterstützte Vercel-CLI oder öffentliche REST-API zum Bearbeiten von Trusted-Sources-Regeln. Ein berechtigter Mensch muss die Einstellungen → Deployment Protection → Trusted Sources des Zielprojekts öffnen und nur die erforderliche Aufrufer-Umgebungszuordnung hinzufügen. Ein lokales Token hat die Umgebung development, daher erfordert der Zugriff auf geschütztes Production die Zuordnung development → production.

Stoppe und übergib die genaue Regel an den Menschen. Verwende keine Browser-Automatisierung, um die Zugriffskontrolle zu ändern, und erweitere keine nicht zusammenhängenden Umgebungszuordnungen. Wiederhole den authentifizierten open-Vorgang, nachdem der Mensch bestätigt hat, dass die Regel gespeichert wurde.

Grenzen menschlicher Eingriffe

Der Pfad „selbes Projekt → Preview“ sollte ohne menschlichen Eingriff auskommen, wenn die Vercel-CLI bereits authentifiziert ist und das Zielprojekt sowie der Bereich bekannt sind. Ein Mensch wird nur benötigt, wenn:

• die Vercel-CLI keine authentifizierte Identität und kein vorhandenes VERCEL_TOKEN hat; interaktives vc login erfordert den Benutzer;
• die installierte Vercel-CLI älter als 53.3.0 ist und vor der Token-Erstellung aktualisiert werden muss;
• das korrekte Zielprojekt oder der Bereich für die Token-Erstellung nicht sicher abgeleitet werden kann;
• eine Trusted-Sources-Regel hinzugefügt oder geändert werden muss; das Dashboard ist die einzige unterstützte Verwaltungsoberfläche, und dies ändert die Zugriffskontrolle;
• der Secure Backend Access mit OIDC Federation im aufrufenden Projekt deaktiviert wurde und unter Einstellungen → Sicherheit wieder aktiviert werden muss; oder
• der statische Geheimnis-Fallback aktiviert oder rotiert werden muss und der Agent eine explizite Autorisierung für diese Zugriffskontrolländerung benötigt. Nach der Genehmigung kann der Agent vc project protection anstelle der Dashboard-Interaktion verwenden.

Der Agent kann jeden Fall diagnostizieren und die genaue erforderliche Aktion benennen und dann fortfahren, nachdem der Benutzer den Abschluss bestätigt hat.

Den richtigen Header verwenden

Sende das von Vercel ausgestellte Token als:

x-vercel-trusted-oidc-idp-token: <VERCEL_OIDC_TOKEN>

Ersetze nicht durch x-vercel-oidc-token. Dieser Header trägt eine Workload-Identität in eine Vercel-Funktion; er authentifiziert keine eingehende Anfrage durch die Deployment Protection.

Fehler diagnostizieren

• Weiterleitung zu vercel.com/login: Die Deployment Protection hat die Anfrage nicht akzeptiert.
• TRUSTED_SOURCES_ENVIRONMENT_MISMATCH: Das Token ist gültig, aber die Aufruferumgebung kann die Zielumgebung nicht erreichen.
• Anwendungs-401 oder 403 nach bestandenem Schutz: Debugge die anwendungseigene Authentifizierung separat.
• Anwendungs-404 auf einer absichtlich nicht vorhandenen Route: Die Anfrage hat die Deployment Protection passiert und die Anwendung erreicht.

Statischer Geheimnis-Fallback

Verwende Protection Bypass for Automation nur, wenn OIDC nicht praktikabel ist oder das Tool den Trusted-Sources-Header nicht senden kann. Das Aktivieren oder Rotieren ändert die Zugriffskontrolle – hole daher zuerst eine explizite Autorisierung ein. Erstelle ein dediziertes Geheimnis, damit es unabhängig rotiert werden kann, halte es in einer Umgebungsvariable und übergib es als Header:

vc project protection enable <project> --protection-bypass \
  --protection-bypass-secret "$VERCEL_AUTOMATION_BYPASS_SECRET"

agent-browser open "$VERCEL_PREVIEW_URL" --headers \
  "{\"x-vercel-protection-bypass\":\"$VERCEL_AUTOMATION_BYPASS_SECRET\",\"x-vercel-set-bypass-cookie\":\"true\"}"

Die Cookie-Direktive erstellt ein wiederverwendbares _vercel_jwt-Cookie. Behandle den gespeicherten Browser-Zustand, der dieses Cookie enthält, als Anmeldedaten.

Sackgassen vermeiden

• Es gibt keinen vercel share-CLI-Befehl. Freigabefähige Links sind für Personen gedacht und nicht der Automatisierungspfad.
• vercel curl ist für HTTP-Anfragen nützlich, kann aber keine Seite rendern und mit ihr interagieren.
• Deployment Protection Exceptions machen die Domain öffentlich. Verwende sie nicht, um lediglich einen Agenten zu entsperren.
• Gib OIDC-Token, Bypass-Geheimnisse, authentifizierte URLs oder gespeicherte Zustände nicht in Logs, Screenshots, Quelldateien oder benutzerseitiger Ausgabe preis.