跳至主要內容

API 資源

API 資源，又稱為 資源標示符 (Resource Indicators)，表示要請求的目標服務或資源，通常是一個表示資源身分的 URI 格式變數。這是 Logto 授權系統中的關鍵概念，因為它定義了授權政策所要保護的端點。

資源標示符​

  • 資源值表示正在請求存取的目標服務或資源。
  • 其值 必須 是絕對 URI。
  • URI 不得 包含片段組件。
  • 不應 包含查詢組件。
  • 你 應 提供最具體的 URI，以便完整存取其打算存取的 API 或資源集。

實際操作中，客戶端可能知道要互動的應用程式或資源的基礎 URI。將其用作資源參數的值是合適的。

例如，Logto Management API 的基礎 URI。

https://tenantId.logto.app/api

預設情況下，這個 API 資源已預先註冊到你的 Logto 服務。此 URI 下的所有 Management API 都受到 Logto 的保護。

Logto API 資源架構​

屬性名稱屬性描述必需
API 名稱一個用戶友好的名稱，有助於識別 API 資源。true
API 識別符獨特的 API 資源標示符 (Resource Indicator) 值，具有上述限制。
Logto 將使用它來識別請求的 API 資源並相應地授予授權權杖。true
權杖過期時間 (以秒為單位)為 存取權杖 設定的過期時間。預設過期值為 3600。false
預設 API每個租戶只能設置零個或一個預設 API。
當指定預設 API 時，可以在授權請求中省略資源參數。隨後的權杖交換將默認使用該 API 作為受眾，從而發行 JWT。false
備註:

應限制使用過期的 存取權杖 的請求。這是為了保護你的 API 不被濫用的權杖攻擊。設置的值越大，發行的 存取權杖 存活時間越長，你的 API 就越容易受到攻擊。

預設 API​

備註:

此功能主要針對不支援 OIDC 資源標示符的應用程式，例如 ChatGPT 插件。

Logto 利用 RFC 8707：OAuth 2.0 的資源標示符 實現基於角色的存取控制 (RBAC)。雖然這是 OAuth 2.0 的一個功能，但尚未被廣泛支援。

在 Logto 的實現中，每個使用者定義的權限 (scope) 必須與一個 API 資源相關聯。否則，它將被視為 OpenID Connect（或 OAuth）權限。通常，這不會影響你的授權過程。然而，當與不支援 RFC 8707 的第三方應用程式（例如 ChatGPT 插件）整合時，可能會出現挑戰，因為初始授權請求可能不包含 resource 參數。因此，Logto 將始終發行不透明存取權杖。

為了解決此問題，你可以將一個 API 資源指定為租戶級別的預設資源。一旦完成：

通過指定預設 API 資源，你可以確保與不支援 RFC 8707 的應用程式順利整合，同時維持適當的存取控制。

在 Logto 中註冊 API 資源​

要從 Logto 獲取受眾限制的 存取權杖，首先需要註冊你的後端 API，以啟用 Logto 的受眾限制存取權杖。當收到授權請求時，Logto 將識別已註冊的 API 資源並相應地授予存取權。

要註冊你的 API，請前往 控制台 > API 資源。你將看到一個內建資源，其 API 識別符顯示為 https://[your-tenant-id].logto.app/api。此資源涵蓋了 Logto 的所有 Management API，確保它們受到保護並僅對 Logto 的授權使用者可訪問。

點擊 創建 API 資源 按鈕，並按照互動式表單創建你自己的 API 資源：

  • 一個易於閱讀的 API 名稱，可以更好地幫助你識別此實體。
  • 一個獨特的 API 識別符，以 URI 格式表示。它代表 API 資源的身分。

新創建的 API 將顯示在列表中。你可以在 API 詳情頁面中點擊實體來管理或刪除它。

不透明權杖 vs JWT 何時應使用 JWTs？ API 授權方法