在幾分鐘內打造一個基於 Node.js 的 Logto 框架 SDK

之前在這篇文章中，我們在幾分鐘內打造了一個為 Logto 的網頁 SDK。現在，讓我們專注於 Node.js，這是 JavaScript 開發者常用的另一個熱門平台。

在本指南中，我們將引導你完成使用 @logto/node 創建一個簡單 Express SDK 的步驟。這個 SDK 會實現登入流程，你可以按照相同的步驟為任何其他基於 Node.js 的平台（例如 Koa、Next.js、NestJS 等）創建 SDK。

登入流程#

在開始之前，讓我們回顧一下 Logto 登入流程。登入流程包括以下步驟：

1. 重定向到 Logto：用戶被重定向到 Logto 登入頁面。
2. 驗證：用戶輸入他們的憑證並在 Logto 上驗證。
3. 重定向回你的應用：成功驗證後，用戶被重定向回你的應用並帶有一個驗證碼。
4. 代碼交換：你的應用交換驗證碼以獲取憑證並將其作為驗證狀態存儲。

@logto/node 的簡短介紹#

類似於 @logto/browser，@logto/node 套件提供一個 LogtoClient 類，提供 Logto 的核心功能，包括登入流程的方法：

1. signIn()：生成 OIDC 驗證 URL，並重定向到它。
2. handleSignInCallback()：檢查並解析回調 URL 並提取驗證碼，然後通過調用 token 端點交換代碼以獲取憑證。
3. getContext()：根據會話 cookie 獲取當前請求的上下文，包括驗證狀態和用戶信息。

打造 Express SDK#

在 SDK 中，我們將提供兩個路由處理器（/sign-in 和 /sign-in-callback）以及 withLogto 中介軟件：

1. /sign-in：一個觸發登入流程的路由處理器，響應重定向到 OIDC 驗證 URL。
2. /sign-in-callback：一個處理回調 URL 的路由處理器，交換驗證碼以獲取憑證，存儲它們，並完成登入流程。
3. withLogto 中介軟件：一個調用 getContext() 的中介軟件，用於檢索當前請求的上下文，包括驗證狀態和用戶信息。

要使用該 SDK，你只需將中介軟件添加到你的 Express 應用中以保護路由，並使用路由處理器來觸發登入流程和處理回調。

步驟 1：安裝套件#

首先，使用 npm 或其他套件管理器安裝 @logto/node 套件：

步驟 2：準備存儲適配器#

初始化 LogtoClient 實例需要一個存儲適配器。

假設 SDK 用戶已經設置了 express session， 我們可以通過創建一個新檔 storage.ts 來實現 Storage 類：

步驟 3：實現路由處理器#

HTTP 請求是無狀態的，因此我們需要為每個請求初始化客戶端實例。讓我們準備一個功能助手來創建客戶端實例：

在此功能中，我們實現了 navigate 適配器以及 ExpressStorage 適配器。navigate 適配器用於將用戶重定向到登入 URL。

接下來，讓我們在一個名為 handleAuthRoutes 的函數中實現路由處理器：

1. /auth/sign-in 路由處理器通過調用 signIn() 來觸發登入流程，登入狀態存儲在會話中，將由 /auth/sign-in-callback 路由處理器消耗。
2. /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。

資源：

1. Logto Node SDK
2. Logto Express SDK