跳至主要內容

保護全域 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. 前往 主控台 → API 資源 (API resources)。
  2. 建立新的 API 資源（如 https://api.yourapp.com/org），並定義其權限（Scopes）。

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

設定全域角色 (Roles)​

  1. 前往 主控台 → 角色 (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 流程 完成。

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

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

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

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

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

Client credentials 流程​

針對機器對機器 (M2M) 情境，你可以使用 client credentials 流程取得全域 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)。

選用：處理使用者權限變更​

資訊:

👷 功能開發中。🚧

最佳實踐與安全建議​

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

常見問題​

如果我的用戶端不支援 resource 參數怎麼辦？{what-if-my-client-doesn-t-support-the-resource-parameter}​

請在 Logto 主控台設定預設 API 資源。當權杖請求未指定 resource 參數時，將預設使用此受眾。

為什麼我的 API 回傳 401 Unauthorized？{why-do-i-get-401-unauthorized-from-my-api}​

請檢查以下常見問題：

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

沒有完整用戶端時如何測試？{how-do-i-test-without-a-full-client}​

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

請求權限時可以用 scope 前綴或簡寫嗎？{can-i-use-scope-prefixes-or-shortened-versions}​

不行。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)