---
title: Identify users and control access in Next.js with Vercel Passport
description: Use `getIdentity()` to read a visitor’s verified Vercel Passport identity in Next.js, then personalize pages, restrict routes by group, and log actions.
url: "https://vercel.com/kb/guide/vercel-passport-nextjs"
published: 2026-10-14
last_updated: 2026-10-14
authors: Ben Sabic
install_vercel_plugin: npx plugins add vercel/vercel-plugin
---

Vercel Passport signs visitors in with your own identity provider, such as Okta or Microsoft Entra ID, before a request reaches your Next.js app. Once a visitor is through, the `@vercel/passport` SDK gives your server-side code a verified identity with a stable visitor ID. Use it to personalize pages, restrict sensitive routes, and record who did what, without building your own auth flow.

In this guide, you'll learn how to:

- Install `@vercel/passport` and read the visitor identity with `getIdentity()`
  
- Choose a stable identifier for each visitor
  
- Develop locally with a Passport development identity
  
- Apply Passport identity to four common use cases in a project
  

## Before you begin

Make sure you have:

- A Vercel team on the Enterprise plan, which is required for Passport.
  
- A Next.js App Router project deployed to Vercel.
  
- Passport enabled on the project with an identity provider configured. If you haven't set this up yet, follow [Set up Passport with an identity provider](https://vercel.com/docs/passport/set-up-identity-provider).
  

## How Vercel Passport identity reaches your Next.js app

Vercel Passport runs in Vercel's network before your deployment's routes and Next.js proxy functions execute. When a visitor without a session opens a protected deployment, Vercel redirects them to your identity provider. After the provider authenticates them, Vercel validates the response, stores a signed session token in a HttpOnly cookie, and forwards the same token to your deployment in the `x-vercel-oidc-passport-token` request header.

The token is a Vercel-signed JSON Web Token (JWT) that combines standard OpenID Connect claims, deployment context, and identity claims from your provider. Vercel strips any client-supplied value for `x-vercel-oidc-passport-token` and injects its own verified token, so a visitor can't forge an identity by setting the header themselves.

Passport controls who can open your deployment. To control what each visitor can see and do inside it, read their verified identity in your Server Components, Server Actions, and route handlers.

## Install the Vercel Passport SDK

Install `@vercel/passport` in your Next.js project:

**pnpm**

```bash
pnpm i @vercel/passport
```

**npm**

```bash
npm i @vercel/passport
```

**yarn**

```bash
yarn add @vercel/passport
```

**bun**

```bash
bun add @vercel/passport
```

## Read the visitor identity with `getIdentity()`

The `getIdentity()` function from `@vercel/passport` reads Vercel's request context, verifies the Passport token, and returns an identity object. It returns `null` when the request has no Passport identity, for example a request that used [Protection Bypass for Automation](https://vercel.com/docs/deployment-protection/methods-to-bypass-deployment-protection/protection-bypass-automation) without an existing Passport session.

Create a shared helper so every route, Server Action, and Server Component reads identity the same way:

```typescript
import { connection } from 'next/server';
import { getIdentity } from '@vercel/passport';

export type PassportIdentity = NonNullable<
  Awaited<ReturnType<typeof getIdentity>>
>;

// Returns the verified Passport visitor, or null if there isn't one.
export async function getVisitor(): Promise<PassportIdentity | null> {
  // Opt this render into request-time rendering so identity is read per request.
  await connection();

  try {
    return await getIdentity();
  } catch {
    // Treat verification failures as unauthenticated. Don't log the raw token.
    return null;
  }
}

// Stable key for storing a visitor. Combines issuer and subject.
export function visitorKey(identity: PassportIdentity): string {
  return `${identity.payload.iss}|${identity.subject}`;
}
```

`getIdentity()` doesn’t opt the route into dynamic rendering, so `connection()` prevents Next.js from prerendering the page at build time, when no identity exists.

The identity object exposes these fields:

| Field             | Type             | Description                                                                                                                   |
| ----------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `subject`         | string           | Stable Passport principal (the `sub` claim). Use this as the visitor ID. Treat it as opaque and don't parse it.               |
| `externalSubject` | string           | Subject from your identity provider (the `external_sub` claim). Specific to the Connect application and not globally unique.  |
| `email`           | string, optional | Email returned by your identity provider, if any.                                                                             |
| `name`            | string, optional | Display name returned by your identity provider.                                                                              |
| `token`           | string or null   | The raw Passport JWT, or `null` for the local development identity. Use it only to forward identity to a backend you operate. |
| `payload`         | object           | All verified token claims, including `iss`, `aud`, `exp`, and any allowlisted claims such as `groups`.                        |

## Which claim to use as the visitor identifier

Use `identity.subject` (the `sub` claim) as the visitor identifier when your app accepts tokens from one Passport issuer. If your app accepts tokens from more than one Vercel team, store `payload.iss` and `subject` together, which is what the `visitorKey()` helper above does.

Don't use `email`, `name`, `sid`, or `external_sub` alone as a global identifier. These values can change, be absent, or overlap across identity providers and Connect applications. Visitors who sign in through a different Connect application also get a different Passport subject.

## How to develop locally with a Passport development identity

The `next dev` server never receives the real Passport cookie or header, because Passport only runs in Vercel's network. When neither is present, `getIdentity()` returns a development identity and logs a warning the first time it does so:

```plaintext
subject: owner:local:connector:local:principal:test-user
externalSubject: test-user
email: test-user@passport.local
name: Test User
```

The development identity has `verified: false` and no `token`, so treat it as a fixture for your application logic, not as proof the sign-in flow works.

Preview and production deployments never return a development identity. Any process where `VERCEL_ENV` is unset does, which includes a production build you run locally with `next start`.

To match the values your app expects, set them in `.env.local`:

```bash
VERCEL_PASSPORT_DEV_OWNER=acme
VERCEL_PASSPORT_DEV_OWNER_ID=team_your_team_id_here
VERCEL_PASSPORT_DEV_PROJECT=my-project
VERCEL_PASSPORT_DEV_PROJECT_ID=prj_your_project_id_here
VERCEL_PASSPORT_DEV_CONNECTOR_ID=scl_dev
VERCEL_PASSPORT_DEV_EXTERNAL_SUB=user_dev
VERCEL_PASSPORT_DEV_EXTERNAL_ISS=https://idp.example.com
```

To test how your app handles a missing identity, set `VERCEL_PASSPORT_DEV=0` in `.env.local`, which makes `getIdentity()` return `null`. To test the real redirect, session cookie, and verified claims, use a Passport-protected preview deployment.

## Common use cases for Passport identity in Next.js

Once `getVisitor()` returns a verified identity, you can use it anywhere your app runs server-side code. The following use cases build on the same `lib/passport.ts` helper and cover the patterns internal tools need most:

- **Personalize pages**: Render content for the signed-in visitor in Server Components and share their profile with Client Components.
  
- **Restrict an admin area**: Use identity provider groups to limit sensitive pages and Server Actions to specific teams.
  
- **Attribute actions**: Record which visitor created or changed data, using a stable identifier instead of an email address.
  
- **Forward identity**: Pass the verified visitor to another backend you operate and verify it there.
  

Each use case stands on its own, so you can start with the one your app needs.

### Personalize pages with the signed-in visitor

Internal dashboards and tools often need to greet the visitor, show their own records, or prefill forms. Because Passport has already authenticated every request, a Server Component can read the visitor’s identity and render a personalized page.

```tsx
import { getVisitor } from '@/lib/passport';

export default async function HomePage() {
  const visitor = await getVisitor();

  if (!visitor) {
    return <p>We couldn't confirm your identity. Please sign in again.</p>;
  }

  const displayName = visitor.name ?? visitor.email ?? 'there';

  return (
    <main>
      <h1>Welcome, {displayName}</h1>
      <p>You're signed in through your company identity provider.</p>
    </main>
  );
}
```

Profile fields such as `name` and `email` only appear when your identity provider returns them, so always provide a fallback. To load records that belong to the visitor, query your data store with `visitorKey(visitor)` rather than the email address.

You can expose the same identity to client-side code through a route handler, which is useful when a Client Component needs the current user:

```typescript
import { getVisitor } from '@/lib/passport';

export async function GET() {
  const visitor = await getVisitor();

  if (!visitor) {
    return Response.json({ error: 'Unauthorized' }, { status: 401 });
  }

  // Return only the fields the client needs. Never return identity.token.
  return Response.json({
    subject: visitor.subject,
    email: visitor.email ?? null,
    name: visitor.name ?? null,
  });
}
```

### Restrict an admin area by identity provider group

Passport lets everyone assigned to your identity provider application into the deployment, but an admin area or a destructive action usually needs a narrower policy. Group membership from your identity provider is a good fit for this.

#### Request the `groups` claim

Passport requests the standard `openid`, `profile`, and `email` scopes by default.

To include group membership in the Passport token:

1. In the Vercel dashboard, open the Connect application that Passport uses from your project's Passport settings.
   
2. Under **Grant Types**, enable **User Authorization**.
   
3. Add `groups` to the **User Authorization** scopes.
   
4. Under **Forwarded ID Token Claims**, add `groups`. This is the allowlist of extra claims Connect can include in the Passport token.
   
5. Save the application.
   

Your identity provider must also return the claim.

In Okta, for example, you configure a `groups` claim on the authorization server that matches your Connect application's issuer. See [Configure additional identity scopes](https://vercel.com/docs/passport/additional-identity-scopes) for the full Okta walkthrough.

After changing the configuration, start a new Passport session in a private browser window so the new claim appears.

#### Check group membership on the server

Add a helper that reads `groups` defensively, because the claim name and shape depend on your identity provider:

```typescript
import type { PassportIdentity } from '@/lib/passport';

export const ADMIN_GROUP = 'platform-admins';

export function getGroups(identity: PassportIdentity): string[] {
  const claims = identity.payload as Record<string, unknown>;
  const groups = claims.groups;

  if (!Array.isArray(groups)) return [];
  return groups.filter((group): group is string => typeof group === 'string');
}

export function isInGroup(
  identity: PassportIdentity | null,
  group: string,
): boolean {
  if (!identity) return false;
  return getGroups(identity).includes(group);
}
```

Check membership on every page the policy protects. Call `notFound()` when the check fails, so visitors outside the group can’t tell the page exists:

```tsx
import { notFound } from 'next/navigation';
import { getVisitor } from '@/lib/passport';
import { ADMIN_GROUP, isInGroup } from '@/lib/authorization';

export default async function AdminPage() {
  const visitor = await getVisitor();

  if (!isInGroup(visitor, ADMIN_GROUP)) {
    notFound();
  }

  return <h1>Admin settings</h1>;
}
```

Server Actions are reachable as their own endpoints, so a check on the page doesn’t protect them. Repeat the check inside each action and throw when it fails:

```javascript
'use server';

import { getVisitor } from '@/lib/passport';
import { ADMIN_GROUP, isInGroup } from '@/lib/authorization';

export async function rotateApiKey() {
  const visitor = await getVisitor();

  if (!isInGroup(visitor, ADMIN_GROUP)) {
    throw new Error('Forbidden');
  }

  // Perform the privileged operation here.
}
```

The local development identity doesn’t include `groups`, so the admin page returns a 404 while running `next dev`. Test group checks on a Passport-protected preview deployment.

Don't move this check into a Next.js proxy function (previously called Middleware). Proxy functions run after Passport has already made its sign-in decision, and `getIdentity()` can make a network request to the Passport JSON Web Key Set (JWKS), which isn't a good fit for a request proxy.

### Attribute actions to the signed-in visitor

When several people share an internal tool, you usually want to record who created a request or approved a change. Passport already gives you a verified actor for every request, so a Server Action can stamp each write with the visitor's identity.

In the Server Action, read the visitor and attach `visitorKey(visitor)` to the record it writes. Store that key as the actor and treat `email` as a display value, because email addresses can change or be absent:

```typescript
'use server';

import { getVisitor, visitorKey } from '@/lib/passport';

export async function submitRequest(formData: FormData) {
  const visitor = await getVisitor();

  if (!visitor) {
    throw new Error('Unauthorized');
  }

  const title = formData.get('title');
  if (typeof title !== 'string' || title.trim() === '') {
    throw new Error('Title is required');
  }

  const event = {
    action: 'request.created',
    actor: visitorKey(visitor),
    actorEmail: visitor.email ?? null,
    title: title.trim(),
    createdAt: new Date().toISOString(),
  };

  // Structured log line, visible in your project's logs.
  console.log(JSON.stringify(event));

  // Persist `event` to your database, keyed on `event.actor`.
}
```

Then connect the action to a form. The form collects only the request title, because the actor comes from Passport. Never read the actor from form fields or request bodies, because the client controls those values:

```javascript
import { submitRequest } from './actions';

export default function RequestsPage() {
  return (
    <form action={submitRequest}>
      <label htmlFor="title">Request title</label>
      <input id="title" name="title" required />
      <button type="submit">Submit request</button>
    </form>
  );
}
```

Passport also records sign-ins at the platform level. Each successful authentication creates a `passport-access-granted` event in the Activity Log and Audit Logs, so your application log covers what visitors did and Vercel's logs cover when they entered.

### Forward Passport identity to another backend

Your Next.js app might call a separate API, such as a reporting service or another Vercel project, that also needs to know who the visitor is. Forward the Passport token as a bearer token and verify it at the receiving service with `verifyIdentity()`.

#### Forward the token from the Next.js app

```typescript
import { getVisitor } from '@/lib/passport';

export async function POST() {
  const visitor = await getVisitor();

  if (!visitor?.token) {
    return Response.json({ error: 'Unauthorized' }, { status: 401 });
  }

  const response = await fetch('https://reports.example.com/api/reports', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${visitor.token}`,
    },
  });

  return new Response(response.body, { status: response.status });
}
```

The development identity has no `token`, so this route returns `401` under `next dev`. Test forwarding against a Passport-protected preview deployment.

#### Verify the token in the receiving backend

Install `@vercel/passport` in the receiving service. The `verifyIdentity()` function is available in `@vercel/passport` 0.1.3 and later.

`verifyIdentity()` reads the bearer token from the request, checks its signature, and confirms it came from the expected source project and environment:

```typescript
import { verifyIdentity } from '@vercel/passport';

// IDs of the Passport-protected deployment that minted the token,
// not the project receiving it.
const ownerId = process.env.PASSPORT_SOURCE_OWNER_ID!;
const projectId = process.env.PASSPORT_SOURCE_PROJECT_ID!;
const environment = process.env.PASSPORT_SOURCE_ENVIRONMENT ?? 'production';

export async function POST(request: Request) {
  try {
    const identity = await verifyIdentity(request, {
      ownerId,
      projectId,
      environment,
    });

    // Use identity.subject (with identity.payload.iss) as the visitor ID.
    return Response.json({ requestedBy: identity.subject });
  } catch {
    return Response.json({ error: 'Unauthorized' }, { status: 401 });
  }
}
```

Keep these rules in mind when forwarding identity:

- **Use HTTPS to backends you operate**: The Passport token authenticates the visitor to your own services. It isn't an access token for your identity provider or for third-party APIs. Use Vercel Connect when a backend needs credentials for another service.
  
- **Validate against the source deployment**: Pass the owner ID, project ID, and environment of the app that minted the token. Don't substitute the receiving project's values.
  
- **Verify outside JavaScript with the JWKS**: Non-JavaScript services can verify the token as a standard JWT against https://passport.vercel.com/.well-known/jwks.json, checking `iss`, `aud`, `exp`, `nbf`, `typ` (which must equal `passport`), `project_id`, and `environment`.
  
- **Account for Deployment Protection on the receiver**: If the receiving backend is itself a protected Vercel deployment, the server-to-server request has no Passport session and needs a [Protection Bypass for Automation](https://vercel.com/docs/deployment-protection/methods-to-bypass-deployment-protection/protection-bypass-automation) secret.
  

## Troubleshooting

### `getIdentity()` returns `null` on a deployment

Confirm that the deployment is Passport-protected and that `getIdentity()` runs in server-side code, such as a Server Component, Server Action, or route handler. Requests that use Protection Bypass for Automation without an existing Passport session legitimately have no identity. If your runtime doesn't expose Vercel's request context, pass the request or its headers to `getIdentity()` explicitly.

`getIdentity()` also checks the token’s `project_id` and `environment` claims against the `VERCEL_PROJECT_ID` and `VERCEL_TARGET_ENV` (or `VERCEL_ENV`) System Environment Variables. If those variables aren’t exposed to your functions, verification throws and `getVisitor()` returns `null`. Confirm that **Enable access to System Environment Variables** is checked in your project’s [environment variable settings.](https://vercel.com/d?to=%2F%5Bteam%5D%2F%5Bproject%5D%2Fsettings%2Fenvironment-variables%3Fenv%3Dsystem)

### The `groups`, `email`, or `name` claim is missing

These claims are optional. Confirm that your identity provider returns the claim, that the Connect application requests the scope and lists the claim under **Forwarded ID Token Claims**, and then start a new Passport session. Existing sessions keep the claims from when they were issued.

### Webhooks or cron jobs can't reach a Passport-protected route

Passport redirects any request without a session to your identity provider, including webhooks and Cron Jobs. The original request must include a Protection Bypass for Automation secret. Don't try to make a path public from a Next.js proxy function, because Passport has already run by then.

### Token verification fails

Treat the request as unauthenticated and confirm your code reads the Vercel-injected `x-vercel-oidc-passport-token` header, not a client-supplied value. For forwarded tokens, check that the server can reach the Passport JWKS and that its clock is accurate. Don't log the raw token while debugging.

The `@vercel/passport` SDK fetches signing keys from https://oidc.vercel.com/.well-known/jwks, which serves the same key set as https://passport.vercel.com/.well-known/jwks.json, so allow both hosts if your backend restricts outbound traffic.

## Next steps

- Review every claim in the [Passport token claims reference](https://vercel.com/docs/passport/token-claims).
  
- Read the full [Read Passport identity in your application](https://vercel.com/docs/passport/read-identity) docs for SDK options.
  
- Set up additional claims with [Configure additional identity scopes](https://vercel.com/docs/passport/additional-identity-scopes).
  
- Learn more about [forwarding identity](https://vercel.com/docs/passport/forward-identity) and [verifying forwarded tokens](https://vercel.com/docs/passport/verify-identity).
  
- Compare Passport with other [methods to protect deployments](https://vercel.com/docs/deployment-protection/methods-to-protect-deployments).
  

## Frequently asked questions

### How do I get the current user in Next.js with Vercel Passport?

Install `@vercel/passport` and call `getIdentity()` from a Server Component, Server Action, or route handler. It returns a verified identity object with `subject`, `externalSubject`, `email`, `name`, and the full claim `payload`, or `null` when the request has no Passport identity.

### Should I use `sub` or `external_sub` to identify a Vercel Passport visitor?

Use `sub` (exposed as `identity.subject`) as the stable visitor identifier, and store it together with the `iss` claim if your app accepts tokens from more than one Vercel team. The `external_sub` claim comes from your identity provider, is specific to the Connect application, and isn't globally unique.

### Can I use Vercel Passport identity in a Client Component?

Not directly. Read identity in server-side code, then pass only the fields you need to Client Components as props or through a route handler such as `/api/me`. Never send the raw Passport token to the browser.

### How do I test Vercel Passport locally?

A local `next dev` server receives a development identity from `getIdentity()`, which you can customize with `VERCEL_PASSPORT_DEV_*` environment variables or disable with `VERCEL_PASSPORT_DEV=0`. To test the real identity provider sign-in and verified claims, use a Passport-protected preview deployment.

### Can I use a Next.js proxy function to authorize Vercel Passport visitors?

No. Passport runs before Next.js proxy functions, so a proxy function can't make a protected path public, and `getIdentity()` can make a network request that isn't suited to a request proxy. Put authorization checks in Server Components, Server Actions, and route handlers instead.

## More Next.js guides

- [Next.js on Vercel vs Webflow Cloud](/kb/guide/next-js-on-vercel-vs-webflow-cloud): Compare running Next.js on Vercel Functions with Fluid compute against Webflow Cloud on Cloudflare Workers. Learn how Next.js feature support, runtimes, storage, pricing, and developer experience differ so you can choose the right platform.
- [Migrate a Next.js app from Webflow Cloud to Vercel](/kb/guide/migrate-a-next-js-app-from-webflow-cloud-to-vercel): Move your Next.js app from Webflow Cloud to Vercel: remove the OpenNext Cloudflare adapter, drop the base path, map storage bindings to Vercel Blob, Redis, and Postgres, and deploy with Git or the vercel CLI.
- [Vercel vs Webflow Cloud](/kb/guide/vercel-vs-webflow-cloud): Compare Vercel and Webflow Cloud for deploying Next.js and Astro apps, including runtime, framework support, storage, pricing, and where your code runs.