vercel-labs/protected-vercel-deployments

Déploiements Vercel protégés

Utilisez l'identité Vercel existante de l'appelant et un jeton OIDC de courte durée. Ne désactivez pas la Protection de Déploiement, ne rendez pas le déploiement public et ne demandez pas un secret de contournement statique au préalable.

Prévisualisation du même projet

Un jeton de développement local pour le projet cible peut accéder aux déploiements de prévisualisation protégés de ce projet via la règle d'auto-accès par défaut Trusted Sources. Aucune configuration Trusted Sources n'est normalement requise.

Confirmez l'identité locale et la version de Vercel CLI :

vc whoami
vc --version

Exigez Vercel CLI 53.3.0 ou plus récent avant d'exécuter vc project token. Les versions 50.25.0 à 53.2.x écrivent le jeton sur stderr, donc la substitution de commande ne capture rien et l'identifiant peut apparaître dans les logs. Si la version installée est plus ancienne, arrêtez-vous et demandez à l'utilisateur de la mettre à niveau. N'essayez pas de capturer ou de récupérer le jeton depuis stderr.

Définissez explicitement le projet cible et le scope. S'ils ne peuvent pas être déduits de manière fiable, demandez à l'utilisateur. Dans un répertoire dont le lien existant .vercel/project.json a été vérifié par rapport à la cible, vc project token sans nom de projet est également valide. N'exécutez pas vc link uniquement pour obtenir un jeton OIDC : les versions actuelles de Vercel CLI tirent également les variables de développement dans .env.local lors de la liaison.

Créez une session de navigateur nommée, générez un jeton OIDC de développement avec Vercel CLI, puis injectez-le sans l'imprimer ni le persister :

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

Continuez le flux de travail normal dans cette même session. L'en-tête est limité à l'origine cible et s'applique au document, aux scripts, aux styles, aux polices et aux requêtes dans la page. Si la session du navigateur est fermée ou redémarrée, répétez la commande open authentifiée.

N'imprimez jamais le jeton, ne le collez pas dans le code source et ne l'enregistrez pas dans un fichier d'environnement.

Autres environnements et appelants

La configuration Trusted Sources est nécessaire lorsque :

• un jeton de développement local doit atteindre un déploiement de production protégé ;
• l'appelant appartient à un autre projet ou équipe Vercel ;
• les règles d'auto-accès du projet cible ont été personnalisées ; ou
• Vercel retourne TRUSTED_SOURCES_ENVIRONMENT_MISMATCH.

Il n'existe pas de CLI Vercel ou d'API REST publique prise en charge pour modifier les règles Trusted Sources. Un humain autorisé doit ouvrir Paramètres → Protection de Déploiement → Trusted Sources du projet cible et ajouter uniquement le mappage de l'appelant et de l'environnement requis. Un jeton local a l'environnement development, donc l'accès à la Production protégée nécessite le mappage development vers production.

Arrêtez-vous et transmettez la règle exacte à l'humain. N'utilisez pas l'automatisation du navigateur pour modifier le contrôle d'accès et n'élargissez pas les mappages d'environnement non liés. Réessayez la commande open authentifiée après que l'humain a confirmé que la règle est enregistrée.

Limites de l'intervention humaine

Le chemin de développement du même projet vers la prévisualisation doit s'exécuter sans intervention humaine lorsque la CLI Vercel est déjà authentifiée et que le projet et le scope cibles sont connus. Un humain n'est nécessaire que lorsque :

• la CLI Vercel n'a pas d'identité authentifiée et aucun VERCEL_TOKEN existant ; vc login interactif nécessite l'utilisateur ;
• la CLI Vercel installée est antérieure à 53.3.0 et doit être mise à niveau avant la création du jeton ;
• le projet ou le scope cible correct ne peut pas être déduit de manière fiable pour la création du jeton ;
• une règle Trusted Sources doit être ajoutée ou modifiée ; le tableau de bord est la seule surface de gestion prise en charge, et cela modifie le contrôle d'accès ;
• l'Accès Backend Sécurisé avec Fédération OIDC a été désactivé sur le projet appelant et doit être réactivé dans Paramètres → Sécurité ; ou
• le recours au secret statique doit être activé ou renouvelé et l'agent a besoin d'une autorisation explicite pour ce changement de contrôle d'accès. Après approbation, l'agent peut utiliser vc project protection au lieu de nécessiter une interaction avec le tableau de bord.

L'agent peut diagnostiquer chaque cas et indiquer l'action exacte requise, puis continuer après que l'utilisateur a confirmé la réalisation.

Utilisez le bon en-tête

Envoyez le jeton délivré par Vercel sous la forme :

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

Ne remplacez pas par x-vercel-oidc-token. Cet en-tête transporte l'identité de la charge de travail dans une Fonction Vercel ; il n'authentifie pas une requête entrante via la Protection de Déploiement.

Diagnostiquer les échecs

• Redirection vers vercel.com/login : la Protection de Déploiement n'a pas accepté la requête.
• TRUSTED_SOURCES_ENVIRONMENT_MISMATCH : le jeton est valide, mais son environnement appelant ne peut pas atteindre l'environnement cible.
• 401 ou 403 de l'application après le passage de la protection : déboguez l'authentification propre à l'application séparément.
• 404 de l'application sur une route délibérément manquante : la requête a passé la Protection de Déploiement et a atteint l'application.

Recours au secret statique

Utilisez Protection Bypass for Automation uniquement lorsque l'OIDC n'est pas viable ou que l'outil ne peut pas envoyer l'en-tête Trusted Sources. Activer ou renouveler cela modifie le contrôle d'accès, alors obtenez d'abord une autorisation explicite. Créez un secret dédié afin qu'il puisse être renouvelé indépendamment, conservez-le dans une variable d'environnement et transmettez-le en tant qu'en-tête :

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\"}"

La directive de cookie crée un cookie _vercel_jwt réutilisable. Traitez l'état enregistré du navigateur contenant ce cookie comme un identifiant.

Éviter les impasses

• Il n'existe pas de commande CLI vercel share. Les Liens Partageables sont destinés aux personnes et ne constituent pas une voie d'automatisation.
• vercel curl est utile pour les requêtes HTTP, mais il ne peut pas afficher et interagir avec une page.
• Les Exceptions de Protection de Déploiement rendent le domaine public. Ne les utilisez pas simplement pour débloquer un agent.
• N'exposez pas les jetons OIDC, les secrets de contournement, les URL authentifiées ou l'état enregistré dans les logs, les captures d'écran, les fichiers source ou les résultats visibles par l'utilisateur.