How to Integrate Bolt.new with Duo Security

Log in to the Duo Admin Panel at admin.duosecurity.com with your Duo admin account. In the left sidebar, navigate to Applications → Protect an Application. Search for 'Web SDK' in the integration list and click 'Protect' next to it. This creates a new Duo Web SDK application and shows you the integration credentials. You will see three key values: Client ID (your integration key, also called ikey), Client Secret (your secret key, also called skey), and API Hostname (a unique Duo domain like api-XXXXXXXX.duosecurity.com). Copy all three — you will need them for your application's environment variables. In the application settings, find the 'Redirect URIs' section. For now, add a placeholder like https://your-app.netlify.app/api/auth/duo/callback — you will replace this with your actual deployed URL after deployment. Duo strictly enforces that the redirect_uri in authorization requests matches a registered URI exactly. Under 'Settings' for the application, you can optionally configure the display name (shown on the Duo prompt), allowed groups, and MFA policies. For a basic integration, the defaults are fine. Save the application. Add to your .env file: NEXT_PUBLIC_DUO_CLIENT_ID (safe for client-side code — it's a public client identifier), DUO_CLIENT_SECRET (server-side only), DUO_API_HOSTNAME (the api-XXXXXXXX.duosecurity.com domain), and DUO_REDIRECT_URI (your deployed callback URL).

1# .env.local
2NEXT_PUBLIC_DUO_CLIENT_ID=your_duo_client_id
3DUO_CLIENT_SECRET=your_duo_client_secret
4DUO_API_HOSTNAME=api-xxxxxxxx.duosecurity.com
5DUO_REDIRECT_URI=https://your-app.netlify.app/api/auth/duo/callback

Duo provides an official Node.js SDK (@duosecurity/duo_universal_nodejs) that handles the PKCE challenge generation, state management, and authorization URL construction. Install it via npm in your Bolt project. Create a src/lib/duo.ts helper that initializes the Duo Client with your credentials. The Duo Client constructor takes clientId, clientSecret, apiHost, and redirectUrl. Create a new instance using environment variables — this client is used by both API routes that handle the MFA flow. The auth start route (/api/auth/duo/start) is called after successful password authentication. It calls duo_client.generateAuthUrl() with the current user's username. This function internally generates the PKCE state and code verifier, stores the state in the session (or returns it for you to store), and returns the full authorization URL for redirecting to Duo. Store the PKCE state and the username in the user's session (or a short-lived cookie) before redirecting. You'll need these in the callback to verify the response. The state prevents CSRF attacks — Duo includes it in the callback and you must verify it matches what you sent. IMPORTANT: This redirect cannot be tested in Bolt's WebContainer preview because Duo will redirect back to DUO_REDIRECT_URI, which must be a publicly accessible URL. Build the routes, deploy first, register the deployed URL in Duo, then test the full flow on the deployed site.

1// src/lib/duo.ts
2import { Client } from '@duosecurity/duo_universal_nodejs';
3
4export function createDuoClient(): Client {
5  const clientId = process.env.NEXT_PUBLIC_DUO_CLIENT_ID;
6  const clientSecret = process.env.DUO_CLIENT_SECRET;
7  const apiHost = process.env.DUO_API_HOSTNAME;
8  const redirectUrl = process.env.DUO_REDIRECT_URI;
9
10  if (!clientId || !clientSecret || !apiHost || !redirectUrl) {
11    throw new Error('Duo Security credentials are not fully configured');
12  }
13
14  return new Client({
15    clientId,
16    clientSecret,
17    apiHost,
18    redirectUrl,
19  });
20}
21
22// app/api/auth/duo/start/route.ts
23import { NextRequest, NextResponse } from 'next/server';
24import { createDuoClient } from '@/lib/duo';
25
26export async function POST(request: NextRequest) {
27  const { username } = await request.json();
28  if (!username) {
29    return NextResponse.json({ error: 'username is required' }, { status: 400 });
30  }
31
32  try {
33    const duo = createDuoClient();
34
35    // Health check verifies Duo API is reachable before redirecting
36    await duo.healthCheck();
37
38    const authUrl = await duo.createAuthUrl(username);
39
40    // Store state and username in session for callback verification
41    const response = NextResponse.json({ authUrl });
42    response.cookies.set('duo_pending_user', username, {
43      httpOnly: true,
44      secure: process.env.NODE_ENV === 'production',
45      maxAge: 300, // 5 minutes to complete MFA
46      sameSite: 'lax',
47    });
48
49    return response;
50  } catch (err: any) {
51    return NextResponse.json({ error: err.message }, { status: 500 });
52  }
53}

After the user completes MFA on Duo's Universal Prompt page, Duo redirects back to your DUO_REDIRECT_URI with two URL parameters: duo_code (the authorization code) and state (the state value from the auth URL). Your callback route exchanges these for an ID token using the Duo SDK's exchangeAuthorizationCodeFor2FAResult() function. The callback route retrieves the pending username from the session cookie, calls the Duo SDK to exchange the code, verifies the returned ID token's username matches the pending username (to prevent session fixation attacks), and if verification passes, grants the full authenticated session. If verification fails, redirect back to login with an error. The Duo ID token exchange must happen server-side — it uses your Client Secret. Never expose the client secret or exchange tokens in client-side code. The exchangeAuthorizationCodeFor2FAResult() function handles the PKCE verification, ID token signature validation, and claim verification internally. After successful MFA verification, clear the duo_pending_user cookie and set a full authentication session cookie (or update the existing session to mark MFA as completed). Redirect the user to their intended destination — the original page they were trying to access before being sent to MFA.

1// app/api/auth/duo/callback/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3import { createDuoClient } from '@/lib/duo';
4
5export async function GET(request: NextRequest) {
6  const duoCode = request.nextUrl.searchParams.get('duo_code');
7  const state = request.nextUrl.searchParams.get('state');
8  const pendingUser = request.cookies.get('duo_pending_user')?.value;
9
10  // Validate required parameters
11  if (!duoCode || !state || !pendingUser) {
12    return NextResponse.redirect(new URL('/login?error=mfa_incomplete', request.url));
13  }
14
15  try {
16    const duo = createDuoClient();
17
18    // Exchange code for MFA result token
19    // This validates PKCE, verifies the ID token signature, and checks claims
20    const result = await duo.exchangeAuthorizationCodeFor2FAResult(
21      duoCode,
22      pendingUser // Duo verifies the username in the ID token matches this
23    );
24
25    // Duo SDK throws if verification fails — reaching here means MFA passed
26    const response = NextResponse.redirect(new URL('/dashboard', request.url));
27
28    // Grant full authenticated session
29    response.cookies.set('mfa_verified', 'true', {
30      httpOnly: true,
31      secure: process.env.NODE_ENV === 'production',
32      maxAge: 60 * 60 * 8, // 8 hour session
33      sameSite: 'strict',
34    });
35    response.cookies.set('authenticated_user', pendingUser, {
36      httpOnly: true,
37      secure: process.env.NODE_ENV === 'production',
38      maxAge: 60 * 60 * 8,
39      sameSite: 'strict',
40    });
41
42    // Clear the pending MFA cookie
43    response.cookies.delete('duo_pending_user');
44
45    return response;
46  } catch (err: any) {
47    console.error('Duo MFA verification failed:', err.message);
48    const response = NextResponse.redirect(
49      new URL('/login?error=mfa_failed', request.url)
50    );
51    response.cookies.delete('duo_pending_user');
52    return response;
53  }
54}

With the Duo API routes in place, connect them to your existing login flow. The typical pattern is: (1) user submits email and password, (2) your existing auth route verifies credentials, (3) if credentials are correct AND the user requires MFA, call /api/auth/duo/start to get the Duo auth URL, (4) redirect the user to the Duo URL instead of granting a session immediately, (5) after Duo callback, grant the session. For Supabase Auth users, the typical integration point is in the login page after supabase.auth.signInWithPassword() succeeds. Check if the authenticated user has MFA required (check a custom field like mfa_required in their profile), and if so, initiate the Duo flow before allowing access to protected pages. Deploy your app: publish to Netlify or Bolt Cloud. After getting your deployed URL (e.g., https://your-app.netlify.app), go back to the Duo Admin Panel → your Web SDK application → Settings → Redirect URIs. Replace the placeholder with your exact deployed callback URL: https://your-app.netlify.app/api/auth/duo/callback. The redirect URI must match character-for-character with DUO_REDIRECT_URI in your production environment variables. Set all four environment variables in your deployment platform: NEXT_PUBLIC_DUO_CLIENT_ID, DUO_CLIENT_SECRET, DUO_API_HOSTNAME, and DUO_REDIRECT_URI. Trigger a new deployment after adding them. Test the full login → Duo prompt → callback → dashboard flow on your deployed site.

1// src/middleware.ts — protect routes requiring MFA
2import { NextRequest, NextResponse } from 'next/server';
3
4export function middleware(request: NextRequest) {
5  const mfaVerified = request.cookies.get('mfa_verified')?.value;
6  const authenticatedUser = request.cookies.get('authenticated_user')?.value;
7
8  // Protect /dashboard routes — require completed MFA
9  if (request.nextUrl.pathname.startsWith('/dashboard')) {
10    if (!mfaVerified || !authenticatedUser) {
11      return NextResponse.redirect(new URL('/login', request.url));
12    }
13  }
14
15  return NextResponse.next();
16}
17
18export const config = {
19  matcher: ['/dashboard/:path*'],
20};