"use strict"; const {Fragment: _Fragment, jsx: _jsx, jsxs: _jsxs} = arguments[0]; const {useMDXComponents: _provideComponents} = arguments[0]; const headings = [{ "data": { "id": "先決條件", "hProperties": { "id": "先決條件" } }, "depth": 2, "value": "先決條件" }, { "data": { "id": "使用-vercel-的-kv-實施會話存儲", "hProperties": { "id": "使用-vercel-的-kv-實施會話存儲" } }, "depth": 2, "value": "使用 Vercel 的 KV 實施會話存儲" }, { "data": { "id": "設置-kv-存儲", "hProperties": { "id": "設置-kv-存儲" } }, "depth": 3, "value": "設置 KV 存儲" }, { "data": { "id": "實施會話管理功能", "hProperties": { "id": "實施會話管理功能" } }, "depth": 3, "value": "實施會話管理功能" }, { "data": { "id": "使用-vercel-的-kv-實施用戶數據庫", "hProperties": { "id": "使用-vercel-的-kv-實施用戶數據庫" } }, "depth": 2, "value": "使用 Vercel 的 KV 實施用戶數據庫" }, { "data": { "id": "準備-webauthn-功能", "hProperties": { "id": "準備-webauthn-功能" } }, "depth": 2, "value": "準備 WebAuthn 功能" }, { "data": { "id": "建設網頁", "hProperties": { "id": "建設網頁" } }, "depth": 2, "value": "建設網頁" }, { "data": { "id": "結論", "hProperties": { "id": "結論" } }, "depth": 2, "value": "結論" }, { "data": { "id": "生產部署的關鍵考慮事項", "hProperties": { "id": "生產部署的關鍵考慮事項" } }, "depth": 3, "value": "生產部署的關鍵考慮事項" }]; const readingTime = { "minutes": 6, "words": 1946, "text": "6 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: ["歡迎回到我們的 WebAuthn 系列。在之前的文章中，我們已經涵蓋了 ", _jsx(_components.a, { href: "https://blog.logto.io/webauthn-base-knowledge/", children: "WebAuthn 的基礎知識" }), " 和 ", _jsx(_components.a, { href: "https://blog.logto.io/web-authn-and-passkey-101/", children: "101 指南" }), "。如果你剛剛加入我們，不妨查看這些基礎文章來快速了解。"] }), "\n", _jsx(_components.p, { children: "今天，我們要捲起袖子，把理論付諸於實踐。我們將利用 Next.js 的新功能 \"Server Actions\"。我們的目標是實現在 Next.js 應用中實施 WebAuthn，並準備好使用 WebAuthn。" }), "\n", _jsxs(_components.p, { children: ["在我們深入探索代碼海洋之前，先讓我們看看旅程的終點 - 一個功能齊全的", _jsx(_components.a, { href: "https://nextjs-webauthn-alpha.vercel.app/", children: "演示網站" }), " 。訪問它來查看 WebAuthn 的實際應用，並體驗你將要建設的內容。在這個演示網站中，你可以註冊新用戶並使用剛註冊的通行密碼登入。"] }), "\n", _jsx(_components.p, { children: _jsx(_components.img, { src: "https://uploads.strapi.logto.io/1/preview_fe67ff2888.webp", alt: "預覽" }) }), "\n", _jsxs(_components.p, { children: ["而對於那些喜歡手持地圖的人，我們也為你準備好了！我們討論的所有代碼都在公眾的 ", _jsx(_components.a, { href: "https://github.com/wangsijie/nextjs-webauthn", children: "GitHub 資源庫" }), " 中。這個資源庫是你的伴侶指南，提供我們實施方案的完整源代碼。"] }), "\n", _jsx(_components.p, { children: "準備好踏上這段激動人心的冒險了嗎？讓我們開始吧！" }), "\n", _jsxs(_components.h2, { id: "先決條件", children: ["先決條件", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#先決條件", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsx(_components.p, { children: "在我們開始之前，讓我們確保我們擁有一切所需：" }), "\n", _jsxs(_components.ol, { children: ["\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "一個 Next.js 項目" }), "：如果你還沒設置 Next.js 項目，這裡有一個", _jsx(_components.a, { href: "https://nextjs.org/docs/getting-started/installation", children: "快速指南" }), "可以幫助你開始。"] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: _jsx(_components.a, { href: "https://github.com/MasterKale/SimpleWebAuthn", children: "簡單 WebAuthn 庫" }) }), "：幾個包可以幫助減少將 WebAuthn 整合到網站所需的工作量。使用你喜歡的包管理器來安裝 ", _jsx(_components.code, { children: "@simplewebauthn/browser" }), "、", _jsx(_components.code, { children: "@simplewebauthn/server" }), " 和 ", _jsx(_components.code, { children: "@simplewebauthn/typescript-types" })] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "會話存儲" }), "：我們將使用會話存儲來管理 WebAuthn 挑戰。我們將使用 ", _jsx(_components.a, { href: "https://vercel.com/docs/storage/vercel-kv", children: "vercel 的 KV" }), " 來實現這一點。"] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "一個用戶數據庫" }), "：一個儲存我們用戶的註冊通行密碼的地方。為了簡化，我們也將使用 vercel 的 KV 來演示。"] }), "\n"] }), "\n", _jsx(_components.p, { children: "現在，準備好了工具和材料，我們可以開始建設了。" }), "\n", _jsxs(_components.h2, { id: "使用-vercel-的-kv-實施會話存儲", children: ["使用 Vercel 的 KV 實施會話存儲", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#使用-vercel-的-kv-實施會話存儲", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsxs(_components.h3, { id: "設置-kv-存儲", children: ["設置 KV 存儲", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#設置-kv-存儲", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsxs(_components.p, { children: ["在生產和本地開發中初始化 KV 存儲都很容易，按照這個指南連接 KV 存儲到你的項目並提取環境值：", _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: "實施會話管理功能", children: ["實施會話管理功能", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#實施會話管理功能", 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: "我們導出了兩個功能：" }), "\n", _jsxs(_components.ul, { children: ["\n", _jsxs(_components.li, { children: [_jsx(_components.code, { children: "getCurrentSession" }), "：使用 Next.js cookie 助手為當前請求創建會話並返回值。"] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.code, { children: "updateCurrentSession" }), "：將數據保存到當前會話。"] }), "\n"] }), "\n", _jsxs(_components.h2, { id: "使用-vercel-的-kv-實施用戶數據庫", children: ["使用 Vercel 的 KV 實施用戶數據庫", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#使用-vercel-的-kv-實施用戶數據庫", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsx(_components.p, { children: "同樣在我們的會話實施中，讓我們實施一個簡單的用戶數據庫。" }), "\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// 原始類型是 \"Buffer\"，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: "我們創建了按電子郵件查找用戶和更新用戶數據的功能。記住，這僅用於演示，真實產品中，用戶數據通常保存在數據庫中。" }), "\n", _jsxs(_components.h2, { id: "準備-webauthn-功能", children: ["準備 WebAuthn 功能", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#準備-webauthn-功能", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsx(_components.p, { children: "在我們繼續之前，讓我們看看註冊和身份驗證流程圖：" }), "\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: "如你所見，我們需要準備兩個功能：" }), "\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: "與註冊類似，登入需要兩個功能：" }), "\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: "以下是代碼：" }), "\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 * 將返回的設備添加到用戶的設備列表中\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: "建設網頁", children: ["建設網頁", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#建設網頁", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsx(_components.p, { children: "我們已經完成了準備工作，讓我們建設網頁：" }), "\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: "結論", children: ["結論", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#結論", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsx(_components.p, { children: "恭喜你，完成了在 Next.js 應用中實施 WebAuthn 的複雜工作。當我們結束時，重要的是要解決一些關鍵的考慮事項，以便在生產環境中部署它。" }), "\n", _jsxs(_components.h3, { id: "生產部署的關鍵考慮事項", children: ["生產部署的關鍵考慮事項", _jsx(_components.a, { "aria-hidden": "true", tabIndex: "-1", href: "#生產部署的關鍵考慮事項", children: _jsx(_components.span, { children: "#" }) })] }), "\n", _jsxs(_components.ol, { children: ["\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "用戶標識符調整" }), "：在本教學中，我們使用了電子郵件地址作為用戶標識符。然而，在生產情況中，你可能需要使用不同的標識符，例如 ", _jsx(_components.strong, { children: _jsx(_components.code, { children: "userId" }) }), " 或 ", _jsx(_components.strong, { children: _jsx(_components.code, { children: "username" }) }), "。"] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "數據庫整合" }), "：雖然我們使用了 Vercel 的 KV 作為會話和用戶數據管理的簡單演示，但現實世界的應用程序應該整合一個更健全的數據庫系統（如 PostgreSQL、MongoDB 等）。"] }), "\n", _jsxs(_components.li, { children: [_jsx(_components.strong, { children: "自定義 WebAuthn 選項" }), "：我們探討的 WebAuthn 選項是一個起點。根據你的應用需求和安全策略，你可能需要調整這些設置。請參閱 ", _jsx(_components.a, { href: "https://www.w3.org/TR/webauthn/", children: "WebAuthn 文檔" }), " 和 ", _jsx(_components.a, { href: "https://github.com/MasterKale/SimpleWebAuthn", children: "簡單 WebAuthn 庫的文檔" }), " 指導如何根據特定需求自定義這些選項。"] }), "\n"] }), "\n", _jsx(_components.p, { children: "感謝你加入我們的教育冒險。即使在這個簡單的例子中，集成 WebAuthn 也不是一個簡單的任務，還有另一個選擇，試試 Logto 的 MFA 的 WebAuthn：" }), "\n", _jsx(LogtoCloudButton, { children: "嘗試 Logto 多重身份驗證" })] }); } 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."); }