How to Integrate Okta with V0

Set up the Okta application registration that authorizes your V0 Next.js app to use Okta for authentication. Log into your Okta developer console at your-org.okta.com or developer.okta.com. Navigate to Applications → Applications in the left sidebar, then click 'Create App Integration'. Select 'OIDC - OpenID Connect' as the sign-in method, then select 'Web Application' as the application type (not 'Single-Page App' or 'Native' — Web Application enables the server-side Authorization Code flow with client secret). Click 'Next'. Configure the app settings: give it a name that identifies your V0 project, and add your Vercel callback URL under 'Sign-in redirect URIs'. The callback URL format is https://your-app.vercel.app/api/auth/callback — replace your-app with your actual Vercel subdomain. For local development, also add http://localhost:3000/api/auth/callback. Under 'Sign-out redirect URIs', add https://your-app.vercel.app and http://localhost:3000. Under 'Assignments', decide whether to assign all users (allows any Okta user in your org to log in) or specific groups. For internal tools, 'Allow everyone in your organization to access' is typical. For external-facing apps, create a specific group and assign only that group. After creating the application, Okta shows your Client ID and gives you the option to generate a Client Secret — copy both. Also note your Okta Issuer URL: https://your-org.okta.com/oauth2/default (the '/oauth2/default' is the default authorization server).

Create the Next.js API routes that handle the OIDC authentication flow: the login initiation route (which redirects to Okta), the callback route (which exchanges the authorization code for tokens), and the logout route. These routes work together to manage the user's session. The login route generates a PKCE code challenge, stores a state parameter to prevent CSRF, and redirects to Okta's authorization endpoint. The authorization URL includes your client ID, requested scopes (openid, profile, email), the callback URL, and the code challenge. The callback route receives the authorization code from Okta, verifies the state matches (CSRF protection), exchanges the code for tokens using the token endpoint, validates the ID token's signature and claims, and creates a session cookie with the user's identity information. Store the session in a signed, encrypted cookie using a library like iron-session. The logout route clears the session cookie and redirects to Okta's logout endpoint so the Okta session is also terminated. Without Okta session termination, the user would be automatically re-authenticated on their next login attempt if the Okta session is still active. Use the jose npm package for JWT validation — it handles Okta's ID token signature verification by fetching the JWKS (public keys) from Okta's well-known configuration endpoint.

1// app/api/auth/login/route.ts
2import { NextResponse } from 'next/server';
3import { cookies } from 'next/headers';
4import { generateCodeChallenge, generateState } from '@/lib/pkce';
5
6const OKTA_ISSUER = process.env.OKTA_ISSUER!;
7const OKTA_CLIENT_ID = process.env.OKTA_CLIENT_ID!;
8const APP_BASE_URL = process.env.NEXT_PUBLIC_APP_URL!;
9
10export async function GET() {
11  const state = generateState();
12  const { codeVerifier, codeChallenge } = await generateCodeChallenge();
13
14  const cookieStore = await cookies();
15  cookieStore.set('okta_state', state, { httpOnly: true, secure: true, maxAge: 300 });
16  cookieStore.set('okta_code_verifier', codeVerifier, { httpOnly: true, secure: true, maxAge: 300 });
17
18  const params = new URLSearchParams({
19    client_id: OKTA_CLIENT_ID,
20    response_type: 'code',
21    scope: 'openid profile email groups',
22    redirect_uri: `${APP_BASE_URL}/api/auth/callback`,
23    state,
24    code_challenge: codeChallenge,
25    code_challenge_method: 'S256',
26  });
27
28  return NextResponse.redirect(`${OKTA_ISSUER}/v1/authorize?${params}`);
29}
30
31// lib/pkce.ts
32import { randomBytes, createHash } from 'crypto';
33
34export function generateState(): string {
35  return randomBytes(16).toString('hex');
36}
37
38export async function generateCodeChallenge() {
39  const codeVerifier = randomBytes(32).toString('base64url');
40  const codeChallenge = createHash('sha256')
41    .update(codeVerifier)
42    .digest('base64url');
43  return { codeVerifier, codeChallenge };
44}

The callback route is where authentication completes. After Okta redirects the user back to your app with an authorization code, this route exchanges the code for tokens, validates the ID token, and creates the user's session. To exchange the code for tokens, POST to Okta's token endpoint (OKTA_ISSUER/v1/token) with the authorization code, code verifier, client ID, client secret, and redirect URI. The response includes an id_token (JWT with user identity), access_token, and refresh_token. Validate the ID token using the jose library: fetch Okta's JWKS from OKTA_ISSUER/v1/keys, verify the JWT signature against the public key, and validate the standard claims (iss matches your issuer, aud matches your client ID, exp is in the future). Never skip token validation — without it, a malicious actor could forge authentication responses. After validation, extract the user's sub, email, name, and groups from the ID token claims. Create a session cookie containing these claims plus an expiry time. Use iron-session or next/headers cookies API with encryption to store the session securely. The session cookie should be HttpOnly, Secure (in production), and SameSite=Lax. Store the minimum necessary user information in the cookie — sub (user ID), email, name, and groups. Don't store the full tokens in the cookie due to cookie size limits (4KB maximum).

1// app/api/auth/callback/route.ts
2import { NextResponse } from 'next/server';
3import { cookies } from 'next/headers';
4import { jwtVerify, createRemoteJWKSet } from 'jose';
5
6const OKTA_ISSUER = process.env.OKTA_ISSUER!;
7const OKTA_CLIENT_ID = process.env.OKTA_CLIENT_ID!;
8const OKTA_CLIENT_SECRET = process.env.OKTA_CLIENT_SECRET!;
9const APP_BASE_URL = process.env.NEXT_PUBLIC_APP_URL!;
10
11export async function GET(request: Request) {
12  const { searchParams } = new URL(request.url);
13  const code = searchParams.get('code');
14  const state = searchParams.get('state');
15
16  const cookieStore = await cookies();
17  const storedState = cookieStore.get('okta_state')?.value;
18  const codeVerifier = cookieStore.get('okta_code_verifier')?.value;
19
20  if (!code || state !== storedState || !codeVerifier) {
21    return NextResponse.redirect(`${APP_BASE_URL}/auth/error?error=invalid_state`);
22  }
23
24  // Exchange code for tokens
25  const tokenRes = await fetch(`${OKTA_ISSUER}/v1/token`, {
26    method: 'POST',
27    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
28    body: new URLSearchParams({
29      grant_type: 'authorization_code',
30      client_id: OKTA_CLIENT_ID,
31      client_secret: OKTA_CLIENT_SECRET,
32      code,
33      code_verifier: codeVerifier,
34      redirect_uri: `${APP_BASE_URL}/api/auth/callback`,
35    }),
36  });
37
38  const tokens = await tokenRes.json();
39
40  if (!tokenRes.ok || !tokens.id_token) {
41    return NextResponse.redirect(`${APP_BASE_URL}/auth/error?error=token_exchange_failed`);
42  }
43
44  // Validate ID token
45  const JWKS = createRemoteJWKSet(new URL(`${OKTA_ISSUER}/v1/keys`));
46  const { payload } = await jwtVerify(tokens.id_token, JWKS, {
47    issuer: OKTA_ISSUER,
48    audience: OKTA_CLIENT_ID,
49  });
50
51  const session = {
52    sub: payload.sub,
53    email: payload.email as string,
54    name: payload.name as string,
55    groups: (payload.groups as string[]) || [],
56    expiresAt: Date.now() + 8 * 60 * 60 * 1000, // 8 hours
57  };
58
59  const response = NextResponse.redirect(`${APP_BASE_URL}/dashboard`);
60  response.cookies.set('okta_session', JSON.stringify(session), {
61    httpOnly: true,
62    secure: process.env.NODE_ENV === 'production',
63    sameSite: 'lax',
64    maxAge: 8 * 60 * 60,
65    path: '/',
66  });
67
68  // Clear PKCE cookies
69  response.cookies.delete('okta_state');
70  response.cookies.delete('okta_code_verifier');
71
72  return response;
73}

Create Next.js middleware that protects routes requiring authentication. Middleware runs before every request on matched paths — it checks for the session cookie, validates the session, and either allows the request through or redirects unauthenticated users to the login page. The middleware checks three conditions: the session cookie exists, the session is valid JSON, and the session hasn't expired. If any check fails, redirect to /api/auth/login which initiates the Okta authentication flow. For authenticated users, optionally add user information to request headers so server components can read user identity without another cookie parse. Configure the middleware matcher to protect specific paths rather than all routes — public pages like /marketing, /about, and error pages should not require authentication. Use the matcher configuration to specify which paths need protection. For role-based access control, check the user's groups array in the session against a required group for each route. If a user lacks the required group, redirect to a 403 error page or the dashboard with an insufficient permissions message. Store your Okta credentials in Vercel environment variables: OKTA_ISSUER (your Okta org URL + /oauth2/default), OKTA_CLIENT_ID, OKTA_CLIENT_SECRET, and NEXT_PUBLIC_APP_URL (your Vercel deployment URL for callback and redirect URIs).

1// middleware.ts
2import { NextResponse } from 'next/server';
3import type { NextRequest } from 'next/server';
4
5const PUBLIC_PATHS = ['/auth', '/api/auth', '/login', '/_next', '/favicon.ico'];
6
7export function middleware(request: NextRequest) {
8  const { pathname } = request.nextUrl;
9
10  // Allow public paths
11  if (PUBLIC_PATHS.some((p) => pathname.startsWith(p))) {
12    return NextResponse.next();
13  }
14
15  const sessionCookie = request.cookies.get('okta_session');
16
17  if (!sessionCookie?.value) {
18    const loginUrl = new URL('/api/auth/login', request.url);
19    return NextResponse.redirect(loginUrl);
20  }
21
22  try {
23    const session = JSON.parse(sessionCookie.value);
24
25    if (!session.sub || !session.expiresAt || Date.now() > session.expiresAt) {
26      const response = NextResponse.redirect(new URL('/api/auth/login', request.url));
27      response.cookies.delete('okta_session');
28      return response;
29    }
30
31    // Optionally pass user info to server components via headers
32    const requestHeaders = new Headers(request.headers);
33    requestHeaders.set('x-user-sub', session.sub);
34    requestHeaders.set('x-user-email', session.email || '');
35    requestHeaders.set('x-user-name', session.name || '');
36
37    return NextResponse.next({ request: { headers: requestHeaders } });
38  } catch {
39    const response = NextResponse.redirect(new URL('/api/auth/login', request.url));
40    response.cookies.delete('okta_session');
41    return response;
42  }
43}
44
45export const config = {
46  matcher: [
47    '/((?!_next/static|_next/image|favicon.ico|public).*)',
48  ],
49};