跳至主要內容

不透明權杖 (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
  "acr": "urn:logto:acr:1fa", // 驗證保證等級 (authentication assurance level)，若已達成
  "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 存取權杖。

以下為 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。

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

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

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

  1. 組織權杖包含需由資源伺服器驗證的組織專屬宣告 (claims)（如 organization_id 與權限）。
  2. JWT 格式讓資源伺服器能直接驗證權杖並擷取組織上下文，無需額外 API 呼叫。

若要取得組織權杖，需使用 重新整理權杖流程 (refresh token flow) 或 client credentials flow 並帶入組織參數。