Preview with Protected Vercel Environments

Introduction#

When using Uniform Canvas Preview with Vercel projects that have Deployment Protection enabled, you may encounter authentication failures. This occurs because Canvas Preview operates within an iframe, and the Vercel authentication cookie uses SameSite=Lax, preventing it from being included in requests originating from the Canvas Preview iframe. As a result, Canvas Preview receives "not authorized" responses when attempting to access protected Vercel environments.

Problem Details#

• Vercel's Deployment Protection features (Authentication, Password Protection, Trusted IPs) block access to non-authenticated requests
• Canvas Preview operates in an iframe, making cross-origin requests to your Vercel deployment
• Vercel's authentication cookie has SameSite=Lax settings that prevent it from being sent with requests from the Canvas Preview iframe
• This causes Canvas Preview to receive unauthorized responses when trying to access protected environments

Solution#

The solution is to use Vercel's Protection Bypass feature, which allows specific requests to bypass the Deployment Protection mechanisms.

Steps to Implement#

1. Enable Protection Bypass for Automation in Vercel:
   • Navigate to your Vercel project dashboard
   • Go to Settings → Deployment Protection
   • Enable Protection Bypass for Automation
   • Copy the generated secret
2. Modify Your Preview URL in Canvas Preview:
   • Add the following two query string parameters:
     • x-vercel-protection-bypass=<your-vercel-bypass-secret>
     • x-vercel-set-bypass-cookie=samesitenone
   • Format: https://your-vercel-url/api/preview?secret=<your-preview-secret>&x-vercel-protection-bypass=<your-vercel-bypass-secret>&x-vercel-set-bypass-cookie=samesitenone

Verification#

Now verify that Canvas Preview can now successfully access your protected Vercel environments by reloading preview.

Important Notes#

• This solution maintains security while allowing Canvas Preview to work with your protected environments
• The bypass only applies to requests with the correct secret
• Your QA environments remain protected from public access while enabling Uniform Canvas Preview integration

Happy previewing on Vercel!