在幾分鐘內打造一個基於 Node.js 的 Logto 框架 SDK
學習如何使用 `@logto/node` 為 Logto 創建自訂 SDK。
Developer
之前在這篇文章中，我們在幾分鐘內打造了一個為 Logto 的網頁 SDK。現在，讓我們專注於 Node.js，這是 JavaScript 開發者常用的另一個熱門平台。
在本指南中，我們將引導你完成使用 @logto/node 創建一個簡單 Express SDK 的步驟。這個 SDK 會實現登入流程，你可以按照相同的步驟為任何其他基於 Node.js 的平台（例如 Koa、Next.js、NestJS 等）創建 SDK。
登入流程
在開始之前，讓我們回顧一下 Logto 登入流程。登入流程包括以下步驟：
- 重定向到 Logto：用戶被重定向到 Logto 登入頁面。
- 驗證：用戶輸入他們的憑證並在 Logto 上驗證。
- 重定向回你的應用：成功驗證後，用戶被重定向回你的應用並帶有一個驗證碼。
- 代碼交換：你的應用交換驗證碼以獲取憑證並將其作為驗證狀態存儲。
@logto/node 的簡短介紹
類似於 @logto/browser，@logto/node 套件提供一個 LogtoClient 類，提供 Logto 的核心功能，包括登入流程的方法：
signIn()：生成 OIDC 驗證 URL，並重定向到它。handleSignInCallback()：檢查並解析回調 URL 並提取驗證碼，然後通過調用 token 端點交換代碼以獲取憑證。getContext()：根據會話 cookie 獲取當前請求的上下文，包括 驗證狀態和用戶信息。
打造 Express SDK
在 SDK 中，我們將提供兩個路由處理器（/sign-in 和 /sign-in-callback）以及 withLogto 中介軟件：
/sign-in：一個觸發登入流程的路由處理器，響應重定向到 OIDC 驗證 URL。/sign-in-callback：一個處理回調 URL 的路由處理器，交換驗證碼以獲取憑證，存儲它們，並完成登入流程。withLogto中介軟件：一個調用getContext()的中介軟件，用於檢索當前請求的上下文，包括驗證狀態和用戶信息。
要使用該 SDK，你只需將中介軟件添加到你的 Express 應用中以保護路由，並使用路由處理器來觸發登入流程和處理回調。
步驟 1：安裝套件
首先，使用 npm 或其他套件管理器安裝 @logto/node 套件：
步驟 2：準備存儲適配器
初始化 LogtoClient 實例需要一個存儲適配器。
假設 SDK 用戶已經設置了 express session， 我們可以通過創建一個新檔 storage.ts 來實現 Storage 類：
步驟 3：實現路由處理器
HTTP 請求是無狀態的，因此我們需要為每個請求初始化客戶端實例。 讓我們準備一個功能助手來創建客戶端實例：
在此功能中，我們實現了 navigate 適配器以及 ExpressStorage 適配器。navigate 適配器用於將用戶重定向到登入 URL。
接下來，讓我們在一個名為 handleAuthRoutes 的函數中實現路由處理器：
/auth/sign-in路由處理器通過調用signIn()來觸發登入流程，登入狀態存儲在會話中，將由/auth/sign-in-callback路由處理器消耗。/auth/sign-in-callback路由處理器處理回調 URL，通過調用handleSignInCallback()來交換驗證碼以獲取憑證，這些憑證由ExpressStorage適配器存儲在會話中。交換完成後，用戶被重定向回主頁。
步驟 4：實現中介軟件
withLogto 中介軟件用於保護路由。它通過調用 getContext() 來獲取當前請求的上下文，包括驗證狀態和用戶信息。
函數 getContext 使用存儲適配器從會話中獲取憑證。
檢查點：使用 SDK
現在，你已經為 Logto 打造了 Express SDK，你可以通過添加中介軟件來保護路由，並使用路由處理器來觸發登入流程和處理回調。
以下是一個在 Express 應用中使用 SDK 的簡單例子：
在這個例子中，我們使用 withLogto 中介軟件來檢查驗證狀態，如果用戶未驗證，則將其重定向到登入頁面，否則，我們顯示一條歡迎信息。
你可以在這裡查看官方的 Express 示例項目。
結論
在本指南中，我們引導你完成了創建 Express SDK 的步驟，實現基本的驗證流程。此處提供的 SDK 是一個基本示例。你可以通過添加更多方法和功能來擴展它以滿足應用的需求。
你可以按照相同的步驟為任何其他基於 JavaScript 並在 Node.js 上運行的平台創建 SDK。
資源：