The Complete Guide to Vercel Passport

Vercel Passport protects your deployments behind your own identity provider, so visitors sign in with Okta, Auth0, or another OpenID Connect provider before they can view a protected deployment. Passport stores the OAuth configuration that connects Vercel to your identity provider and runs the sign-in flow. It's available on Enterprise plans, and you can enable it per project or team-wide.

In this guide, you'll learn how Passport authenticates visitors against your identity provider and how to set it up for a single project or as a team-wide default. You'll also read an authenticated visitor's identity from your server-side code and troubleshoot the most common discovery and sign-in problems.

Vercel Passport redirects visitors to your identity provider when they open a protected deployment, then sets a session cookie once the provider confirms their identity. Passport has two parts that work together:

• Identity provider application: The OAuth or OpenID Connect application that stores the issuer, authorization endpoint, token endpoint, client ID, and client secret for your identity provider.
• Project or team setting: The Passport configuration that points to the identity provider application and controls whether Passport is enabled.

When a visitor opens a protected deployment, Vercel redirects them to your identity provider. After your provider authenticates the visitor, Vercel validates the response and sets a session cookie for that deployment. A visitor with a valid session can view the deployment until the session expires.

Passport is available on Enterprise plans. Within an Enterprise team, anyone with the owner or member role can manage Passport alongside your other Deployment Protection settings.

Passport is billed per project:

Before you set up Passport, make sure you have:

• A Vercel Enterprise team with permission to manage Deployment Protection settings.
• An identity provider that supports OAuth 2.0 or OpenID Connect.
• An identity provider application. You can create one during Passport setup.
• The Vercel redirect URI registered in your identity provider's OAuth application:

https://connect.vercel.com/callback

For Okta, Auth0, and similar providers, configure the application as a confidential client with a client secret.

Enable Passport for a single project from that project's Passport settings. New visits to the project's protected deployment URLs use Passport after you save.

1. Open Passport settings: From your Vercel dashboard, open the Passport settings for your project.
2. Enable Passport: Turn on the Passport toggle.
3. Select or create an identity provider application: Choose an existing application, or create a new one from the setup flow. For an OpenID Connect provider, choose Generic OAuth. If your provider supports discovery, enter its server URL and click Discover. If discovery doesn't work, enter the OAuth endpoints manually. Your provider must allow the redirect URI https://connect.vercel.com/callback.
4. Save your changes: Click Save. New visits to protected deployment URLs use Passport, and existing authenticated sessions stay valid until they expire.

Set a team default so new projects inherit your Passport configuration automatically. Existing projects keep their current settings.

1. Open team settings: In your Vercel dashboard, open your team’s Passport settings.
2. Enable Passport: Turn on the Passport toggle.
3. Select or create an identity provider application: Choose an existing application, or create a new one.
4. Save your changes: Click Save.

Projects created after you save use this Passport configuration. To apply Passport to existing projects, assign it from the team Passport page.

Assign the same identity provider application to multiple existing projects from your team's Passport settings.

1. Select projects: From your team's Passport settings, select the projects you want to update. You can filter the list to show all projects, or only those where Passport is disabled.
2. Start the assignment flow: Begin assigning Passport to the selected projects.
3. Select the identity provider application: Choose the application to apply.
4. Confirm the assignment: Apply Passport to the selected projects.

After Passport authenticates a visitor, read their identity from the x-vercel-oidc-passport-token request header in your server-side code. Vercel forwards a signed Passport session token in this header and also stores it in the vercelpassport cookie.

The token is a Vercel-signed JWT that carries deployment context and Passport identity claims. Use the external_sub claim as the reliable user identifier, since it comes from the external subject your identity provider returns. The sub and scope claims include the owner, connector_id, and external_sub in a stable Vercel format.

Profile fields such as email or name aren't guaranteed. They appear only if your identity provider returns them in the Passport user info response.

Always read x-vercel-oidc-passport-token from server-side code. Vercel strips any client-supplied value from this header and injects the verified token after validating the session, so your server can trust the value it receives.

// Server-side request handler
export function GET(request: Request) {
  const passportToken = request.headers.get('x-vercel-oidc-passport-token');

  if (!passportToken) {
    return new Response('Unauthorized', { status: 401 });
  }

  // passportToken is a Vercel-signed JWT containing Passport identity claims.
  // Decode it server-side to read claims such as external_sub.

  return Response.json({ authenticated: true });
}

Use the issuer URL for your authorization server, not only your identity provider's domain. For Okta's default custom authorization server, use:

https://your_okta_domain.okta.com/oauth2/default

If discovery still fails, enter the authorization endpoint, token endpoint, issuer, JWKS URI, and userinfo endpoint manually.

Confirm that your team has access to Passport. If you're testing a preview deployment of the Vercel dashboard, confirm that the same team has the required feature flags enabled.

Confirm these settings in your identity provider:

• The redirect URI is https://connect.vercel.com/callback.
• The visitor is assigned to the application.
• The application supports the authorization_code grant.
• The scopes include openid.
• The issuer, authorization endpoint, token endpoint, and JWKS URI all belong to the same authorization server.

• Learn how Passport fits alongside other methods in Deployment Protection.
• Compare methods to protect deployments to choose the right one for your project.
• Review Vercel Authentication for another way to protect deployments.