第三方權杖儲存與 API 存取

第三方權杖集（又稱為聯邦權杖集，federated token set）是一種儲存在 Logto 秘密保管庫中的密鑰類型，用於安全管理由第三方身分提供者 (IdP) 發出的存取權杖 (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 所需的權限範圍 (Scopes)。
在「Setting」頁面啟用 持久 API 存取權杖儲存 (Store tokens for persistent API access) 選項。

企業級 SSO 連接器

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

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

請記得儲存你的變更。

權杖儲存

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

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

檢查權杖儲存狀態

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

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

你也可以透過 Management 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：存取權杖已儲存且有效。
Expired：存取權杖已儲存但已過期。若有重新整理權杖，可用於取得新存取權杖。
Inactive：此連線未儲存存取權杖。可能是使用者尚未透過此連線驗證，或權杖儲存已被刪除。
Not applicable：此連接器不支援權杖儲存。

權杖中繼資料

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

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

權杖擷取

啟用權杖儲存並將權杖安全儲存於 Logto 秘密保管庫後，終端使用者可透過你的用戶端應用程式，整合 Logto Account API 來擷取其第三方存取權杖。

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

資訊:

要擷取第三方存取權杖，必須先於 Console > Sign-in & Account > Account center 為終端使用者啟用 Account API。請參閱如何啟用 Account API 及如何使用 Logto 發出的存取權杖存取 Account API。

權杖輪替

權杖擷取端點回傳：

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

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

權杖儲存刪除

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

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

撤銷權杖

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

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

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

重新驗證與權杖續期

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

備註:

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

使用者呼叫 POST /api/verification/social 端點發起社交驗證請求。可指定自訂權限範圍 (Scopes) 以請求第三方提供者額外權限。
```
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 連接器​

權杖儲存​

檢查權杖儲存狀態​

權杖儲存狀態​

權杖中繼資料​

權杖擷取​

權杖輪替​

權杖儲存刪除​

撤銷權杖​

重新驗證與權杖續期​