跳至主要內容

保護全域 API 資源 (API resources)

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

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

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

常見使用情境包括

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

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

在 Logto 中的運作方式​

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

實作概覽​

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

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

Logto 依據 RFC 8707: Resource Indicators for OAuth 2.0 建模 API 資源。資源標示符 (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 resources。
  2. 建立新的 API 資源（如 https://api.yourapp.com/org），並定義其權限（scopes）。

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

設定全域角色 (Roles)​

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

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

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

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

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

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

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

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

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

Client credentials 流程​

針對機器對機器 (M2M) 情境，你可以使用 client credentials 流程取得全域 API 資源的存取權杖。只需對 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 存取權杖​

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

當你的 API 收到帶有 Logto 簽發存取權杖的請求時，應：

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

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

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

資訊:

👷 功能開發中 🚧

最佳實踐與安全建議​

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

常見問題​

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

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

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

請檢查以下常見問題：

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

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

可使用 個人存取權杖 (Personal access token) 模擬驗證呼叫。這讓你能在未實作完整 OAuth 流程的情況下測試 API 端點。

延伸閱讀​

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

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

 自訂權杖宣告 (Token claims)

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