跳到主要内容

不透明令牌 (Opaque token)

在认证 (Authentication) 过程中，如果未指定资源，Logto 会签发一个不透明令牌 (Opaque token) 作为访问令牌 (Access token)，而不是 JWT。不透明令牌 (Opaque token) 是一个随机字符串，比 JWT 短得多：

{
  "access_token": "some-random-string", // 不透明令牌 (Opaque token)
  "expires_in": 3600,
  "id_token": "eyJhbGc...aBc", // JWT
  "scope": "openid profile email",
  "token_type": "Bearer"
}

不透明令牌 (Opaque token) 可用于调用 userinfo 端点 和访问需要认证 (Authentication) 的受保护资源。由于它不是 JWT，资源服务器如何验证它呢？

Logto 提供了一个 introspection 端点，可用于验证不透明令牌 (Opaque token)。默认情况下，introspection 端点为 /oidc/token/introspection，并接受 POST 请求。需要以下参数：

  • token：要验证的不透明令牌 (Opaque token)

该端点还需要客户端认证 (Authentication)。你可以使用以下方法之一：

  • HTTP Basic 认证 (Authentication)：使用 Authorization 头，值为 Basic <base64-encoded-credentials>。凭据必须是 client ID 和 client secret 用冒号（:）分隔后进行 base64 编码。
  • HTTP POST 认证 (Authentication)：使用 client_id 和 client_secret 参数：
    • client_id：请求令牌的应用程序的 client ID
    • client_secret：请求令牌的应用程序的 client secret

client ID（应用 ID）和 client secret（应用密钥）可以是 Logto 中任何“传统 Web”或“机器对机器”应用的应用凭据。如果凭据无效，introspection 端点会返回错误。

introspection 端点会返回一个包含令牌声明 (Claims) 的 JSON 对象：

{
  "active": true, // 令牌是否有效
  "sub": "1234567890" // 令牌的主体 (Subject)（用户 ID）
}

如果令牌无效，active 字段将为 false，并且不会返回 sub 字段。

以下是 introspection 请求的一个非规范示例：

curl --location \
  --request POST 'https://[tenant-id].logto.app/oidc/token/introspection' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'token=some-random-string' \
  --data-urlencode 'client_id=1234567890' \
  --data-urlencode 'client_secret=1234567890'

记得将 [tenant-id] 替换为你的租户 ID。

不透明令牌 (Opaque token) 与组织 (Organizations)​

不透明令牌 (Opaque token) 可用于通过 userinfo 端点 获取组织 (Organizations) 成员信息。当你请求 urn:logto:scope:organizations 权限 (Scope) 时，userinfo 端点会返回用户的组织 (Organizations) 相关声明 (Claims)，如 organizations（组织 ID）和 organization_data。

然而，不透明令牌 (Opaque token) 不能用作组织令牌 (Organization token)。组织令牌 (Organization token) 始终以 JWT 格式签发，原因如下：

  1. 组织令牌 (Organization token) 包含需要资源服务器验证的组织 (Organizations) 相关声明 (Claims)（如 organization_id 和权限 (Permissions) 范围）。
  2. JWT 格式允许资源服务器直接验证令牌并提取组织 (Organizations) 上下文，无需额外的 API 调用。

要获取组织令牌 (Organization token)，你需要使用带有组织参数的 刷新令牌流程 (Refresh token flow) 或 客户端凭据流程 (Client credentials flow)。