Vercel’s deployment protection is a powerful feature that lets you restrict access to your preview and production deployments, ensuring only authorized users can see your latest work. It’s not just about hiding things; it’s about controlled visibility, which is crucial for internal tools, client demos, or sensitive projects.
Let’s see it in action. Imagine you’ve got a staging environment for a client project that you’re actively developing. You want to show them progress without exposing it to the public internet.
Here’s a vercel.json snippet that sets up password protection for a specific deployment path, say /staging:
{
"routes": [
{
"src": "/staging(/.*)?",
"dest": "/staging/$1",
"methods": ["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS"],
"headers": {
"x-middleware-protected": "true"
}
}
],
"github": {
"enabled": true
}
}
When a user tries to access /staging on a protected deployment, Vercel intercepts the request and presents a login prompt. If password protection is enabled, they’ll see a simple username and password field. If SSO is configured, they’ll be redirected to your chosen identity provider.
The magic here is the x-middleware-protected: "true" header. Vercel’s edge network reads this and knows to apply the configured protection rules before routing the request to your application code. It’s a layer of security enforced at the edge, meaning your application doesn’t even see the unauthorized request.
You can configure this protection in the Vercel dashboard under your project’s "Settings" -> "Access Control". You can choose between "Password Protection" or "SSO".
For password protection, you simply define a username and password. These are stored securely by Vercel.
{
"version": 2,
"public": true,
"builds": [
{
"src": "next.config.js",
"use": "@vercel/next"
}
],
"routes": [
{
"src": "/(.*)",
"dest": "/index.html",
"headers": {
"x-middleware-protected": "true",
"x-password-protected": "true",
"x-password": "your-secret-password",
"x-username": "your-username"
}
}
]
}
This vercel.json example shows how you could pass credentials directly, but Vercel’s UI is the recommended way to manage them to avoid committing secrets to your repository. The dashboard allows you to set a username and password, and Vercel injects the necessary headers internally.
For SSO, you’ll need to integrate with an identity provider like GitHub, GitLab, Google, or Okta. Vercel acts as a service provider (SP), and your IdP is the identity provider (IdP). The flow typically involves Vercel redirecting the user to your IdP for authentication, and then receiving a SAML assertion back to grant access.
The core idea is that Vercel handles the authentication handshake at the edge. If authentication succeeds, Vercel forwards the request to your deployment with a special header, often x-user-id or similar, which your application can optionally use to identify the authenticated user.
Here’s a crucial detail that trips many people up: when you use SSO with Vercel, Vercel doesn’t directly store your user credentials. Instead, it relies on your chosen Identity Provider (IdP). When a user accesses a protected deployment, Vercel redirects them to your IdP (e.g., your company’s Google Workspace or Okta login page). After successful authentication with the IdP, the IdP sends a signed assertion back to Vercel confirming the user’s identity. Vercel then trusts this assertion and grants access to the deployment. This means your IdP is the source of truth for user authentication, and Vercel is simply verifying that truth.
The next step after securing your deployments is often implementing fine-grained access control within your application based on the authenticated user’s identity.