使用 Logto 管理 API：一步步指南

雖然 Logto 提供了一個基於網頁的控制台讓你管理身份，但使用管理 API 是自動化工作流程或以程式化方式存取 Logto 的強大替代方案。本指南將帶你一步步了解如何在不同場景中使用 Logto 管理 API。

概述#

你可能會注意到，在 Logto 控制台中有一個內建的 API 資源「Logto 管理 API」。它將是本指南中的關鍵角色。

與其他 API 資源相比，目前 Logto 管理 API 不允許終端使用者直接存取，因為它是為機器與機器之間的通訊而設計的，並且功能強大，可以用來管理你的 Logto 帳戶和資源。

以下是一些你可能想使用 Logto 管理 API 的典型場景：

CI/CD

服務通訊

單頁應用程式

渲染 HTML 的 Web 伺服器

架構#

無論是什麼場景，你都可以用兩種模式來存取 Logto 管理 API。

模式 1：直接存取

在此模式中，你的客戶端或服務將直接存取 Logto 管理 API。在 Logto 中，客戶端或服務被稱為「機器對機器」應用程式。

使用後端服務的例子：

模式 2：間接存取

在此模式中，你的客戶端或服務將透過後端服務存取 Logto 管理 API。模式 2 是建立在模式 1 之上，涉及另一個應用程式。新的應用程式可以是一個傳統 Web、原生或單頁應用程式，將存取後端服務。

使用單頁應用程式的例子：

此模式在你想要自訂邏輯來控制對 Logto 管理 API 的存取時很有用。例如，你可能想要為消費者返回所有訂單，並附上每個訂單的賣家資訊。在這種情況下，你可以讓單頁應用程式向後端服務發出請求以獲得訂單，然後在後端服務中使用 Logto 管理 API 獲取賣家的資訊。

存取 Logto 管理 API#

建立機器對機器應用程式#

首先，你需要在 Logto 控制台中建立一個機器對機器應用程式。前往「應用程式」標籤並點擊「建立應用程式」按鈕。然後在「機器對機器」卡片中點擊「開始構建」。

設置機器對機器角色#

為了存取 Logto 管理 API，你需要建立一個具有適當權限的機器對機器角色。在 Logto 控制台中，前往「角色」標籤並點擊「建立角色」按鈕。點擊「顯示更多選項」並在「角色類型」部分中選擇「機器對機器應用程式角色」。

現在你可以在「分配權限」部分看到「Logto 管理 API」顯示。勾選 API 資源的所有權限，然後點擊「建立角色」按鈕。

角色建立後，你可以將其分配給你在前一步中創建的機器對機器應用程式。

獲取訪問令牌#

你可以按照這篇文章中的步驟通過客戶端憑證授予機器對機器應用程式獲取訪問令牌。通過向 Logto 管理 API 的端點發送請求來測試訪問令牌。

現在你已準備好使用模式 1。注意訪問令牌的有效期較短，所以如果你想快取它可能需要定期更新。

添加另一層#

雖然不允許終端使用者存取 Logto 管理 API，你可以添加另一層以利用 Logto 管理 API 的威力，並讓它增強你的服務。

例如，你正在構建一個有著單頁應用程式和後端服務的在線社區。你可能想要有一個功能允許已登入的用戶查看擁有最多追隨者的前 10 名用戶。將創建一個端點 GET /api/top-users：

為了確保該端點僅可被已登入的用戶存取，你可以在 Logto 控制台中創建一個「單頁應用程式」，並向該應用程式中集成 Logto SDK。然後你可以使用 SDK 獲取訪問令牌並向該端點發出請求：

在後端服務中，你可以先從資料庫查詢前 10 名用戶，然後使用 Logto 管理 API 獲取用戶的資訊：

最後，你可以將回應返回給單頁應用程式：

完整的序列圖：

在此流程中，涉及兩種訪問令牌：一種是後端服務存取 Logto 管理 API 的令牌，另一種是單頁應用程式存取後端服務的令牌。

前者是你在上一節中獲取的訪問令牌。而後者是你可以通過 Logto SDK 獲取的令牌。

我在單頁應用程式中的訪問令牌不是 JSON Web Token (JWT)

如果在調用 Logto SDK 的 getAccessToken 方法時沒有指定資源，則訪問令牌將為一個不透明的字串，旨在用於 userinfo 端點。要獲取 JWT：

1. 在 Logto 控制台中定義一個 API 資源，例如 https://api.example.com。
2. 將 API 資源添加到 Logto SDK 的 resources 配置中，例如 resources: ['https://api.example.com']。
3. 使用 API 資源調用 getAccessToken 方法，例如 getAccessToken('https://api.example.com')。

在你的後端服務中驗證 JWT，請參見驗證 API 請求的授權令牌。

單頁應用程式中的 JWT 意味著什麼？

JWT 只意味著用戶已登入並嘗試存取 API 資源。它不意味著用戶擁有該 API 資源的特定權限。是否授予用戶存取該 API 資源的權限由你自行決定。

如果你需要更精細的存取控制，也可以對用戶應用基於角色的存取控制 (RBAC)。詳情請參見🔐 基於角色的存取控制 (RBAC)。

結語#

Logto 管理 API 在多種場景中強大且靈活。藉助標準協議，你可以輕鬆地將 Logto 管理 API 集成到你的應用程式中，並構建安全且可擴展的系統。如果你有任何問題，請隨時與我們聯繫。