"use strict"; const {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0]; const {useMDXComponents: _provideComponents} = arguments[0]; const headings = [{ "data": { "id": "prerequisites", "hProperties": { "id": "prerequisites" } }, "depth": 2, "value": "Prerequisites" }, { "data": { "id": "implementing-session-storage-with-vercels-kv", "hProperties": { "id": "implementing-session-storage-with-vercels-kv" } }, "depth": 2, "value": "Implementing session storage with Vercel’s KV" }, { "data": { "id": "setting-up-kv-storage", "hProperties": { "id": "setting-up-kv-storage" } }, "depth": 3, "value": "Setting up KV storage" }, { "data": { "id": "implement-session-management-functions", "hProperties": { "id": "implement-session-management-functions" } }, "depth": 3, "value": "Implement session management functions" }, { "data": { "id": "implementing-user-database-with-vercels-kv", "hProperties": { "id": "implementing-user-database-with-vercels-kv" } }, "depth": 2, "value": "Implementing user database with Vercel’s KV" }, { "data": { "id": "preparing-webauthn-functions", "hProperties": { "id": "preparing-webauthn-functions" } }, "depth": 2, "value": "Preparing WebAuthn functions" }, { "data": { "id": "build-the-web-page", "hProperties": { "id": "build-the-web-page" } }, "depth": 2, "value": "Build the web page" }, { "data": { "id": "conclusion", "hProperties": { "id": "conclusion" } }, "depth": 2, "value": "Conclusion" }, { "data": { "id": "key-considerations-for-production-deployment", "hProperties": { "id": "key-considerations-for-production-deployment" } }, "depth": 3, "value": "Key Considerations for Production Deployment" }]; const readingTime = { "minutes": 5, "words": 1584, "text": "5 min read" }; const frontmatter = undefined; function _createMdxContent(props) { const _components = { a: "a", code: "code", h2: "h2", h3: "h3", img: "img", li: "li", ol: "ol", p: "p", pre: "pre", span: "span", strong: "strong", ul: "ul", ..._provideComponents(), ...props.components }, {LogtoCloudButton} = _components; if (!LogtoCloudButton) _missingMdxReference("LogtoCloudButton", true); return _jsxs(_Fragment, { children: [_jsxs(_components.p, { children: ["Welcome back to our WebAuthn series. In our previous articles, we've covered ", _jsx(_components.a, { href: "https://blog.logto.io/webauthn-base-knowledge/", children: "the basics of WebAuthn" }), ", and a ", _jsx(_components.a, { href: "https://blog.logto.io/web-authn-and-passkey-101/", children: "101 guide" }), ". If you're just joining us, feel free to check out these foundational pieces to get up to speed."] }), "\n", _jsx(_components.p, { children: "Today, we're rolling up our sleeves to put theory into practice. We'll be harnessing the power of Next.js with the new feature “Server Actions”. Our goal? To implement WebAuthn in a Next.js application, and get ourselves ready for WebAuthn." }), "\n", _jsxs(_components.p, { children: ["Before we dive into the coding sea, here's a glimpse of what awaits you at the journey's end - a fully functional ", _jsx(_components.a, { href: "https://nextjs-webauthn-alpha.vercel.app/", children: "demo website" }), ". Explore it to see WebAuthn in action and to get a taste of what you'll be building. In this demo website, you can register new users and login with the passkeys just registered."] }), "\n", _jsx(_components.p, { children: _jsx(_components.img, { src: "https://uploads.strapi.logto.io/1/preview_fe67ff2888.webp", alt: "Preview" }) }), "\n", _jsxs(_components.p, { children: ["And for those who prefer a map in hand, we've got you covered! All the code we'll be discussing is available in a public ", _jsx(_components.a, { href: "https://github.com/wangsijie/nextjs-webauthn", children: "GitHub repository" }), " . This repository is your companion guide, offering the full source code of our implementation."] }), "\n", _jsx(_components.p, { children: "Ready to embark on this exciting adventure? Let's get started!" }), "\n", _jsxs(_components.h2, { id: "prerequisites", children: ["Prerequisites", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#prerequisites", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsx(_components.p, { children: "Before we begin, let's make sure we have everything we need:" }), "\n", _jsxs(_components.ol, { children: ["\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "A Next.js Project" }), ": If you haven't set up a Next.js project yet, here's a ", _jsx(_components.a, { href: "https://nextjs.org/docs/getting-started/installation", children: "quick guide" }), " to get you started."] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: _jsx(_components.a, { href: "https://github.com/MasterKale/SimpleWebAuthn", children: "Simple WebAuthn Library" }) }), ": Several packages to help reduce the amount of work needed to incorporate WebAuthn into a website. Use your favorite package manager to install ", _jsx(_components.code, { children: "@simplewebauthn/browser" }), ", ", _jsx(_components.code, { children: "@simplewebauthn/server" }), " and ", _jsx(_components.code, { children: "@simplewebauthn/typescript-types" })] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Session Storage" }), ": We'll be using session storage to manage WebAuthn challenges. We’ll use ", _jsx(_components.a, { href: "https://vercel.com/docs/storage/vercel-kv", children: "vercel’s KV" }), " to achieve this."] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "A User Database" }), ": A place to store our users' registered passkeys. To keep it simple, we’ll also use vercel’s KV to demonstrate."] }), "\n"] }), "\n", _jsx(_components.p, { children: "Now, with our tools and materials at hand, we're ready to start building." }), "\n", _jsxs(_components.h2, { id: "implementing-session-storage-with-vercels-kv", children: ["Implementing session storage with Vercel’s KV", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#implementing-session-storage-with-vercels-kv", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsxs(_components.h3, { id: "setting-up-kv-storage", children: ["Setting up KV storage", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#setting-up-kv-storage", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsxs(_components.p, { children: ["It is easy to initialize a KV storage both in production and local development, follow this guide to connect a KV store to your project and pull the environment values: ", _jsx(_components.a, { href: "https://vercel.com/docs/storage/vercel-kv/quickstart", children: "https://vercel.com/docs/storage/vercel-kv/quickstart" })] }), "\n", _jsxs(_components.h3, { id: "implement-session-management-functions", children: ["Implement session management functions", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#implement-session-management-functions", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-tsx", children: "import { kv } from '@vercel/kv';\nimport { cookies } from 'next/headers';\n\nconst sessionPrefix = 'nextjs-webauthn-example-session-';\n\ntype SessionData = {\n currentChallenge?: string;\n email?: string;\n};\n\nconst getSession = async (id: string) => {\n return kv.get(`${sessionPrefix}${id}`);\n};\n\nconst createSession = async (id: string, data: SessionData) => {\n return kv.set(`${sessionPrefix}${id}`, JSON.stringify(data));\n};\n\nexport const getCurrentSession = async (): Promise<{\n sessionId: string;\n data: SessionData;\n}> => {\n const cookieStore = cookies();\n const sessionId = cookieStore.get('session-id');\n\n if (sessionId?.value) {\n const session = await getSession(sessionId.value);\n\n if (session) {\n return { sessionId: sessionId.value, data: session };\n }\n }\n\n const newSessionId = Math.random().toString(36).slice(2);\n const newSession = { currentChallenge: undefined };\n cookieStore.set('session-id', newSessionId);\n\n await createSession(newSessionId, newSession);\n\n return { sessionId: newSessionId, data: newSession };\n};\n\nexport const updateCurrentSession = async (data: SessionData): Promise => {\n const { sessionId, data: oldData } = await getCurrentSession();\n\n await createSession(sessionId, { ...oldData, ...data });\n};\n" }) }), "\n", _jsx(_components.p, { children: "We exported 2 functions:" }), "\n", _jsxs(_components.ul, { children: ["\n", _jsxs(_components.li, { children: [_jsx(_components.code, { children: "getCurrentSession" }), ": Use Next.js cookie helper to create a session for current request, and return the value."] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.code, { children: "updateCurrentSession" }), ": Save data to current session."] }), "\n"] }), "\n", _jsxs(_components.h2, { id: "implementing-user-database-with-vercels-kv", children: ["Implementing user database with Vercel’s KV", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#implementing-user-database-with-vercels-kv", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsx(_components.p, { children: "Similarly to our session implementation, let's implement a simple user database." }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-tsx", children: "import { AuthenticatorDevice } from '@simplewebauthn/typescript-types';\nimport { kv } from '@vercel/kv';\nimport { cookies } from 'next/headers';\n\nconst userPrefix = 'nextjs-webauthn-example-user-';\n\n// The original types are \"Buffer\" which is not supported by KV\nexport type UserDevice = Omit & {\n credentialID: string;\n credentialPublicKey: string;\n};\n\ntype User = {\n email: string;\n devices: UserDevice[];\n};\n\nexport const findUser = async (email: string): Promise => {\n const user = await kv.get(`${userPrefix}${email}`);\n\n return user;\n};\n\nexport const createUser = async (email: string, devices: UserDevice[]): Promise => {\n const user = await findUser(email);\n\n if (user) {\n throw new Error('User already exists');\n }\n\n await kv.set(`${userPrefix}${email}`, { email, devices });\n return { email, devices };\n};\n" }) }), "\n", _jsx(_components.p, { children: "We created functions to find user by email, and update user data by email. Remember, this is for demonstration only, in the real product, the user data is kept in database usually." }), "\n", _jsxs(_components.h2, { id: "preparing-webauthn-functions", children: ["Preparing WebAuthn functions", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#preparing-webauthn-functions", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsx(_components.p, { children: "Before we proceed, let’s see the diagram of registration and authentication flow:" }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-mermaid", children: "sequenceDiagram\n\tparticipant User\n participant WebPage\n participant API Server\n\n User->>WebPage: Request register a new passkey\n WebPage->>API Server: Get registration options (generateWebAuthnRegistrationOptions)\n API Server->>WebPage: options\n WebPage->>WebPage: Call WebAuthn API\n WebPage->>User: Prompt to authenticate\n User->>WebPage: Perform auth\n WebPage->>API Server: Send WebAuthn API response\n API Server->>API Server: Verify and save (verifyWebAuthnRegistration)\n API Server->>WebPage: Return result\n WebPage->>User: ✅\n" }) }), "\n", _jsx(_components.p, { children: "As you can see, we need to prepare 2 functions:" }), "\n", _jsxs(_components.ol, { children: ["\n", _jsx(_components.li, { children: _jsx(_components.code, { children: "generateWebAuthnRegistrationOptions" }) }), "\n", _jsx(_components.li, { children: _jsx(_components.code, { children: "verifyWebAuthnRegistration" }) }), "\n"] }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-mermaid", children: "sequenceDiagram\n\tparticipant User\n participant WebPage\n participant API Server\n\n User->>WebPage: Request login to an email\n WebPage->>API Server: Get authentication options (generateWebAuthnLoginOptions)\n API Server->>WebPage: options\n WebPage->>WebPage: Call WebAuthn API\n WebPage->>User: Prompt to authenticate\n User->>WebPage: Perform auth\n WebPage->>API Server: Send WebAuthn API response\n API Server->>API Server: Verify (verifyWebAuthnLogin)\n API Server->>WebPage: Return result\n WebPage->>User: ✅\n" }) }), "\n", _jsx(_components.p, { children: "Similar to registration, the login requires 2 functions:" }), "\n", _jsxs(_components.ol, { children: ["\n", _jsx(_components.li, { children: _jsx(_components.code, { children: "generateWebAuthnLoginOptions" }) }), "\n", _jsx(_components.li, { children: _jsx(_components.code, { children: "verifyWebAuthnLogin" }) }), "\n"] }), "\n", _jsx(_components.p, { children: "Here’s the code:" }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-tsx", children: "'use server';\n\nimport {\n GenerateAuthenticationOptionsOpts,\n GenerateRegistrationOptionsOpts,\n VerifyAuthenticationResponseOpts,\n VerifyRegistrationResponseOpts,\n generateAuthenticationOptions,\n generateRegistrationOptions,\n verifyAuthenticationResponse,\n verifyRegistrationResponse,\n} from '@simplewebauthn/server';\nimport { UserDevice, createUser, findUser, getCurrentSession, updateCurrentSession } from './user';\nimport { origin, rpId } from './constants';\nimport {\n AuthenticationResponseJSON,\n RegistrationResponseJSON,\n} from '@simplewebauthn/typescript-types';\nimport { isoBase64URL } from '@simplewebauthn/server/helpers';\n\nexport const generateWebAuthnRegistrationOptions = async (email: string) => {\n const user = await findUser(email);\n\n if (user) {\n return {\n success: false,\n message: 'User already exists',\n };\n }\n\n const opts: GenerateRegistrationOptionsOpts = {\n rpName: 'SimpleWebAuthn Example',\n rpID: rpId,\n userID: email,\n userName: email,\n timeout: 60000,\n attestationType: 'none',\n excludeCredentials: [],\n authenticatorSelection: {\n residentKey: 'discouraged',\n },\n /**\n * Support the two most common algorithms: ES256, and RS256\n */\n supportedAlgorithmIDs: [-7, -257],\n };\n\n const options = await generateRegistrationOptions(opts);\n\n await updateCurrentSession({ currentChallenge: options.challenge, email });\n\n return {\n success: true,\n data: options,\n };\n};\n\nexport const verifyWebAuthnRegistration = async (data: RegistrationResponseJSON) => {\n const {\n data: { email, currentChallenge },\n } = await getCurrentSession();\n\n if (!email || !currentChallenge) {\n return {\n success: false,\n message: 'Session expired',\n };\n }\n\n const expectedChallenge = currentChallenge;\n\n const opts: VerifyRegistrationResponseOpts = {\n response: data,\n expectedChallenge: `${expectedChallenge}`,\n expectedOrigin: origin,\n expectedRPID: rpId,\n requireUserVerification: false,\n };\n const verification = await verifyRegistrationResponse(opts);\n\n const { verified, registrationInfo } = verification;\n\n if (!verified || !registrationInfo) {\n return {\n success: false,\n message: 'Registration failed',\n };\n }\n\n const { credentialPublicKey, credentialID, counter } = registrationInfo;\n\n /**\n * Add the returned device to the user's list of devices\n */\n const newDevice: UserDevice = {\n credentialPublicKey: isoBase64URL.fromBuffer(credentialPublicKey),\n credentialID: isoBase64URL.fromBuffer(credentialID),\n counter,\n transports: data.response.transports,\n };\n\n await updateCurrentSession({});\n\n try {\n await createUser(email, [newDevice]);\n } catch {\n return {\n success: false,\n message: 'User already exists',\n };\n }\n\n return {\n success: true,\n };\n};\n\nexport const generateWebAuthnLoginOptions = async (email: string) => {\n const user = await findUser(email);\n\n if (!user) {\n return {\n success: false,\n message: 'User does not exist',\n };\n }\n\n const opts: GenerateAuthenticationOptionsOpts = {\n timeout: 60000,\n allowCredentials: user.devices.map((dev) => ({\n id: isoBase64URL.toBuffer(dev.credentialID),\n type: 'public-key',\n transports: dev.transports,\n })),\n userVerification: 'required',\n rpID: rpId,\n };\n const options = await generateAuthenticationOptions(opts);\n\n await updateCurrentSession({ currentChallenge: options.challenge, email });\n\n return {\n success: true,\n data: options,\n };\n};\n\nexport const verifyWebAuthnLogin = async (data: AuthenticationResponseJSON) => {\n const {\n data: { email, currentChallenge },\n } = await getCurrentSession();\n\n if (!email || !currentChallenge) {\n return {\n success: false,\n message: 'Session expired',\n };\n }\n\n const user = await findUser(email);\n\n if (!user) {\n return {\n success: false,\n message: 'User does not exist',\n };\n }\n\n const dbAuthenticator = user.devices.find((dev) => dev.credentialID === data.rawId);\n\n if (!dbAuthenticator) {\n return {\n success: false,\n message: 'Authenticator is not registered with this site',\n };\n }\n\n const opts: VerifyAuthenticationResponseOpts = {\n response: data,\n expectedChallenge: `${currentChallenge}`,\n expectedOrigin: origin,\n expectedRPID: rpId,\n authenticator: {\n ...dbAuthenticator,\n credentialID: isoBase64URL.toBuffer(dbAuthenticator.credentialID),\n credentialPublicKey: isoBase64URL.toBuffer(dbAuthenticator.credentialPublicKey),\n },\n requireUserVerification: true,\n };\n const verification = await verifyAuthenticationResponse(opts);\n\n await updateCurrentSession({});\n\n return {\n success: verification.verified,\n };\n};\n" }) }), "\n", _jsxs(_components.h2, { id: "build-the-web-page", children: ["Build the web page", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#build-the-web-page", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsx(_components.p, { children: "We’ve completed the preparation, let’s build the page:" }), "\n", _jsx(_components.pre, { children: _jsx(_components.code, { className: "language-tsx", children: "'use client';\n\nimport { startAuthentication, startRegistration } from '@simplewebauthn/browser';\nimport {\n generateWebAuthnLoginOptions,\n generateWebAuthnRegistrationOptions,\n verifyWebAuthnLogin,\n verifyWebAuthnRegistration,\n} from '@/libraries/webauthn';\nimport styles from './page.module.css';\n\nexport default function Home() {\n const handleSubmit = async (event: React.FormEvent) => {\n event.preventDefault();\n\n const formData = new FormData(event.currentTarget);\n const email = formData.get('email')?.toString();\n const type = formData.get('type')?.toString();\n\n if (!email) {\n return;\n }\n\n if (type === 'register') {\n const response = await generateWebAuthnRegistrationOptions(email);\n\n if (!response.success || !response.data) {\n alert(response.message ?? 'Something went wrong!');\n return;\n }\n\n const localResponse = await startRegistration(response.data);\n const verifyResponse = await verifyWebAuthnRegistration(localResponse);\n\n if (!verifyResponse.success) {\n alert(verifyResponse.message ?? 'Something went wrong!');\n return;\n }\n\n alert('Registration successful!');\n } else {\n const response = await generateWebAuthnLoginOptions(email);\n\n if (!response.success || !response.data) {\n alert(response.message ?? 'Something went wrong!');\n return;\n }\n\n const localResponse = await startAuthentication(response.data);\n const verifyResponse = await verifyWebAuthnLogin(localResponse);\n\n if (!verifyResponse.success) {\n alert(verifyResponse.message ?? 'Something went wrong!');\n return;\n }\n\n alert('Login successful!');\n }\n };\n\n return (\n

\n \n

\n );\n}\n" }) }), "\n", _jsxs(_components.h2, { id: "conclusion", children: ["Conclusion", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#conclusion", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsx(_components.p, { children: "Congratulations on navigating through the intricacies of implementing WebAuthn in a Next.js application. As we wrap up, it's important to address some crucial considerations for deploying it in a production environment." }), "\n", _jsxs(_components.h3, { id: "key-considerations-for-production-deployment", children: ["Key Considerations for Production Deployment", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#key-considerations-for-production-deployment", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsxs(_components.ol, { children: ["\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "User Identifier Adjustment" }), ": In this tutorial, we used an email address as the user identifier. However, in a production scenario, you might need to use a different identifier, such as a ", _jsx(_components.strong, { children: _jsx(_components.code, { children: "userId" }) }), " or ", _jsx(_components.strong, { children: _jsx(_components.code, { children: "username" }) }), "."] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Database Integration" }), ": While we utilized Vercel’s KV as a simple demonstration of session and user data management, a real-world application should integrate a more robust database system (like PostgreSQL, MongoDB, etc.)"] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "Customizing WebAuthn Options" }), ": The WebAuthn options we explored are a starting point. Depending on your application's requirements and security policies, you may need to adjust these settings. Consult the ", _jsx(_components.a, { href: "https://www.w3.org/TR/webauthn/", children: "WebAuthn documentation" }), " and the ", _jsx(_components.a, { href: "https://github.com/MasterKale/SimpleWebAuthn", children: "Simple WebAuthn library's documentation" }), " for guidance on customizing these options to suit your specific needs."] }), "\n"] }), "\n", _jsx(_components.p, { children: "Thank you for joining us on this educational adventure. Even in this minimal example, integrating WebAuthn is not a simple task, there is another option, try WebAuthn in Logto’s MFA:" }), "\n", _jsx(LogtoCloudButton, { children: "Try Logto multi-factor authentication" })] }); } function MDXContent(props = {}) { const {wrapper: MDXLayout} = { ..._provideComponents(), ...props.components }; return MDXLayout ? _jsx(MDXLayout, { ...props, children: _jsx(_createMdxContent, { ...props }) }) : _createMdxContent(props); } return { headings, readingTime, frontmatter, default: MDXContent }; function _missingMdxReference(id, component) { throw new Error("Expected " + (component ? "component" : "object") + " `" + id + "` to be defined: you likely forgot to import, pass, or provide it."); }