跳至主要內容

機器對機器：使用 Logto 進行驗證 (Auth)

備註:

本指南假設你已在管理控制台中創建了一個類型為 "Machine-to-machine" 的應用程式。

介紹​

機器對機器（M2M）是一種常見的驗證 (Authentication) 實踐，適用於需要直接與資源通信的應用程式（而非使用者）。通常，使用 M2M 應用程式不需要使用者互動，因此沒有 UI。例如，一個在 Logto 中更新使用者自訂資料的 API 服務，一個提取每日訂單的統計服務等。

由於 Logto 使用基於角色的存取控制 (RBAC) 作為其存取控制策略，因此為 M2M 應用程式分配 M2M 角色是保護需要直接服務通信的 API 的必要措施。

資訊:

要了解我們目前的 RBAC 以及使用者角色與 M2M 角色的區別，請參閱 配置角色 以獲取更多資訊。

在 Logto 中使用機器對機器應用程式有兩個常見的使用案例：

  1. 存取 Logto Management API：在此情況下，你需要為 M2M 應用程式分配包含內建 Logto Management API 的 all 權限的 M2M 角色。
  2. 存取你的 API 資源：在此情況下，你需要為 M2M 應用程式分配包含你的 API 資源權限的 M2M 角色。

在創建 M2M 應用程式的過程中，你將被引導至一個頁面，在此頁面上可以為你的應用程式指派 M2M 角色 (Roles)：

指派 M2M 角色 (Roles) 模態視窗

或者，你也可以在已創建的 M2M 應用程式詳細頁面上指派這些角色：

指派 M2M 角色 (Roles) 頁面

現在，讓我們逐步完成整個過程。為了清晰起見，我們將分開介紹存取 Logto Management API 和其他 API 資源的步驟。我們假設你已經在 Logto 中創建了一個 M2M 應用程式。

獲取存取權杖​

存取權杖請求的基本知識​

M2M 應用程式向權杖端點發出 POST 請求，以 application/x-www-form-urlencoded 格式在 HTTP 請求實體中加入以下參數來獲取存取權杖：

  • grant_type：必須設為 client_credentials
  • resource：你想要存取的資源
  • scope：存取請求的權限範圍

你還需要在請求標頭中包含 M2M 應用程式的憑證，以便權杖端點驗證你的 M2M 應用程式。

這是透過在請求的 Authorization 標頭中以 基本驗證 (Basic authentication) 形式包含應用程式的憑證來實現的，其中用戶名是 App ID，密碼是 App Secret。

你可以在 M2M 應用程式的詳細資訊頁面找到 App ID 和 App Secret：

App ID 和 App Secret

以下是存取權杖請求的範例：

POST /oidc/token HTTP/1.1
Host: your.logto.endpoint
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&resource=https://shopping.api
&scope=read:products write:products

請求存取權杖​

備註:

在以下示範中，將 https://your.logto.endpoint 替換為你目標的 Logto 端點。對於 Logto Cloud，將是 https://{your-tenant-id}.logto.app。

Logto 提供了一個內建的「Logto Management API」資源，這是一個具有 all 權限的唯讀資源，用於存取 Logto Management API，你可以在你的 API 資源列表中看到它。資源 API 標示符的格式為 https://{your-tenant-id}.logto.app/api，這將是你在存取權杖請求主體中使用的資源值。

Logto Management API 詳細資訊

在存取 Logto Management API 之前，確保你的 M2M 應用程式已被分配了包含此內建「Logto Management API」資源的 all 權限的 M2M 角色。

資訊:

Logto 也為新創建的租戶提供了一個預先配置的「Logto Management API 存取」M2M 角色，該角色已經被分配了 Logto Management API 資源的所有權限。你可以直接使用它而無需手動設置權限。此預先配置的角色也可以根據需要進行編輯和刪除。

現在，將我們所有的內容組合起來並發送請求：

const logtoEndpoint = 'https://your.logto.endpoint'; // 用你的 Logto endpoint 替換
const tokenEndpoint = `${logtoEndpoint}/oidc/token`;
const applicationId = 'your-application-id';
const applicationSecret = 'your-application-secret';
const tenantId = 'your-tenant-id';

const fetchAccessToken = async () => {
  return await fetch(tokenEndpoint, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      Authorization: `Basic ${Buffer.from(`${applicationId}:${applicationSecret}`).toString(
        'base64'
      )}`,
    },
    body: new URLSearchParams({
      grant_type: 'client_credentials',
      resource: `https://${tenantId}.logto.app/api`,
      scope: 'all',
    }).toString(),
  });
};
警告:

對於 Logto Cloud 使用者：當你與 Logto Management API 互動時，不能使用自訂域名，請使用預設的 Logto endpoint https://{your_tenant_id}.logto.app/oidc/token 來授予存取權杖。

存取權杖回應​

成功的存取回應內容如下：

{
  "access_token": "eyJhbG...2g", // 使用此權杖存取 Logto Management API
  "expires_in": 3600, // 權杖到期時間（秒）
  "token_type": "Bearer", // 使用存取權杖時的驗證 (Auth) 類型
  "scope": "all" // Logto Management API 的權限範圍 `all`
}
備註:

Logto 目前不支援將 M2M 應用程式表示為使用者。存取權杖 (Access token) 負載中的 sub 將是應用程式 ID。

使用存取權杖存取資源​

你可能會注意到權杖回應中有一個 token_type 欄位，其固定為 Bearer。

因此，當你與 API 資源 (API resource) 伺服器互動時，應將存取權杖 (Access token) 以 Bearer 格式（Bearer YOUR_TOKEN）放在 HTTP 標頭的 Authorization 欄位中。

使用請求的存取權杖 (Access token) 與內建的 Logto Management API 資源 https://[your-tenant-id].logto.app/api 來獲取 Logto 中的所有應用程式：

const logtoEndpoint = 'https://your.logto.endpoint'; // 用你的 Logto endpoint 替換
const accessToken = 'eyJhb...2g'; // 存取權杖 (Access Token)

const fetchLogtoApplications = async () => {
  return await fetch(`${logtoEndpoint}/api/applications`, {
    method: 'GET',
    headers: {
      Authorization: `Bearer ${accessToken}`,
    },
  });
};

驗證 (Authentication)​

如果你保護的是 Logto Management API 以外的 API 資源，請記得為你的資源實施驗證 (Authentication)。詳情請參閱 保護你的 API。