跳至主要內容

保護全域 API 資源 (API resources)

使用 Logto 的角色型存取控制 (RBAC, Role-based Access Control) 來保護產品層級的 API。指派全域角色 (Roles) 與權限 (Permissions)，以控管所有使用者與用戶端在你的應用程式中的存取權限。

什麼是全域 API 資源 (API resources)？​

全域 API 資源 (API resources) 是指你應用程式中所有使用者皆可存取的端點或服務，無論其所屬組織或租戶。這些通常是對外公開的 API、核心產品服務，或未限定於特定組織的端點。

常見情境包含

  • 供所有使用者共享的公開 API 或端點。
  • 不屬於多租戶架構的微服務。
  • 所有客戶都會用到的核心應用程式 API（如 /api/users、/api/products）。

Logto 允許你結合 OAuth 2.1 與彈性的角色型存取控制來保護這些 API。

在 Logto 中的運作方式​

  • API 資源 (API resources) 與權限 (Permissions) 全域註冊： 你想保護的每個 API 都需以唯一的資源標示符 (Resource indicator, URI) 註冊，並設定一組控制存取的權限範圍 (Scopes)。
  • 存取權由全域角色 (Roles) 控制： 你可以將權限指派給角色，再將角色指派給使用者或用戶端。
  • 與組織層級權限分離： 全域 API 資源 (API resources) 不具組織脈絡。但如有需要，也可與組織角色 (Roles) 搭配，提供額外脈絡。若需保護組織層級 API，請參閱 保護組織層級 API 資源 (API resources)。
全域 API 資源 RBAC

實作概覽​

  1. 註冊你的 API 資源 (API resource) 並在 Logto 中定義其權限。
  2. 定義角色 (Roles)，並賦予存取 API 所需的權限。
  3. 指派角色 (Roles) 給使用者或用戶端。
  4. 使用 OAuth 2.0 授權流程 取得 API 的存取權杖 (Access token)（resource 參數必須與註冊的 API 標識符一致）。
  5. 在你的 API 驗證存取權杖 (Access token)，以強制執行權限。

認識資源標示符 (Resource indicators)​

Logto 依據 RFC 8707: Resource Indicators for OAuth 2.0 建模 API 資源 (API resources)。資源標示符 (Resource indicator) 是唯一標識目標 API 或服務的 URI。

重點說明

  • 資源標示符必須是絕對 URI（如 https://api.example.com）
  • 不可包含 fragment 元件；盡量避免使用查詢字串。
  • 資源標示符可實現受眾限制權杖 (Audience-restricted tokens) 與多 API 架構支援。

範例

  • Management API：https://my-tenant.logto.app/api
  • 自訂全域 API：https://api.yourapp.com

授權流程：驗證 (Authentication) 並保護你的 API​

下列流程適用於互動式使用者驗證（瀏覽器 / 應用程式）與後端機器對機器 (M2M) 情境。

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

使用者驗證 = 瀏覽器 / 應用程式。M2M = 使用 client credentials 的後端服務或腳本。

備註:

resource 參數必須與你在 Logto 註冊的 API 標識符（資源標示符）完全一致。

實作步驟​

註冊你的 API 資源 (API resources)​

  1. 前往 Console → API 資源 (API resources)。
  2. 建立新的 API 資源（如 https://api.yourapp.com/org），並定義其權限範圍 (Scopes)。

完整設定步驟請參閱 定義帶權限的 API 資源 (API resources)。

設定全域角色 (Roles)​

  1. 前往 Console → 角色 (Roles)。
  2. 建立對應 API 權限的角色（如 read:products、write:products）。
  3. 將這些角色指派給需要存取 API 的使用者或用戶端。

完整設定步驟請參閱 使用全域角色 (Roles)。

取得全域 API 資源 (API resources) 的存取權杖 (Access tokens)​

在存取全域 API 資源 (API resources) 前，你的用戶端必須先取得存取權杖 (Access token)。Logto 會針對全域 API 資源 (API resources) 發行 JSON Web Token (JWT) 作為存取權杖。這通常透過 OAuth 2.0 授權碼流程 (authorization code flow)、重新整理權杖流程 (refresh token flow) 或 client credentials flow 完成。

授權碼或重新整理權杖流程​

所有 Logto 官方 SDK 均原生支援使用重新整理權杖流程取得全域 API 資源 (API resources) 的存取權杖 (Access tokens)。你也可以使用標準 OAuth 2.0 / OIDC 用戶端函式庫實作此流程。

初始化 Logto client 時，將資源標示符 (Resource indicator) 加入 resources 參數（陣列），再將所需權限 (Scopes) 加入 scopes 參數。

使用者驗證後，請在請求存取權杖 (Access token) 時，於 resource 參數或同名參數傳入資源標示符（如呼叫 getAccessToken()）。

各 SDK 詳細用法請參閱 快速入門 (Quick starts)。

Client credentials flow​

針對機器對機器 (M2M) 情境，你可以使用 client credentials flow 取得全域 API 資源 (API resources) 的存取權杖 (Access token)。只需向 Logto /oidc/token 端點發送 POST 請求，並使用你的 client ID 與 secret。

請在請求中包含兩個關鍵參數：

  • resource：你要存取的 API 資源標示符 URI（如 https://api.yourapp.com）。
  • scope：你要請求的 API 權限（如 read:products write:products）。

以下為使用 client credentials grant type 的權杖請求非正式範例：

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
&resource=https://api.yourapp.com
&scope=read:products write:products

在你的 API 驗證 JWT 存取權杖 (Access tokens)​

Logto 發行的 JWT 內含宣告 (Claims)，你的 API 可據此執行授權 (Authorization)。

當你的 API 收到帶有 Logto 發行存取權杖 (Access token) 的請求時，應：

  • 驗證權杖簽章（使用 Logto 的 JWKs）。
  • 確認權杖未過期（exp 宣告）。
  • 檢查 iss（簽發者）是否與你的 Logto 端點一致。
  • 確認 aud（受眾）是否與你註冊的 API 資源標識符一致（如 https://api.yourapp.com）。
  • 拆解 scope 宣告（以空格分隔），檢查是否具備所需權限。

各語言詳細教學請參閱 如何驗證存取權杖 (Access tokens)。

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 global API resources, when a user gains permissions, enlarged permissions will NOT show up through refresh. The client must perform a new OAuth authorization flow to obtain a token that includes the new scopes. This can happen silently if the user has an active Logto session.

Recommendations​

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

最佳實踐與安全建議​

  • 權限設計以業務為導向： 使用能對應實際動作的清楚名稱。
  • 縮短權杖有效期： 若權杖外洩可降低風險。
  • 限制授予的權限範圍 (Scopes)： 僅給予權杖實際所需權限。
  • 使用受眾限制 (Audience restriction)： 一定要驗證 aud 宣告，避免權杖被濫用。

常見問題​

如果我的用戶端不支援 resource 參數怎麼辦？​

請在 Logto Console 設定預設 API 資源。當權杖請求未指定 resource 參數時，權杖將預設發給此受眾 (Audience)。

為什麼我的 API 回傳 401 Unauthorized？​

請檢查以下常見問題：

  • 權杖簽章：確認你的後端有正確取得 Logto 的 JWKs
  • 權杖過期：確保權杖尚未過期（exp 宣告）
  • 受眾 (Audience)：確認 aud 宣告與你註冊的 API 資源標示符一致
  • 所需權限：確認權杖的 scope 宣告包含必要權限

沒有完整用戶端要怎麼測試？​

可使用 個人存取權杖 (Personal access token) 模擬驗證呼叫。這讓你無需在用戶端應用程式實作完整 OAuth 流程，也能測試 API 端點。

請求權限時可以用 scope 前綴或簡寫嗎？​

不行。Scope 名稱必須完全符合你在 API 資源 (API resource) 中定義的權限名稱。前綴與簡寫無法作為萬用字元。

範例：

若你的 API 資源 (API resource) 定義了：

  • read:elections
  • write:elections

你必須請求：

scopes: ["read:elections", "write:elections"]

這樣無法運作：

scopes: ["read", "write"]  // ❌ 不符合權限名稱

延伸閱讀​

如何驗證存取權杖 (Access tokens)

RBAC 實務：為你的應用程式實作安全授權 (Authorization)

 自訂權杖宣告 (Token claims)

RFC 8707：資源標示符 (Resource Indicators)