跳到主要内容

不透明令牌 (Opaque token)

在认证 (Authentication) 过程中，如果未指定资源，Logto 会签发一个不透明访问令牌 (Opaque 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 tokens)。默认情况下，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）
  "acr": "urn:logto:acr:1fa", // 认证保障级别（如已达到）
  "amr": ["pwd"], // 交互中使用的认证方法
  "auth_time": 1787745600 // 用户认证 (Authentication) 的时间（epoch 秒）
}

如果令牌无效，active 字段将为 false，其他声明 (Claims) 会被省略。关于如何验证 acr、amr 和 auth_time，请参见 Step-up 认证 (Authentication)。注意，结构化的 JWT 访问令牌 (Access tokens) 不能在 /oidc/token/introspection 进行 introspect——始终在本地通过你的租户 JWKS 验证 JWT 访问令牌 (Access tokens)。

以下是 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 tokens) 可用于通过 userinfo 端点 获取组织成员信息。当你请求 urn:logto:scope:organizations 权限 (Scope) 时，userinfo 端点会返回用户的组织相关声明 (Claims)，如 organizations（组织 ID）和 organization_data。

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

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

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