Restrict access to deployments with Passport

Passport lets you protect deployments with your own identity provider. Visitors authenticate with your identity provider before they can view a protected deployment.

Use Passport when you want visitors to sign in with an external identity provider, such as Okta, Auth0, or another OpenID Connect compatible provider. Passport stores the OAuth application configuration that talks to your identity provider.

Passport has two parts:

• Identity provider application: The OAuth or OpenID Connect application that stores your identity provider's issuer, authorization endpoint, token endpoint, client ID, and client secret.
• 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 the identity provider authenticates the visitor, Vercel validates the response and sets a session cookie for the protected deployment.

After Passport authenticates a visitor, Vercel stores a signed Passport session token in the _vercel_passport cookie. Vercel also forwards that token to your deployment in the x-vercel-oidc-passport-token request header.

The token is a Vercel-signed JWT. It includes deployment context and Passport identity claims. The reliable user identifier is the external_sub claim, which comes from the external subject returned by your identity provider. 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 are not guaranteed. They only appear if your identity provider returns them in the Passport user info response.

You need:

• 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 it during Passport setup.
• The redirect URI registered in your identity provider's OAuth application:

https://connect.vercel.com/callback

For Okta, Auth0, and similar providers, make sure the application uses a confidential client with a client secret.

Passport is available as an Enterprise feature. Contact your Vercel account team for pricing.

1. Open Passport settings

   From your Vercel dashboard, open Project Passport Settings.

2. Enable Passport

   Use the Passport toggle to enable the feature.

3. Select or create an identity provider application

   Select an existing identity provider application, or create a new one from the Passport setup flow.

   When you create an application, choose Generic OAuth for an OpenID Connect provider. If discovery works, enter your provider's server URL and click Discover. If discovery does not work, enter the OAuth endpoints manually.

   Your provider must allow this redirect URI:

   https://connect.vercel.com/callback

4. Save your changes

   Click Save.

   New visits to protected deployment URLs will use Passport. Existing authenticated sessions can remain valid until they expire.

You can set a team default so new projects inherit Passport settings.

1. From your Vercel dashboard, open Team Passport Settings.
2. Enable Passport.
3. Select or create an identity provider application.
4. Click Save.

Existing projects keep their current Passport settings. Use the project list on the team Passport page to assign Passport to existing projects.

From Team Passport Settings, you can assign the same identity provider application to multiple projects.

1. Select the projects you want to update.
2. Start the assignment flow.
3. Select the identity provider application.
4. Confirm the assignment.

You can filter the project list to show all projects or only projects where Passport is disabled.

Use the issuer URL for the authorization server, not only the domain of your identity provider.

For example, with 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 are testing a preview deployment of the dashboard, confirm that the same team has the required feature flags enabled.

Check the following settings in your identity provider:

• The redirect URI is https://connect.vercel.com/callback.
• The visitor is assigned to the application.
• The app 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.

• Deployment Protection
• Methods to protect deployments
• Vercel Authentication