How to Integrate Duo Security with V0

Start by generating the login form and MFA verification screen in V0. The UI needs two distinct states: a primary credentials form (email/password) and a Duo verification pending screen that appears after credentials are validated. Use V0's chat to describe both states explicitly so it generates a complete flow. The primary login form should collect email and password, with a submit button that calls your primary auth check. Once primary auth succeeds, the UI transitions to the Duo pending screen which displays a message like 'A Duo push has been sent to your phone' along with a loading spinner and a timeout countdown. The Duo screen should also offer alternative methods — 'Enter a passcode instead' — for users who don't have push access. After V0 generates the components, review the state management. You'll want a state variable like `authStep` that moves through 'credentials' → 'duo_pending' → 'authenticated'. V0 typically generates this correctly if you describe the multi-step flow in your prompt. The key thing to check is that the Duo pending screen polls your API route for the verification result rather than expecting an immediate response — Duo push can take 5-30 seconds for the user to respond.

Create a Next.js API route at `app/api/auth/duo/route.ts` that handles the Duo Auth API v2 communication. This route receives the username from the client, constructs a signed request to Duo's `/auth/v2/auth` endpoint, and returns the verification status. Duo's Auth API uses HMAC-SHA1 request signing for authentication — you must include a canonical request string signed with your secret key and base64-encoded as a Basic Auth header. Rather than implementing this from scratch, use the `@duosecurity/duo_web` npm package or the `duo-client-node` package which handles the signing for you. The API route should handle two scenarios: triggering a push (which returns immediately with a `txid` and requires polling) and verifying a passcode (which returns synchronously). For push flows, the route calls `/auth/v2/auth` with `factor: 'push'`, gets back a transaction ID, then polls `/auth/v2/auth_status` until the user approves or denies. To avoid the complexity of server-side polling, have the client poll your `/api/auth/duo/status` endpoint with the `txid`, and have that endpoint check Duo's auth status. This way the 60-second wait happens in a client-controlled polling loop rather than a single long-running serverless function. Always validate that the username passed to this route matches the currently authenticated session — never trust a username from an unauthenticated request.

1// app/api/auth/duo/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3import crypto from 'crypto';
4
5const DUO_IKEY = process.env.DUO_INTEGRATION_KEY!;
6const DUO_SKEY = process.env.DUO_SECRET_KEY!;
7const DUO_HOST = process.env.DUO_API_HOSTNAME!;
8
9function duoSign(method: string, host: string, path: string, params: Record<string, string>): string {
10  const date = new Date().toUTCString();
11  const sortedParams = Object.keys(params).sort().map(k => `${k}=${encodeURIComponent(params[k])}`).join('&');
12  const canon = [date, method.toUpperCase(), host.toLowerCase(), path, sortedParams].join('\n');
13  const sig = crypto.createHmac('sha1', DUO_SKEY).update(canon).digest('hex');
14  const auth = Buffer.from(`${DUO_IKEY}:${sig}`).toString('base64');
15  return `Basic ${auth}`;
16}
17
18export async function POST(request: NextRequest) {
19  try {
20    const { username, factor, passcode } = await request.json();
21    if (!username) return NextResponse.json({ error: 'Username required' }, { status: 400 });
22
23    const path = '/auth/v2/auth';
24    const params: Record<string, string> = {
25      username,
26      factor: factor === 'passcode' ? 'passcode' : 'push',
27      device: 'auto',
28      async: '1',
29    };
30    if (factor === 'passcode' && passcode) params.passcode = passcode;
31
32    const authorization = duoSign('POST', DUO_HOST, path, params);
33    const body = new URLSearchParams(params).toString();
34
35    const res = await fetch(`https://${DUO_HOST}${path}`, {
36      method: 'POST',
37      headers: {
38        Authorization: authorization,
39        'Content-Type': 'application/x-www-form-urlencoded',
40        Date: new Date().toUTCString(),
41      },
42      body,
43    });
44
45    const data = await res.json();
46    if (!res.ok) return NextResponse.json({ error: data.message || 'Duo API error' }, { status: 502 });
47
48    return NextResponse.json({ txid: data.response?.txid, stat: data.stat });
49  } catch (err) {
50    return NextResponse.json({ error: 'Internal server error' }, { status: 500 });
51  }
52}

Create a second API route at `app/api/auth/duo/status/route.ts` that the client polls to check whether the user has approved or denied the Duo push. This endpoint accepts the `txid` returned from the previous step and queries Duo's `/auth/v2/auth_status` endpoint. The status endpoint should return one of three states to the client: `waiting` (user hasn't responded yet), `allow` (user approved — proceed to grant access), or `deny` (user denied — show error and restart flow). Duo's API returns these as `result: 'allow'` or `result: 'deny'` with a `status` of `answered`, or `status: 'pushed'` while still waiting. The client should poll this endpoint every 3 seconds until it receives either `allow` or `deny`, or until the 60-second timeout expires. Keep your server-side logic thin here — just proxy the Duo status check and return a normalized response. The heavy lifting of session creation should happen in a separate endpoint only invoked after receiving `allow`. Security note: associate the `txid` with the user's session on the server side so that a client cannot pass an arbitrary txid from a different user's Duo push. For simple implementations, validate that the txid was issued within the last 60 seconds using a short-lived store like Upstash Redis or an in-memory map (not suitable for multi-instance deploys).

1// app/api/auth/duo/status/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3import crypto from 'crypto';
4
5const DUO_IKEY = process.env.DUO_INTEGRATION_KEY!;
6const DUO_SKEY = process.env.DUO_SECRET_KEY!;
7const DUO_HOST = process.env.DUO_API_HOSTNAME!;
8
9function duoSign(method: string, host: string, path: string, params: Record<string, string>): string {
10  const date = new Date().toUTCString();
11  const sortedParams = Object.keys(params).sort().map(k => `${k}=${encodeURIComponent(params[k])}`).join('&');
12  const canon = [date, method.toUpperCase(), host.toLowerCase(), path, sortedParams].join('\n');
13  const sig = crypto.createHmac('sha1', DUO_SKEY).update(canon).digest('hex');
14  const auth = Buffer.from(`${DUO_IKEY}:${sig}`).toString('base64');
15  return `Basic ${auth}`;
16}
17
18export async function GET(request: NextRequest) {
19  const { searchParams } = new URL(request.url);
20  const txid = searchParams.get('txid');
21  if (!txid) return NextResponse.json({ error: 'txid required' }, { status: 400 });
22
23  const path = '/auth/v2/auth_status';
24  const params = { txid };
25  const authorization = duoSign('GET', DUO_HOST, path, params);
26
27  const res = await fetch(
28    `https://${DUO_HOST}${path}?${new URLSearchParams(params).toString()}`,
29    {
30      headers: {
31        Authorization: authorization,
32        Date: new Date().toUTCString(),
33      },
34    }
35  );
36
37  const data = await res.json();
38  const result = data.response?.result;
39  const status = data.response?.status;
40
41  if (result === 'allow') return NextResponse.json({ status: 'allow' });
42  if (result === 'deny') return NextResponse.json({ status: 'deny' });
43  return NextResponse.json({ status: 'waiting', duoStatus: status });
44}

Navigate to your Vercel project dashboard, click Settings in the top navigation, then select Environment Variables from the left sidebar. You need to add three environment variables that Duo provides when you create an Auth API application in the Duo Admin Panel. Add `DUO_INTEGRATION_KEY` — this is the Integration Key (IKEY) from your Duo Admin Panel application, a string starting with 'DI'. Add `DUO_SECRET_KEY` — the Secret Key (SKEY), a longer string used for request signing. Both should be set as server-only variables (no `NEXT_PUBLIC_` prefix) since they must never appear in browser code. Add `DUO_API_HOSTNAME` — the API Hostname from your Duo application, in the format `api-xxxxxxxx.duosecurity.com`. Set all three variables for the Production environment. If you have a staging environment, create a separate Duo application in the Duo Admin Panel and use its credentials for Preview deployments — this keeps test traffic separate from production analytics and avoids enrolling test users in production. After adding the environment variables, redeploy your application so the new values are picked up by the serverless functions. Changes to server-side environment variables require a redeployment — they are not hot-reloaded.

Connect the V0-generated login component to your API routes. After primary credential validation succeeds, the component should call `/api/auth/duo` to trigger the push, then start a polling interval that calls `/api/auth/duo/status` every 3 seconds until the result is `allow` or `deny`. In the component, use a `useEffect` cleanup function to clear the polling interval when the component unmounts — this prevents memory leaks if the user navigates away while waiting. Set a maximum poll count (60 seconds / 3 second interval = 20 polls) and display a timeout error if the user doesn't respond in time. On receiving `allow`, call your session creation endpoint (or set a cookie/JWT), then redirect to the protected route using Next.js router. On `deny`, clear the polling loop and show an error message: 'Duo authentication was denied. Please try again.' Offer a 'Resend Push' button that calls `/api/auth/duo` again with the same username. For the passcode flow, show a text input when the user clicks 'Enter passcode instead'. Call `/api/auth/duo` with `factor: 'passcode'` and the entered code — this returns synchronously with allow/deny rather than requiring polling, so you can await it directly and skip the polling loop for this path. For complex auth flows with session management, RapidDev's team can help configure the full token issuance and refresh logic after Duo verification.

1// hooks/useDuoVerification.ts
2import { useState, useEffect, useRef } from 'react';
3
4export function useDuoVerification() {
5  const [status, setStatus] = useState<'idle' | 'pending' | 'allow' | 'deny' | 'timeout'>('idle');
6  const [txid, setTxid] = useState<string | null>(null);
7  const intervalRef = useRef<NodeJS.Timeout | null>(null);
8  const pollCountRef = useRef(0);
9
10  const triggerPush = async (username: string) => {
11    setStatus('pending');
12    pollCountRef.current = 0;
13    const res = await fetch('/api/auth/duo', {
14      method: 'POST',
15      headers: { 'Content-Type': 'application/json' },
16      body: JSON.stringify({ username, factor: 'push' }),
17    });
18    const data = await res.json();
19    if (data.txid) setTxid(data.txid);
20  };
21
22  const verifyPasscode = async (username: string, passcode: string) => {
23    const res = await fetch('/api/auth/duo', {
24      method: 'POST',
25      headers: { 'Content-Type': 'application/json' },
26      body: JSON.stringify({ username, factor: 'passcode', passcode }),
27    });
28    const data = await res.json();
29    setStatus(data.status === 'allow' ? 'allow' : 'deny');
30  };
31
32  useEffect(() => {
33    if (!txid || status !== 'pending') return;
34    intervalRef.current = setInterval(async () => {
35      pollCountRef.current += 1;
36      if (pollCountRef.current > 20) {
37        clearInterval(intervalRef.current!);
38        setStatus('timeout');
39        return;
40      }
41      const res = await fetch(`/api/auth/duo/status?txid=${txid}`);
42      const data = await res.json();
43      if (data.status === 'allow' || data.status === 'deny') {
44        clearInterval(intervalRef.current!);
45        setStatus(data.status);
46      }
47    }, 3000);
48    return () => clearInterval(intervalRef.current!);
49  }, [txid, status]);
50
51  return { status, triggerPush, verifyPasscode };
52}