跳至主要內容

保護組織（非 API）權限

使用組織範本來管理並強制執行 Logto 中的組織層級角色與權限，控制在組織情境下對應用程式內功能與工作流程的存取。

什麼是組織（非 API）權限？​

組織權限（非 API）控制使用者在組織情境下可以執行哪些操作，但不會在 API 層級強制執行。這些權限主要用於管理應用程式功能、UI 元素、工作流程或商業行為，而非後端 API。

常見使用情境包括

  • 邀請或管理組織成員
  • 指派或變更組織角色
  • 管理組織的帳單、設定或管理功能
  • 存取沒有 API 端點的儀表板、分析或內部工具

Logto 允許你透過 OAuth 2.1 與角色型存取控制 (RBAC, Role-based Access Control) 來保護這些組織權限，同時支援多租戶 SaaS 架構。

這些權限透過 組織範本 中定義的組織角色來管理。每個組織都使用相同的範本，確保所有組織擁有一致的權限模型。

在 Logto 中的運作方式​

  • 組織層級 RBAC (Role-based Access Control)： 角色與權限在組織範本中定義。當使用者加入組織時，會被指派一個或多個角色，進而獲得特定權限。
  • 非 API 強制執行： 權限會在你的應用程式 UI、工作流程或後端邏輯中檢查與強制執行，不一定由 API gateway 處理。
  • 與 API 保護分離： 組織（非 API）權限與 API 資源權限是分開的。你可以在進階情境下同時結合兩者。
組織權限 RBAC

實作概覽​

  1. 在 Logto 的組織範本中定義組織權限。
  2. 建立組織角色，將所需權限打包給組織專屬操作。
  3. 在每個組織內指派角色給使用者或用戶端。
  4. 透過重新整理權杖 (refresh token) 或用戶端憑證流程 (client credentials flow) 取得當前組織的組織權杖 (JWT)。
  5. 在應用程式 UI 或後端驗證存取權杖，以強制執行組織權限。

授權流程：驗證與保護組織權限​

下方流程展示用戶端（網頁、行動裝置或後端）如何取得並使用組織權杖來強制執行非 API 權限。

請注意，此流程未詳列所有必要參數或標頭，僅聚焦於主要步驟。繼續閱讀可了解實際運作方式。

使用者驗證 = 瀏覽器 / 應用程式。M2M = 使用用戶端憑證 + 組織情境的後端服務或腳本。

實作步驟​

註冊組織權限​

  1. 前往 控制台 → 組織範本 → 組織權限。
  2. 定義你需要的組織權限（例如：invite:member、manage:billing、view:analytics）。

完整設定步驟請參閱 定義組織權限。

設定組織角色​

  1. 前往 控制台 → 組織範本 → 組織角色。
  2. 建立包含前述組織權限的角色（例如：admin、member、billing）。
  3. 在每個組織內將這些角色指派給使用者或用戶端。

完整設定步驟請參閱 使用組織角色。

取得組織權杖（非 API）​

你的用戶端 / 應用程式應取得組織權杖（非 API）以存取組織權限。Logto 發行的組織權杖為 JSON Web Tokens (JWTs)。你可以透過 重新整理權杖流程 (refresh token flow) 或 用戶端憑證流程 (client credentials flow) 取得。

重新整理權杖流程​

幾乎所有 Logto 官方 SDK 都原生支援透過重新整理權杖流程取得組織權杖。你也可以使用標準 OAuth 2.0 / OIDC 用戶端函式庫實作此流程。

初始化 Logto SDK 時，請將 urn:logto:scope:organizations 及所需組織權限（scopes）加入 scopes 參數。

部分 Logto SDK 已預設提供組織專用 scope，例如 JavaScript SDK 的 UserScope.Organizations。

備註:

檢查 ID 權杖 (ID token) 中的 organizations 宣告 (claim)，即可取得使用者所屬組織 (organization) ID 清單。此宣告會列出使用者所屬的所有組織，方便你在應用程式中列舉或切換組織。

使用 getOrganizationToken 或類似方法（如帶組織 ID 的 getAccessToken）來請求特定組織的組織權杖。

各 SDK 詳細用法請參閱 快速入門。

用戶端憑證流程​

針對機器對機器（M2M）情境，你可以使用用戶端憑證流程取得組織權限的存取權杖。只需對 Logto 的 /oidc/token 端點發送 POST 請求並帶上組織參數，即可使用用戶端 ID 與密鑰請求組織權杖。

請在請求中包含以下主要參數：

  • organization_id：你要取得權杖的組織 ID。
  • scope：你要請求的組織權限（如 invite:member、manage:billing）。

以下為使用用戶端憑證授權型態的權杖請求非正式範例：

POST /oidc/token HTTP/1.1
Host: your.logto.endpoint
Content-Type: application/x-www-form-urlencoded
Authorization: Basic base64(client_id:client_secret)

grant_type=client_credentials
&organization_id=your-organization-id
&scope=invite:member manage:billing

驗證組織權杖​

Logto 發行的組織權杖（JWT）包含宣告（claims），你的應用程式 / UI / 後端可用來強制執行組織層級存取控制。

當你的應用程式收到組織權杖時，應：

  • 驗證權杖簽章（使用 Logto 的 JWKs）。
  • 確認權杖未過期（exp 宣告）。
  • 檢查 iss（簽發者）是否符合你的 Logto 端點。
  • 確認 aud（受眾）是否符合格式化的組織識別碼（如 urn:logto:organization:{organization_id}）。
  • 拆解 scope 宣告（以空格分隔），檢查所需權限。

逐步與語言專屬教學請參閱 如何驗證存取權杖。

最佳實踐與安全建議​

  • 切勿僅依賴 UI 強制執行： 關鍵操作務必在後端驗證權限。
  • 使用受眾限制： 一定要檢查 aud 宣告，確保權杖屬於目標組織。
  • 權限設計以業務為導向： 使用清楚對應實際操作的名稱，每個組織角色僅授予必要權限。
  • 盡可能區分 API 與非 API 權限（但兩者可同時存在於單一角色）。
  • 隨產品演進定期檢視組織範本。

常見問題​

我可以在單一角色中混用組織與非組織權限嗎？​

不行，組織權限（包含組織層級 API 權限）由組織範本定義，無法與全域 API 權限混用。不過，你可以建立同時包含組織權限與組織層級 API 權限的角色。

我應該在哪裡強制執行非 API 權限？​

請同時在 UI（功能開關）與伺服器端邏輯（敏感操作）檢查非 API 權限。

延伸閱讀​

如何驗證存取權杖 自訂權杖宣告

使用情境：打造多租戶 SaaS 應用程式