保護組織（非 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 資源權限是分開的。你可以根據需求結合兩者以應對進階情境。

實作概覽

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 Token (JWT) 形式發行組織權杖。你可以透過 重新整理權杖流程 (refresh token flow) 或 用戶端憑證流程 (client credentials flow) 取得。

重新整理權杖流程

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

Logto SDK

初始化 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 詳細用法請參閱 快速入門。

OAuth 2.0 / OIDC client library

設定 OAuth 2.0 用戶端或初始化授權碼流程時，請確保包含下列參數：

• resource：設為 urn:logto:resource:organizations，表示你要取得組織權杖。
• scope：包含預設組織 scope（urn:logto:scope:organizations）、offline_access（取得重新整理權杖），以及你需要的組織權限（如 invite:member、manage:billing）。

部分函式庫可能不原生支援 resource 參數，但通常允許你在授權請求中傳遞額外參數。請查閱你的函式庫文件。

以下為授權請求的非正式範例：

GET /oidc/auth?response_type=code
&client_id=your-client-id
&redirect_uri=https://your-app.com/callback
&scope=openid profile offline_access urn:logto:scope:organizations invite:member manage:billing
&resource=urn:logto:resource:organizations
&code_challenge=abc123
&code_challenge_method=S256
&state=xyz
HTTP/1.1
Host: your.logto.endpoint

使用者驗證後，你會收到授權碼。請用此授權碼對 Logto 的 /oidc/token 端點發送 POST 請求。

以下為權杖請求的非正式範例：

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=authorization_code
&code=authorization-code-received
&redirect_uri=https://your-app.com/callback

注意:

目前，Logto 尚未支援直接透過授權碼流程（authorization code flow）取得組織權杖（Organization token）。你需要使用重新整理權杖（Refresh token）流程來獲取組織權杖（Organization token）。

你將收到可用於取得組織權杖的重新整理權杖。

備註:

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

最後，使用重新整理權杖對 Logto 的 /oidc/token 端點發送 POST 請求以取得組織權杖。請記得包含：

• organization_id 參數，設為目標組織 ID。
• （選填）scope 參數，進一步縮限所需權限（如 manage:members view:reports）。

以下為權杖請求的非正式範例：

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=refresh_token
&refresh_token=your-refresh-token
&organization_id=your-organization-id

用戶端憑證流程

針對機器對機器（M2M, Machine-to-Machine）情境，你可以使用用戶端憑證流程取得組織權限的存取權杖。只需對 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 宣告（以空格分隔），檢查所需權限。

各語言詳細步驟請參閱 如何驗證存取權杖。

Optional: Handle user permission change

User permissions can change at any time. Because Logto issues JWTs for RBAC, permission updates only appear in newly issued tokens, and never modify existing JWTs.

Scope subset rule:

An access token can only include scopes that were requested in the original OAuth authorization flow. Even if a user gains new permissions, the token issued later can only contain a subset of the originally requested scopes. To access newly granted scopes that were not part of the initial request, the client must run a new authorization flow.

Downscoped permissions

When a user loses permissions:

• Newly issued tokens immediately reflect the reduced scopes.
• Existing JWTs keep the old scopes until they expire.
• Your API should always validate scopes and rely on short token lifetimes.

If you need faster reactions, implement your own signal that tells clients to refresh their tokens.

Enlarged permissions

For organization tokens, when a user gains permissions, enlarged permissions will show up on the next issuance (refresh or token request). A new token is still required, but no full re-auth is needed unless the new scopes exceed the original request set.

Recommendations

• Validate scopes in your API on every call.
• Keep token expiration short.
• Add optional notifications if you need immediate permission-change propagation.

最佳實踐與安全建議

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

常見問題

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

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

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

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

延伸閱讀

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

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