組織範本 (Organization template)
Logto 中的 組織範本 (organization template) 定義了你 SaaS 產品中每個組織（租戶）都可用的一致「角色 (Roles)」與「權限 (Permissions)」集合。透過集中管理這些定義，你可以強化安全性、實現可擴展的導入流程，並確保所有組織都擁有優異的使用體驗。
如果你不是在開發多租戶應用程式，或不需要組織專屬的角色／權限，可以略過本節。Logto 的全域角色與權限已足夠應用於單租戶或非組織型應用程式。
什麼是組織範本 (Organization template)?
組織範本是一份藍圖，指定每個組織可用的角色與權限。你在 Logto 租戶中建立的每個組織都會自動繼承這份範本，確保所有租戶都擁有一致的授權 (Authorization) 模型。
- 為什麼要使用範本？
- 強制每個組織遵循統一的存取控制政策。
- 簡化新租戶與團隊成員的導入流程。
- 隨著產品成長，讓角色型存取控制 (RBAC, Role-based access control) 的更新與稽核更容易。
核心概念
- 組織角色 (Organization roles)： 指派給組織內使用者或 M2M（機器對機器）客戶端的權限集合。角色定義了「誰可以在組織內做什麼」。
- 組織權限 (Organization permissions)： 可指派給角色的細緻非 API 行為（如 UI 功能、商業邏輯）。
- API 資源 (API resources)： 受權限保護的 API 端點／服務。組織角色可連結 API 資源，以取得組織範圍的 API 存取權。
- 角色－權限對應 (Role-permission mapping)： 範本中的每個組織角色都可對應一個或多個權限。
- 範本傳播 (Template propagation)： 範本的變更會同步更新所有組織可用的角色與權限。
組織角色與權限（包含 API 資源權限）與全域角色及其權限是分開管理的。不過，API 資源及其權限是集中定義，可同時在全域與組織情境中引用。
與全域角色／權限的比較
角色類型比較 (Role type comparison)
| 角色類型 (Role type) | 可擁有 API 資源權限？ | 可擁有組織（非 API）權限？ |
|---|---|---|
| 全域 (Global) | 是 | 否 |
| 組織 (Organization) | 是 | 是 |
權限類型比較 (Permissions type comparison)
| 權限類型 (Permission type) | 定義於 (Defined in) | 可指派給全域角色？ | 可指派給組織角色？ |
|---|---|---|---|
| API 資源 (API resource) | API 資源實體 (API resource entity) | 是 | 是 |
| 組織 (Organization) | 組織範本 (Organization template) | 否 | 是 |
組織範本結構說明 (Anatomy of an organization template)
組織範本由以下部分組成：
- 角色 (Roles)： 例如
Admin、Member、Viewer、Billing - 組織權限 (Organization permissions)： 例如
invite:member、manage:billing、view:analytics - 角色－權限矩陣 (Role-permission matrix)： 每個角色可獲得哪些權限（包含組織權限與 API 資源權限）的對應關係。
視覺化總覽 (Visual overview)
此圖說明組織角色、權限與 API 資源如何在 Logto 組織範本中串連。 (This diagram illustrates how organization roles, permissions, and API resources connect in a Logto organization template.)
每個在 Logto 建立的組織都會擁有這套角色與權限，並可依需求為使用者／客戶端指派角色。
在你的產品中使用組織範本
Logto 的組織範本專為現代多租戶 SaaS 應用設計，適用於：
- 每個組織都應有相同的角色與權限選項，以利導入、協作與管理。
- 你希望避免為每個新組織手動定義角色／權限。
- 一致的 RBAC 對合規、安全與客戶信任至關重要。
- 你需要隨產品變動調整存取控制，且不影響現有組織。
範例應用情境 (Example use cases)
- 提供工作區、團隊或公司（每個為一租戶）的 SaaS 產品。
- 每個組織有細緻管理員／成員／檢視者角色的平台。
- 同時有 API 與非 API 權限的產品。
最佳實踐與版本管理 (Best practices & versioning)
- 以業務為導向設計角色與權限： 使用能對應實際行為的清楚名稱（不僅僅是技術端點）。
- 避免角色／權限氾濫： 從簡單開始，僅在產品真正需要時新增新角色／權限。
- 溝通變更： 若組織內的角色或權限即將變動，請通知使用者／管理員。
- 持續演進範本： 產品成長時，隨時可更新範本，所有組織都會自動取得新角色／權限。
- 版本管理（選用）： 重大變更時，建議為範本加上版本號，並與客戶溝通遷移計畫。
管理你的組織範本
你可以在 Console → 組織範本 (Organization template) 或透過 Logto Management API 管理組織範本。
- 建立角色： 將使用者角色與 M2M 角色加入範本，每個角色對所有組織皆可用。
- 建立權限： 定義 API 資源與非 API（應用內）行為的權限。
- 編輯角色－權限矩陣： 透過 Logto Console 或 Management API 指派權限給角色。
- 更新或刪除角色／權限： 範本變更會自動套用到所有組織。（使用者／客戶端的角色指派不變，僅權限集合會變動。）
管理組織角色與權限的詳細步驟，請參閱 角色型存取控制 (Role-based access control)。
常見問題 (FAQs)
我一定要用組織權限嗎？
不用，組織權限是選用的。你也可以僅用組織範本來定義角色與 API 資源權限。
如果我更改組織範本會怎樣？
角色或權限的變更會立即反映到所有組織。使用者與客戶端的角色指派不變，僅角色所擁有的權限可能會變動。
可以針對每個組織自訂角色或權限嗎？
無法直接自訂。組織範本強制所有租戶遵循一致模型。（你仍可在每個組織內為不同使用者／客戶端指派不同角色。）
如何回滾或遷移變更？
手動更新範本以還原先前的角色／權限。若為複雜遷移，建議採用版本管理策略。
如果我刪除角色或權限會怎樣？
擁有該角色的使用者／客戶端將失去與其綁定的權限。刪除權限會從所有擁有該權限的角色中移除。