構建多租戶 SaaS 應用程序：從設計到實施的完整指南

像 Notion、Slack 或 Figma 這樣的應用程序是如何構建的？這些多租戶 SaaS 應用程序看起來使用簡單，但自己構建一個呢？那是另一回事。

當我第一次考慮構建這樣一個複雜的系統時，我的腦袋簡直炸掉了：

• 用戶需要多種登入選項（電子郵件、Google、GitHub）
• 每位用戶可以創建和屬於多個組織
• 每個組織中有不同的許可級別
• 企業組織要求自動加入特定的電子郵件域
• 對於敏感操作需要 MFA
• ...

"老闆，我們兩週後談產品設計吧。我現在陷入困境了。"

但當我真正開始動手時，我發現這並沒有看上去那麼艱難。

我只花了不到 2 小時就 構建了一個擁有所有這些功能的系統！

我將向你展示如何從頭開始設計和實施這樣的系統——你會驚訝於 2025 年用現代工具和正確的架構方法做起來有多簡單。

完整的源代碼在本文末尾提供。我們開始吧！

我們將從一個名為 DocuMind 的 AI 文檔 SaaS 產品開始。

DocuMind 是一款設計為多租戶模型的 AI 文檔 SaaS 產品，支持個人用戶、小型企業和企業用戶。

該平台為文檔管理提供強大的 AI 功能，包括自動生成摘要、關鍵點提取以及組織內的智能內容推薦。

SaaS 認證和授權需要哪些功能？#

首先，讓我們回顧一下必要的要求。你需要哪些功能？

多租戶架構#

要實現多租戶架構，你將需要一個稱為 "組織" 的實體層。想像一下擁有一個用戶池，他們可以訪問多個工作空間。每個組織代表一個工作空間，用戶在根據其指定角色訪問不同工作空間（組織）的同時保持單一身份。

這是身份驗證提供者中廣泛使用的功能。身份管理系統中的組織對應於你的 SaaS 應用的工作空間、項目或租戶。

會員資格#

成員是一個用於指示身份在組織內部會員資格狀態的臨時概念。

例如，Sarah 使用她的電子郵件，[email protected]，註冊你的應用。她可以屬於不同的工作空間。如果 Sarah 是 工作空間 A 的成員，但不是 工作空間 B，那麼她被認為是 工作空間 A 的成員，而不是 工作空間 B 的成員。

角色和權限設計#

在多租戶架構中，用戶需要具有特定 權限 的 角色 來訪問其租戶資源。 權限是定義特定操作（如 read: order 或 write: order）的詳細訪問控制。它們決定可以在特定資源上執行哪些操作。

角色是分配給多租戶環境中成員的一組權限。

你需要定義這些角色和權限，然後將角色分配給用戶，有時它可能包含自動化的過程。例如：

1. 加入組織的用戶會自動獲得 成員 角色。
2. 創建工作空間的第一個用戶會自動被分配 管理員 角色。

註冊和登入流程#

確保用戶友好且安全的註冊和身份認證過程，包括基本登入和註冊選項：

1. 電子郵件和密碼登入：傳統的電子郵件和密碼登入方法。
2. 密碼無需登入：使用電子郵件驗證碼進行簡單且安全的訪問。
3. 賬戶管理：用戶可以在賬戶中心更新其電子郵件、密碼和其他詳細信息。
4. 社交登入：選項包括 Google 和 GitHub 快速登入。
5. 多因素認證（MFA）：通過允許使用 Duo 等身份驗證應用程式登入來提高安全性。

租戶創建和邀請#

在多租戶 SaaS 應用中，用戶流的一個關鍵區別是需要支持租戶創建和成員邀請。這個過程需要精心計劃和執行，因為它在產品激活和增長中發揮著關鍵作用。

這裡有一些你需要考慮的典型使用流程：

這裡有一些在幾乎每個 SaaS 應用中常見的場景。使用這些作為參考來激發你們的產品和設計團隊的靈感，並根據需要自由創建自己的流程。

技術架構和系統設計#

一旦我們了解所有產品需求，就可以進行實施。

定義身份認證策略#

身份認證聽起來很可怕。用戶需要：

• 電子郵件 & 密碼註冊/登入
• Google/Github 一鍵登入
• 忘記密碼時重置密碼
• 企業客戶的團隊登錄
• ...

僅僅實施這些基本功能可能需要數週的開發時間。

但現在，我們不需要自己構建這些功能！

現代身份驗證提供程序（這次我將選擇 Logto）已為我們打包了所有這些功能。身份認證流程如下：

從數週的開發時間到 15 分鐘的設置時間，Logto 處理了所有複雜的流程！我們將在實施部分中覆蓋集成步驟。現在我們可以專注於構建 DocuMind 的核心功能！

建立多租戶架構#

組織系統允許用戶創建和加入多個組織。讓我們了解核心關係：

在此系統中，每個用戶可以屬於多個組織，每個組織可以有多個成員。

在多租戶應用中啟用訪問控制#

基於角色的訪問控制 (RBAC) 對於在多租戶 SaaS 應用程序中確保安全和可擴展性至關重要。

在多租戶應用中，權限和角色的設計通常是一致的，因為它源自於產品設計。例如，在多個工作空間中，通常有一個管理員角色和一個成員角色。作為身份驗證提供者的 Logto 有以下組織層級角色基於訪問控制設計：

1. 統一的權限定義：系統級別定義的權限，適用於所有組織，確保可維護和一致的權限管理
2. 組織模板：通過組織模板預先定義的角色和權限組合，簡化組織初始化

權限關係如下所示：

由於每個用戶在每個組織中需要自己的角色，角色與組織之間的關係必須反映分配給每個用戶的角色：

我們已經設計了組織系統和訪問控制系統，現在我們可以開始構建我們的產品！

技術棧#

我選擇了一個適合初學者的便攜棧：

1. 前端：React（可輕鬆轉換為 Vue/Angular/Svelte）
2. 後端：Express（簡單、直觀的 API）

為什麼要分離前端和後端呢？因為它具有清晰的架構，容易學習且易於切換技術棧。至於身份驗證提供者，我以 Logto 為例。

對於以下指南，此處的模式適用於：任何前端、任何後端和任何身份驗證系統。

為你的應用添加基本身份認證流程#

這是最簡單的一步。我們只需將 Logto 集成到我們的項目中。然後我們可以根據需要在 Logto 控制台中配置用戶登入/註冊方法。

安裝 Logto 到你的應用中#

首先，登錄到 Logto Cloud。如果你沒有帳戶，可以免費註冊一個帳戶。創建一個開發租戶進行測試。

在租戶控制台中，點擊左側的 "應用程序" 按鈕。然後選擇 React 開始構建我們的應用程序。

按照頁面上的指南進行操作。你可以在大約 5 分鐘內完成 Logto 的集成！

以下是我的集成代碼：

這裡有一個實用的技巧：我們的登錄頁有登入和註冊按鈕。註冊按鈕直接連到 Logto 的註冊頁面。這是通過使用 Logto 的第一步功能來實現的。它決定用戶首先看到驗證流程的哪一步。

當你的產品預期有很多新用戶時，可以預設到註冊頁面。

在點擊登入後，你將進入 Logto 的登入頁面。成功登錄（或註冊）後，恭喜！你的應用有了第一個用戶（就是你自己）！

當你想登出用戶時，可以從 useLogto 鉤子中調用 signOut 函數。

自定義登錄和註冊方法#

在 Logto 控制台中，點擊左側菜單的 "登入體驗"。然後點擊 "註冊和登入" 標籤。 在此頁面上，按照說明配置 Logto 的登入/註冊方法。

登錄流程如下所示：

啟用多因素認證#

使用 Logto，啟用 MFA 非常簡單。只需點擊 Logto 控制台中的 "多因素認證" 按鈕。然後在多因素認證頁面上啟用它。

MFA 流程如下所示：

一切都非常簡單！我們只用了幾分鐘就設置了一個複雜的用戶身份認證系統！

添加多租戶組織體驗#

現在我們有了第一位用戶！然而，這位用戶尚未屬於任何組織，我們也還未創建任何組織。

Logto 提供了對多租戶的內置支持。你可以在 Logto 中創建任何數量的組織。每個組織都可以有多個成員。

每個用戶可以從 Logto 獲取其組織信息。這使得多租戶支持成為可能。

獲取用戶的組織信息#

要從 Logto 獲取用戶的組織信息，請遵循以下兩個步驟：

在 Logto 配置中聲明組織信息訪問。這是通過設置適當的 scopes 和 resources 來完成的。

使用 Logto 的 fetchUserInfo 方法獲取用戶信息，包括組織數據。

完成這些步驟後，你需要登出並重新登入。這是必要的，因為我們修改了請求的範圍和資源。

現在，你還沒有創建任何組織。用戶也沒有加入任何組織。儀表板將顯示 "你尚不屬於任何組織"。

接下來，我們將為用戶創建一個組織並將其添加到其中。

感謝 Logto，我們不需要構建複雜的組織關係。我們只需要在 Logto 中創建一個組織並將用戶添加到其中。Logto 為我們處理了所有的複雜性。有兩種方式可以創建組織：

1. 通過 Logto 控制台手動創建組織
2. 使用 Logto 管理 API 創建組織，特別是在設計允許用戶創建自己組織（工作空間）的 SaaS 流程時。

在 Logto 控制台中創建組織#

點擊 Logto 控制台左側的 "組織" 菜單按鈕。創建一個組織。

現在你擁有了你的第一個組織。

接下來，讓我們將用戶添加到此組織。

進入組織詳細頁面。切換到成員標籤。點擊 "添加成員" 按鈕。從左側列表中選擇你的登入用戶。在右下角點擊 "添加成員" 按鈕。現在你已經成功地將用戶添加到此組織。

刷新你的 APP 頁面。你將看到用戶現在已屬於一個組織！

實現自助式組織創建體驗#

在控制台創建組織是不夠的。你的 SaaS 應用需要一個允許終端用戶輕鬆創建和管理自己的工作空間的流。要實施此功能，請使用 Logto 管理 API。

欲獲取指導，請查看與管理 API 交互文檔以設置與 Logto 的 API 通信。

理解組織身份驗證交互流程#

讓我們以組織創建流程為例。組織創建過程如下所示：

此流程有兩個關鍵認證要求：

1. 保護後端服務 API：
   • 前端訪問我們的後端服務 API 需要身份驗證
   • 通過驗證用戶的 Logto 訪問令牌來保護 API 端點
   • 確保只有認證用戶才能訪問我們的服務
2. 訪問 Logto 管理 API：
   • 後端服務需要安全地調用 Logto 管理 API
   • 為設置訪問資格，請遵循 與管理 API 交互指南
   • 使用機器對機器身份驗證來獲取訪問憑據

保護你的後端 API#

首先，讓我們在我們的後端服務中創建一個 API 端點來創建組織。

我們的後端服務 API 只允許認證用戶。我們需要使用 Logto 來保護我們的 API。也需要知道當前的用戶信息（例如用戶 ID）。

在 Logto 的概念中（和 OAuth 2.0），我們的後端服務作為一個資源服務器。用戶使用前端的訪問令牌來訪問 DocuMind 資源服務器。資源服務器驗證此令牌。如果有效，它返回請求的資源。

我們來創建一個 API 資源來表示我們的後端服務。

進入 Logto 控制台。

1. 點擊右側的 "API 資源" 按鈕。
2. 點擊 "創建 API 資源"。在彈出窗口中選擇 Express。
3. 輸入 "DocuMind API" 作為 API 名稱。使用 "https://api.documind.com" 作為 API 標識符。
4. 點擊創建。

不用擔心此 API 標識符 URL。它只是 Logto 中你的 API 的唯一標識符。與你的實際後端服務 URL 無關。

你將看到一個教程以使用 API 資源。你可以遵循該教程或我們的步驟。

讓我們創建一個 requireAuth 中間件來保護 POST /organizations 端點。

要使用此中間件，我們需要以下環境變量：

• LOGTO_JWKS_URL
• LOGTO_ISSUER

從你的 Logto 租戶的 OpenID 配置端點獲取這些變量。訪問 https://<your-tenant-id>.logto.app/oidc/.well-known/openid-configuration。你將在返回的 JSON 中找到所需的信息：

現在在我們的 POST /organizations 端點中使用 requireAuth 中間件。

這保護了我們的 POST /organizations 端點。只有具有有效 Logto 訪問令牌的用戶可以訪問它。

我們現在可以在前端從 Logto 獲取令牌。用戶可以通過此令牌訪問我們的後端服務 API。在添加用戶到組織時，中間件還為我們提供了用戶 ID。

在前端代碼中，宣告此 API 資源在 Logto 配置中。將其標識符添加到資源列表中。

如以前一樣，我們更新 Logto 配置後用戶需重新登入。

在儀表板中，創建組織時獲取 Logto 訪問令牌。使用此令牌訪問我們的後端服務 API。

現在我們可以正確訪問 DocuMind 後端服務 API。

呼叫 Logto 管理 API#

讓我們使用 Logto 管理 API 實現組織創建。

像前端請求後端服務一樣，後端服務請求 Logto 也需要訪問令牌。

在 Logto 中，我們使用機器對機器身份驗證來獲取訪問令牌。請參閱與管理 API 交互。

進入 Logto 控制台的應用程序頁面。創建一個機器對機器應用。分配 "Logto 管理 API 訪問" 角色。複製令牌端點、應用 ID 和應用密鑰。我們將使用這些來獲取訪問令牌。

現在我們可以通過此 M2M 應用獲取 Logto 管理 API 訪問令牌。

使用此訪問令牌來呼叫 Logto 管理 API。

我們將使用這些管理 API：

• POST /api/organizations：創建組織（請參閱：創建組織 API 參考）
• POST /api/organizations/{id}/users：將用戶添加到組織（請參閱：將用戶添加到組織 API 參考）

我們現在已通過 Logto 管理 API 實現了組織創建。我們也可以將用戶添加到組織。

讓我們在儀表板中測試這一功能。

然後點擊 "創建組織"

創建成功！

下一步將是邀請用戶到組織。我們不會在本教程中實施此功能。你已經知道如何使用管理 API。你可以將此租戶創建和邀請作為產品設計參考，並通過這篇博客文章輕鬆實現此功能：我們如何在多租戶應用中實現用戶協作。

為你的多租戶應用添加訪問控制#

現在讓我們看看怎樣統一管理組織訪問控制。

我們想要達成的目標是：

• 用戶只能訪問屬於自己組織的資源：這可以通過 Logto 的 組織令牌 來完成
• 用戶在組織中擁有特定角色（包含不同權限）以執行授權操作：這可以通過 Logto 的組織模板功能來實現

讓我們看看如何實現！

使用 Logto 組織令牌#

類似於我們前面提到的 Logto 訪問令牌，Logto 發行了對應於特定資源的訪問令牌，用戶使用此令牌訪問受保護的後端服務。相應地，Logto 發行對應於特定組織的組織令牌，用戶使用此令牌訪問受保護的組織資源。

在前端應用中，我們可以使用 Logto 的 getOrganizationToken 方法來獲取訪問特定組織的令牌。

這裡，organizationId 是用戶所屬的組織的 id。

在使用 getOrganization 或任何組織相關功能之前，我們需要確保 urn:logto:scope:organizations 範圍和 urn:logto:resource:organization 資源已在 Logto 配置中聲明。由於我們之前已經聲明過，因此這裡不再重複。

在我們的組織頁面中，我們使用組織令牌來獲取組織內的文檔。

在此實現中有兩個重要點需要註意：

1. 如果傳遞給 getOrganizationToken 的 organizationId 不是該用戶的組織的 id，這個方法將無法得到令牌，從而保證用戶只能訪問自己的組織。
2. 當請求組織資源時，我們使用組織令牌而不是訪問令牌，因為對於屬於組織的資源，我們希望使用組織權限控制而非用戶權限控制（你在實施 GET /documents API 時會更好地理解這一點）。

接下來，我們在後端服務中創建一個 GET /documents API。類似於我們之前如何使用 API 資源來保護 POST /organizations API，我們使用特定於組織的資源標識符來保護 GET /documents API。

首先，我們來創建一個 requireOrganizationAccess 中間件來保護組織資源。

然後我們使用 requireOrganizationAccess 中間件來保護 GET /documents API。

這樣，我們已經實現了使用組織令牌來訪問組織資源。在後端服務中，你可以根據組織 id 從數據庫中檢索相應的資源。

有些軟件要求在組織之間進行數據隔離。對於進一步的討論和實現，你可以參考這篇博客文章：使用 PostgreSQL 實現多租戶：通過一個簡單的真實案例學習。

實現組織層級的基於角色的訪問控制設計#

我們已經實現了使用組織令牌來訪問組織資源。接下來，我們將通過 RBAC 實現組織內用戶權限控制。

假設 DocuMind 有兩個角色：管理員和協作者。

管理員可以創建和訪問文檔，而協作者只能訪問文檔。

因此，我們的組織需要具有這兩個角色：管理員和協作者。

管理員擁有 read:documents 和 create:documents 權限，而協作者只有 read:documents 權限。

• 管理員
  • read:documents
  • create:documents
• 協作者
  • read:documents

這就是 Logto 的組織模板功能的用武之地。

組織模板是一個適用於每個組織的訪問控制模型藍圖：它定義了適用於所有組織的角色和權限。

為什麼使用組織模板？

因為可擴展性是 SaaS 產品最重要的要求之一。換句話說，適用於一個客戶的應適用所有客戶。

讓我們轉到 Logto 控制台 > 組織模板 > 組織權限，並創建兩個權限：read:documents 和 create:documents。

然後轉到組織角色選項卡來創建兩個用戶角色：管理員和協作者，並將相應的權限分配給這些角色。

這樣，我們已經為每個組織創建了一個 RBAC 權限模型。

接下來，我們進入我們的組織詳細頁面以分配適當角色給我們的成員。

現在我們的組織用戶有角色了！ 你可以通過 Logto 管理 API 完成這些步驟：

現在我們可以通過檢查用戶權限來實現用戶權限控制。

在我們的代碼中，我們需要讓用戶的組織令牌攜帶權限信息，然後在後端進行這些權限的驗證。

在前端代碼的 Logto 配置中，我們需要宣布用戶在組織中需要請求的權限。讓我們將 read:documents 和 create:documents 權限添加到 scopes。

照例，以用戶身份重新登入以使這些配置生效。

然後在後端的 requireOrganizationAccess 中間件中，我們添加用戶權限的驗證。

然後創建 POST /documents API，並使用具有 requiredScopes 配置的 requireOrganizationAccess 中間件來保護此 API 和之前的 GET /documents API。

這樣，我們就通過檢查用戶權限實現了用戶權限控制。

在前端，你可以通過解碼組織令牌或調用 Logto 的 getOrganizationTokenClaims 方法獲取用戶權限信息。

通過檢查聲明中的範圍來根據用戶權限控制頁面元素。

添加更多多租戶應用功能#

到目前為止，我們已經在多租戶 SaaS 系統中實現了基本的用戶和組織功能！然而，還有一些功能我們尚未涵蓋，例如為每個組織自訂登入頁面品牌，使用特定域電子郵件自動將用戶添加到特定組織，以及集成企業級 SSO 功能。

這些都是開箱即用的功能，關於這些功能的更多信息可以在 Logto 文檔中找到。

總結#

還記得一開始有多壓力嗎？用戶、組織、權限、企業功能...它看起來像是一座無法逾越的山。

但看看我們已經完成的事情：

• 一個完整的身份認證系統，具有多種登入選項和 MFA 支持
• 一個靈活的組織系統，支持多個會員資格
• 組織內基於角色的訪問控制

而且最好的一點？我們不必重新發明輪子。通過利用現代工具如 Logto，我們將可能需要數月的開發工作轉變成了幾個小時內就完成。

本教程的完整源代碼可在此處獲得：Multi-tenant SaaS Sample。

這就是 2025 年現代開發的力量——我們可以專注於構建獨特的產品功能，而不是與基礎設施搏鬥。現在輪到你構建一些令人驚奇的東西了！

探索 Logto 的所有功能，從 Logto Cloud 到 Logto OSS，請訪問 Logto 網站 或在 Logto 雲 上註冊。