第三方權杖儲存與 API 存取

第三方權杖集（又稱聯邦權杖集）是一種儲存在 Logto 秘密保管庫中的秘密類型，用於安全管理由第三方身分提供者簽發的存取權杖 (Access token) 與重新整理權杖 (Refresh token)。當使用者透過社交或企業級單一登入 (SSO) 連接器驗證時，Logto 會將簽發的權杖儲存在保管庫中。這些權杖日後可被取出，代表使用者存取第三方 API，而無需再次驗證。

常見應用場景

這項能力對於現代應用程式（如 AI 代理、SaaS 平台、生產力工具與需代表使用者與第三方服務互動的客戶應用程式）至關重要。以下是一些實際範例：

📅 行事曆管理應用：使用者以 Google 登入後，你的生產力應用可自動同步行事曆事件、建立新會議並發送邀請，無需再次要求驗證。

🤖 AI 助理：AI 代理可存取使用者的 GitHub 儲存庫以分析程式碼、建立 pull request 或管理議題。這一切僅需使用者在登入或帳號連結時一次性授權。

📊 分析儀表板：SaaS 平台可從使用者連結的社群帳號（Facebook、LinkedIn）拉取資料，產生洞察與報告，無需重複登入中斷工作流程。

啟用第三方權杖儲存

此功能適用於支援權杖儲存的社交連接器。第三方權杖可於社交登入、社交帳號連結及為第三方 API 存取續約權杖時儲存。目前支援的連接器包括：GitHub、Google、Facebook、標準 OAuth 2.0 及標準 OIDC。未來將陸續支援更多連接器。

前往 Console > Connectors > Social Connectors。
選擇你要啟用第三方權杖儲存的社交連接器。
依照設定教學配置連接器，包含新增存取特定第三方 API 所需的權限範圍 (scope)。
在「Setting」頁面啟用 Store tokens for persistent API access 選項。

企業級 SSO 連接器

所有 OIDC 企業連接器皆支援權杖儲存。存取權杖與重新整理權杖可於企業級單一登入 (Enterprise SSO) 時儲存。目前支援的連接器包括：Google Workspace、Microsoft Entra ID (OIDC)、Okta 及 OIDC (Enterprise)。

前往 Console > Enterprise SSO。
選擇你要啟用第三方權杖儲存的企業級 SSO 連接器。
依照設定教學配置連接器，包含新增存取特定第三方 API 所需的權限範圍 (scope)。
在「SSO Experience」分頁啟用 Store tokens for persistent API access 選項。

請記得儲存你的變更。

權杖儲存

啟用第三方權杖儲存後，Logto 會在使用者透過社交或企業級 SSO 連接器驗證時，自動儲存由聯邦身分提供者簽發的存取權杖 (Access token) 與重新整理權杖 (Refresh token)。包含：

儲存的權杖會綁定於使用者的社交或企業級 SSO 身分，讓他們日後可取出權杖以存取 API，無需再次驗證。

檢查權杖儲存狀態

你可以在 Logto Console 檢查使用者的第三方權杖儲存狀態：

前往 Console > Users。
點擊你要檢查的使用者，進入該使用者詳細頁。
捲動至 Connections 區塊，這裡會列出所有與該使用者關聯的社交與企業級 SSO 連線。
每個連線條目會顯示權杖狀態標籤，指示該連線是否有儲存權杖。
點擊連線條目可查看更多細節，包括儲存的存取權杖 (Access token) 中繼資料與重新整理權杖 (Refresh token) 是否可用（如有）。

你也可以透過管理 API 檢查使用者第三方身分與權杖儲存狀態：

GET /api/users/{userId}/identities/{target}?includeTokenSecret=true：根據指定連接器 target（如 github、google 等）查詢使用者的社交身分與權杖儲存狀態。
GET /api/users/{userId}/sso-identities/{ssoConnectorId}?includeTokenSecret=true：根據指定 SSO 連接器 ID 查詢使用者的企業級 SSO 身分與權杖儲存狀態。

權杖儲存狀態

Active：存取權杖 (Access token) 已儲存且有效。
Expired：存取權杖已儲存但已過期。若有重新整理權杖 (Refresh token)，可用於取得新存取權杖。
Inactive：此連線未儲存存取權杖。可能是使用者尚未透過此連線驗證，或權杖儲存已被刪除。
Not applicable：此連接器不支援權杖儲存。

權杖中繼資料

為確保資料完整性與安全性，所有權杖在儲存進秘密保管庫前皆會加密。實際權杖值僅授權的終端使用者可存取。開發者僅能取得權杖集的中繼資料，以瞭解儲存狀態而不暴露敏感內容。

createdAt：首次建立連線並將權杖集儲存進秘密保管庫的時間戳記。
updatedAt：權杖集最後一次更新的時間。
- 若無重新整理權杖，該值與 createdAt 相同。
- 若有重新整理權杖，該值反映最近一次存取權杖被刷新時的時間。
hasRefreshToken：是否有重新整理權杖可用。若連接器支援離線存取且授權請求正確配置，Logto 會在身分提供者簽發時同時儲存重新整理權杖與存取權杖。當存取權杖過期且有有效重新整理權杖時，Logto 會在使用者請求存取連接的服務時自動嘗試以重新整理權杖取得新存取權杖。
expiresAt：存取權杖預估過期時間（單位：秒）。根據身分提供者權杖端點回傳的 expires_in 計算。（僅當提供者回傳 expires_in 時才有此欄位。）
scope：存取權杖的權限範圍，表示身分提供者授予的權限。有助於瞭解儲存的存取權杖可執行哪些操作。（僅當提供者回傳 scope 時才有此欄位。）
tokenType：存取權杖型態，通常為 "Bearer"。（僅當提供者回傳 token_type 時才有此欄位。）

權杖擷取

啟用權杖儲存並將權杖安全儲存於 Logto 秘密保管庫後，終端使用者可透過你的客戶端應用程式，結合 Logto 的使用者帳號 API 取得第三方存取權杖。

GET /my-account/identities/:target/access-token：指定連接器 target（如 github、google）取得社交身分的存取權杖。
GET /my-account/sso-identities/:connectorId/access-token：指定連接器 ID 取得企業級 SSO 身分的存取權杖。

資訊:

瞭解如何啟用與存取帳號 API（使用 Logto 簽發的存取權杖）。

權杖輪替

權杖擷取端點回傳：

200 OK：成功取得且存取權杖仍有效。
404 Not Found：使用者未有指定 target 或連接器 ID 的社交或企業級 SSO 身分，或未儲存存取權杖。
401 Unauthorized：存取權杖已過期。

若存取權杖已過期且有重新整理權杖，Logto 會自動嘗試刷新存取權杖並於回應中回傳新權杖。秘密保管庫中的權杖儲存也會同步更新。

權杖儲存刪除

第三方權杖儲存直接綁定於每位使用者的社交或企業級 SSO 連線。這表示在下列情況下，儲存的權杖集會自動刪除：

關聯的社交或企業級 SSO 身分自使用者帳號移除。
使用者帳號自你的租戶中刪除。
社交或企業級 SSO 連接器自你的租戶中刪除。

撤銷權杖

你也可以手動刪除使用者的第三方權杖集以撤銷存取：

透過 Console：前往使用者身分詳細頁，捲動至 Access token 區塊（如有權杖儲存），點擊區塊底部的 Delete tokens 按鈕。
透過管理 API：
- DELETE /api/secret/:id：根據身分詳細頁取得的 ID 刪除指定秘密。

撤銷權杖集後，使用者需再次與第三方提供者驗證，才能取得新存取權杖並再次存取第三方 API。

重新驗證與權杖續期

當儲存的存取權杖已過期，或應用程式需請求額外 API 權限範圍時，終端使用者可重新驗證第三方提供者以取得新存取權杖——無需再次登入 Logto。這可透過 Logto 的 Social Verification API 實現，允許使用者重新啟動聯邦社交授權流程並更新儲存的權杖集。

備註:

重新啟動聯邦授權目前僅限於社交連接器。對於企業級 SSO 連接器，重新驗證與權杖續期需使用者重新啟動完整 Logto 驗證流程，因目前尚不支援登入後直接與企業級 SSO 提供者重新授權。

使用者呼叫 POST /api/verification/social 端點發起社交驗證請求。可指定自訂權限範圍 (scope) 以請求第三方提供者額外權限。
```
curl -X POST https://<your-logto-domain>/api/verification/social \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "<state>",
    "connectorId": "<logto_connectorId>",
    "redirectUri": "<redirect_uri>",
    "scope": "<custom_scope>"
  }'
```
- authorization header：Logto 簽發的使用者存取權杖。
- connectorId：Logto 中的社交連接器 ID。
- redirectUri：驗證後將使用者導回你應用程式的 URI。你需在提供者應用程式設定中註冊此 URI。
- scope：（選填）自訂權限範圍，請求第三方提供者額外權限。未指定則使用連接器預設權限範圍。
Logto 建立新的社交驗證紀錄，並回傳社交驗證 ID 及授權 URL，讓你將使用者導向第三方提供者進行驗證。

回應範例如下：
```
{
  "verificationRecordId": "<social_verification_id>",
  "authorizationUri": "<authorization_url>",
  "expiresAt": "<expiration_time>"
}
```
將使用者導向授權 URL。使用者於第三方提供者驗證並授權。
第三方提供者將使用者導回你的應用程式，並附上授權碼。

處理授權回呼，將授權碼轉發至 Logto 的驗證端點：

curl -X POST https://<your-logto-domain>/api/verification/social/verify \
  -H "Authorization: Bearer <access_token>" \
  -d '{
    "verificationRecordId": "<social_verification_id>",
    "connectorData": {
      "code": "<authorization_code>",
      "state": "<state>",
      "redirectUri": "<redirect_uri>"
    }
  }'

authorization header：Logto 簽發的使用者存取權杖。
verificationRecordId：前一步回傳的社交驗證 ID。
connectorData：授權碼及第三方提供者於回呼時回傳的其他資料。

備註:

請務必驗證 state 參數以防止 CSRF 攻擊。

Logto 驗證授權碼，並向第三方提供者換取新存取權杖與重新整理權杖，然後於回應中回傳社交驗證 ID。
最後，呼叫 PATCH /my-account/identities/:target/access-token 端點並附上社交驗證 ID，更新使用者的權杖儲存：
```
curl -X PATCH https://<your-logto-domain>/my-account/identities/<target>/access-token \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "socialVerificationId": "<social_verification_id>"
  }'
```
- authorization header：Logto 簽發的使用者存取權杖。
- socialVerificationId：前一步回傳的社交驗證紀錄 ID。
這將以新存取權杖與重新整理權杖更新 Logto 秘密保管庫中的使用者權杖集，讓使用者無需再次登入 Logto 即可存取第三方 API。

更新後的存取權杖將會回傳。

常見應用場景​

啟用第三方權杖儲存​

社交連接器​

企業級 SSO 連接器​

權杖儲存​

檢查權杖儲存狀態​

權杖儲存狀態​

權杖中繼資料​

權杖擷取​

權杖輪替​

權杖儲存刪除​

撤銷權杖​

重新驗證與權杖續期​