跳至主要內容

使用 Logto Management API 設定你的應用服務

利用 Logto Management API，你可以在應用程式中打造自訂的 組織 (Organization) 流程。以下是整合 Management API 的基本設定步驟。如果你已經熟悉這些內容，可以直接前往 教學。

熟悉設定後，你可以探索更多 API，根據業務需求調整其餘流程。

建立機器對機器連線​

Logto 採用 機器對機器 (M2M, Machine-to-Machine) 驗證 (Authentication)，安全地將你的後端服務連接至 Logto Management API 端點。 你的後端服務即可透過 Management API 處理與組織 (Organization) 相關的任務，例如 建立組織 (Organization)、新增或移除成員等。

步驟如下：

  1. 在 Logto Console 建立一個機器對機器 (M2M) 應用程式。
M2M app details
  1. 從 Logto 取得 M2M 存取權杖 (Access token)。進一步了解。
  2. 從你的後端服務 呼叫 Logto Management API。例如，列出所有組織 (Organizations)：
curl \
 -X GET https://[tenant_id].logto.app/api/organizations \
 -H "Authorization: Bearer $M2M_ACCESS_TOKEN" \
 -H "Content-Type: application/json"

保護你的應用伺服器​

由於終端使用者可自行執行部分組織 (Organization) 操作，建議在終端使用者與應用伺服器之間加入授權 (Authorization) 層。伺服器應攔截每個請求，驗證使用者的組織權杖 (Organization token) 及所需權限範圍 (Scopes)，僅在通過驗證後，才以伺服器持有的 M2M 憑證呼叫 Management API。

當使用者提交組織權杖 (Organization token) 請求操作（例如建立組織 (Organization)）時，伺服器會先驗證權杖中的權限範圍 (Scopes)。若權杖包含必要的權限範圍（如 org:create），則授權 (Authorize) 請求並透過 M2M 流程呼叫 Logto Management API 建立組織 (Organization)。

若權杖未包含所需權限範圍，則回傳 403 Forbidden，並略過 M2M 邏輯。這可確保未具備適當權限的使用者無法建立組織 (Organization)。

以下是常見的授權 (Authorization) 模式。

使用組織權限 (Organization permissions)​

首先，請確保你已在 前一節 的組織 (Organization) 範本中定義組織權限 (Organization permissions) 與角色 (Roles)。

接著，確認 Logto 設定中已包含 UserScope.Organizations（值：urn:logto:organization）。以 React SDK 為例：

// src/App.js
import { UserScope } from '@logto/react';

const config = {
  endpoint: 'https://<tenant-id>.logto.app/', // 你的 Logto 端點
  appId: '40fmibayagoo00lj26coc', // 你的 app id
  resources: [
    'https://my.company.com/api', // 你的全域 API 資源 (API resource) 識別符
  ],
  scopes: [
    UserScope.Email,
    UserScope.Phone,
    UserScope.CustomData,
    UserScope.Identities,
    UserScope.Organizations, // 請求組織權杖 (Organization token)
  ],
};

這樣當呼叫 getOrganizationToken(organizationId) 時，client SDK 會請求包含指派給使用者之組織權限 (Organization permissions) 的組織權杖 (Organization token)。你的後端服務即可驗證該權杖，並根據這些權限授權 (Authorize) 後續請求。

關於保護組織層級（非 API）權限的詳細說明，請參閱 完整指南。

混合組織層級權限與 API 層級權限​

當你的 API 資源 (API resources) 與權限 (Permissions) 是全域註冊，但角色 (Roles) 則在組織 (Organization) 層級定義時適用（你可以在組織範本中將 API 層級權限指派給組織角色）。

實作方式與前述相同。務必提供組織 ID 並呼叫 getOrganizationToken(organizationId) 以取得組織權杖 (Organization token)；否則，組織權限 (Organization permissions) 不會被包含。

關於保護組織層級 API 權限的詳細說明，請參閱 完整指南。