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

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

在本指南中，我們將引導你完成使用 @logto/node 為 Logto 創建一個簡單的 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，然後重定向到該 URL。
2. handleSignInCallback()：檢查並解析回調 URL，提取授權碼，然後調用令牌端點交換授權碼為令牌。
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 示例專案。

結論#

在本指南中，我們已引導你完成創建一個實現基本身份驗證流程的 Logto Express SDK 的步驟。這裡提供的 SDK 是一個基礎示例。你可以透過添加更多的方法和功能來擴展它以滿足你的應用需求。

你可以遵循相同的步驟來為任何在 Node.js 上運行的其他 JavaScript 平台創建 SDK。

資源：

1. Logto Node SDK
2. Logto Express SDK