跳到主要内容

机器对机器：使用 Logto 认证 (Authentication)

备注:

本指南假设你已经在管理控制台中创建了一个类型为“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 角色：

分配 M2M 角色弹窗

或者，当你已经创建了 M2M 应用程序后，也可以在 M2M 应用详情页分配这些角色：

分配 M2M 角色页面

现在，让我们一起走完整流程。为清晰起见，我们将访问 Logto Management API 和其他 API 资源的步骤分开。并假设你已经在 Logto 中创建了一个 M2M 应用。

获取访问令牌 (Access token)​

关于访问令牌 (Access token) 请求的基础知识​

M2M 应用通过向令牌请求端点发送 POST 请求来获取访问令牌 (Access token)，在 HTTP 请求实体主体中使用 application/x-www-form-urlencoded 格式添加以下参数：

  • grant_type：必须设置为 client_credentials
  • resource：你想要访问的资源
  • scope：访问请求的权限 (Scope)

你还需要在请求头中包含 M2M 应用的凭据，以便令牌请求端点认证 (Authentication) 你的 M2M 应用。

这是通过在请求的 Authorization 头中以 基本认证 (Basic authentication) 形式包含应用的凭据来实现的，其中用户名是 App ID，密码是 App Secret。

你可以在 M2M 应用的详细信息页面找到 App ID 和 App Secret：

App ID and App Secret

一个访问令牌 (Access token) 请求示例如下：

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

请求访问令牌 (Access token)​

备注:

在以下演示中，将 https://your.logto.endpoint 替换为你要访问的 Logto endpoint。对于 Logto Cloud，它将是 https://{your-tenant-id}.logto.app。

Logto 提供了一个内置的 “日志管理 API (Logto Management API)” 资源，它是一个只读资源，具有访问日志管理 API (Logto Management API) 的 all 权限，你可以在你的 API 资源列表中看到它。资源 API 指示器的模式是 https://{your-tenant-id}.logto.app/api ，这将是你在访问令牌请求正文中使用的资源值。

Logto Management API details

在访问日志管理 API (Logto Management API) 之前，确保你的 M2M 应用已被分配了包含此内置 “日志管理 API (Logto Management API)” 资源的 all 权限的 M2M 角色。

信息:

Logto 还为新创建的租户提供了一个预配置的 “日志管理 API (Logto Management API) 访问” M2M 角色，该角色已经分配了日志管理 API (Logto Management API) 资源的所有权限。你可以直接使用它，而无需手动设置权限。这个预配置的角色也可以根据需要进行编辑和删除。

现在，组合我们所有的内容并发送请求：

const logtoEndpoint = 'https://your.logto.endpoint'; // 用你的 Logto 端点替换
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) 用户：当你与日志管理 API (Logto Management API) 交互时，不能使用自定义域名，请使用默认的 Logto 端点 https://{your_tenant_id}.logto.app/oidc/token 来授予访问令牌。

访问令牌 (Access token) 响应​

一个成功的访问响应体如下：

{
  "access_token": "eyJhbG...2g", // 使用此令牌访问 Logto Management API
  "expires_in": 3600, // 令牌过期时间（秒）
  "token_type": "Bearer", // 使用访问令牌时请求的认证类型
  "scope": "all" // Logto Management API 的 scope `all`
}
备注:

Logto 目前不支持 M2M 应用表示用户。访问令牌 (Access token) 负载中的 sub 将是应用 ID。

使用访问令牌 (Access token) 访问资源​

你可能会注意到令牌响应中有一个 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'; // Replace with your Logto endpoint
const accessToken = 'eyJhb...2g'; // Access Token

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

授权 (Authorization)​

如果你保护的是自己的 API 资源（而不是 Logto Management API），你需要在 API 服务中实现授权 (Authorization) 逻辑，以验证访问令牌 (Access token) 并检查 M2M 应用是否有访问该资源所需的权限。

更多详情请参阅 授权 (Authorization) 和 验证访问令牌 (Access tokens)。