# The Complete Guide to Vercel Passport **Author:** Ben Sabic --- 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. ## How does Vercel Passport work? 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. ## Plans, roles, and pricing for Vercel Passport Passport is available on [Enterprise plans](https://vercel.com/docs/plans/enterprise), contact your account team for pricing. Within an Enterprise team, anyone with the [owner](https://vercel.com/docs/rbac/access-roles#owner-role) or [member](https://vercel.com/docs/rbac/access-roles#member-role) role can manage Passport alongside your other Deployment Protection settings. ## Before you begin 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. ## How to configure Vercel Passport for a project 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](https://vercel.com/d?to=%2F%5Bteam%5D%2F%5Bproject%5D%2Fsettings%2Fpassport&title=Project+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. ## How to set a team-wide default for Vercel Passport 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](https://vercel.com/d?to=%2F%5Bteam%5D%2F%7E%2Fsettings%2Fpassport&title=Team+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. ## How to assign Vercel Passport to existing projects 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. ## How to access a visitor's identity after authentication 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 `_vercel_``passport` 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 }); }` ## Troubleshooting ### Discovery can't find your OAuth metadata 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. ### Creating an identity provider application returns Not Found 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. ### Visitors can't complete sign-in 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. ## Next steps - Learn how Passport fits alongside other methods in [Deployment Protection](https://vercel.com/docs/deployment-protection). - Compare [methods to protect deployments](https://vercel.com/docs/deployment-protection/methods-to-protect-deployments) to choose the right one for your project. - Review [Vercel Authentication](https://vercel.com/docs/deployment-protection/methods-to-protect-deployments/vercel-authentication) for another way to protect deployments. --- [View full KB sitemap](/kb/sitemap.md)