跳至主要內容

不透明權杖 (Opaque token)

在驗證 (Authentication) 流程中，若未指定資源，Logto 會簽發不透明存取權杖 (Opaque access token)，而非 JWT。不透明權杖是一串隨機字串，長度遠短於 JWT：

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

不透明權杖可用於呼叫 userinfo endpoint 以及存取需要驗證 (Authentication) 的受保護資源。由於它不是 JWT，資源伺服器該如何驗證它的有效性？

Logto 提供 introspection endpoint 來驗證不透明權杖。預設情況下，introspection endpoint 為 /oidc/token/introspection，並接受 POST 請求。需傳遞以下參數：

  • token：要驗證的不透明權杖

此 endpoint 也需要用戶端驗證 (client 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（app ID）與 client secret（app secret）可為 Logto 中任何「傳統網頁」或「機器對機器」應用程式的應用程式憑證。若憑證無效，introspection endpoint 會回傳錯誤。

introspection endpoint 會回傳一個包含權杖宣告 (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] 替換為你的 tenant ID。

不透明權杖與組織 (Organizations)​

不透明權杖可用於透過 userinfo endpoint 取得組織 (Organization) 成員資訊。當你請求 urn:logto:scope:organizations 權限範圍 (Scope) 時，userinfo endpoint 會回傳使用者的組織相關宣告 (Claims)，如 organizations（組織 ID）與 organization_data。

然而，不透明權杖無法作為組織權杖 (Organization token) 使用。組織權杖一律以 JWT 格式簽發，原因如下：

  1. 組織權杖包含組織專屬宣告 (如 organization_id 與權限範圍)，資源伺服器需驗證這些資訊。
  2. JWT 格式允許資源伺服器直接驗證權杖並擷取組織上下文，無需額外 API 呼叫。

若要取得組織權杖，需使用帶有組織參數的 重新整理權杖流程 (Refresh token flow) 或 用戶端憑證流程 (Client credentials flow)。