跳到主要内容

第三方令牌存储与 API 访问

Cloud availabilityOSS availability

第三方令牌集（也称为联合令牌集）是一种存储在 Logto 密钥库中的密钥类型，用于安全管理由第三方身份提供商颁发的访问令牌 (Access token) 和刷新令牌 (Refresh token)。当用户通过社交或企业单点登录 (SSO) 连接器进行认证 (Authentication) 时，Logto 会将颁发的令牌存储在密钥库中。这些令牌随后可以被检索，用于代表用户访问第三方 API，无需再次认证 (Authentication)。

常见用例​

此功能对于现代应用程序（如 AI 代理、SaaS 平台、效率工具和需要代表用户与第三方服务交互的客户应用）至关重要。以下是一些实际示例：

📅 日历管理应用：用户使用 Google 登录后，你的效率应用可以自动同步他们的日历事件、创建新会议并发送邀请，无需再次请求用户认证 (Authentication)。

🤖 AI 助手：AI 代理可以访问用户的 GitHub 仓库以分析代码、创建拉取请求或管理问题。所有操作仅需用户在登录或账户绑定时一次性授权。

📊 分析仪表盘：SaaS 平台可以从用户已连接的社交媒体账户（Facebook、LinkedIn）拉取数据，生成洞察和报告，无需频繁登录打断用户工作流。

启用第三方令牌存储​

社交连接器​

该功能适用于支持令牌存储的 社交连接器。第三方令牌可在 社交登录、社交账户绑定 以及 为第三方 API 访问续期令牌时 存储。目前支持的连接器包括：GitHub、Google、Facebook、标准 OAuth 2.0 和 标准 OIDC。更多连接器的支持将逐步推出。

  1. 进入 控制台 > 连接器 > 社交连接器。
  2. 选择你想为其启用第三方令牌存储的社交连接器。
  3. 按照设置教程配置连接器，包括添加访问特定第三方 API 所需的权限 (Scope)。
  4. 在“设置”页面，启用 为持久 API 访问存储令牌 选项。

企业单点登录 (SSO) 连接器​

所有 OIDC 企业连接器 均支持令牌存储。访问令牌 (Access token) 和刷新令牌 (Refresh token) 可在 企业单点登录 (SSO) 过程中存储。目前支持的连接器包括：Google Workspace、Microsoft Entra ID (OIDC)、Okta 和 OIDC (Enterprise)。

  1. 进入 控制台 > 企业单点登录 (SSO)。
  2. 选择你想为其启用第三方令牌存储的企业单点登录 (SSO) 连接器。
  3. 按照设置教程配置连接器，包括添加访问特定第三方 API 所需的权限 (Scope)。
  4. 在“SSO 体验”标签页，启用 为持久 API 访问存储令牌 选项。

请确保保存你的更改。

令牌存储​

启用第三方令牌存储后，每当用户通过社交或企业单点登录 (SSO) 连接器认证 (Authentication) 时，Logto 会自动存储由联合身份提供商颁发的访问令牌 (Access token) 和刷新令牌 (Refresh token)。包括以下场景：

存储的令牌会附加到用户的社交或企业单点登录 (SSO) 身份上，允许用户后续检索令牌以访问 API，无需再次认证 (Authentication)。

检查令牌存储状态​

你可以在 Logto 控制台检查用户的第三方令牌存储状态：

  1. 进入 控制台 > 用户。
  2. 点击你想查看的用户，进入该用户详情页。
  3. 滚动到 连接 区域。此处列出了与用户关联的所有社交和企业单点登录 (SSO) 连接。
  4. 每个连接条目会显示一个令牌状态标签，指示该连接是否已存储令牌。
  5. 点击连接条目可查看更多详情，包括已存储的访问令牌 (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（已过期）：访问令牌 (Access token) 已存储但已过期。如果有刷新令牌 (Refresh token)，可用于获取新的访问令牌 (Access token)。
  • Inactive（未激活）：该连接未存储访问令牌 (Access token)。可能是用户未通过该连接认证 (Authentication) 或令牌存储已被删除。
  • Not applicable（不适用）：该连接器不支持令牌存储。

令牌元数据​

为保证数据完整性和安全性，所有令牌在存储到密钥库前都会被加密。实际令牌值仅对具有适当授权的终端用户可见。开发者只能获取令牌集的元数据，以便了解存储令牌的状态，而不会暴露敏感内容。

  • createdAt：首次建立连接并将令牌集存储到密钥库的时间戳。
  • updatedAt：令牌集最近一次被更新的时间。
    • 如果没有刷新令牌 (Refresh token)，该值与 createdAt 相同。
    • 如果有刷新令牌 (Refresh token)，该值反映最近一次访问令牌 (Access token) 被刷新时的时间。
  • hasRefreshToken：指示是否有刷新令牌 (Refresh token) 可用。 如果连接器支持离线访问且授权请求配置正确，Logto 会在身份提供商颁发刷新令牌 (Refresh token) 时与访问令牌 (Access token) 一起存储。 当访问令牌 (Access token) 过期且存在有效刷新令牌 (Refresh token) 时，Logto 会在用户请求访问已连接提供商时自动尝试使用存储的刷新令牌 (Refresh token) 获取新的访问令牌 (Access token)。
  • expiresAt：访问令牌 (Access token) 的预计过期时间（单位：秒）。 该值基于身份提供商的 token endpoint 返回的 expires_in 计算。（仅当提供商在令牌响应中包含 expires_in 字段时可用。）
  • scope：访问令牌 (Access token) 的权限 (Scope)，指示身份提供商授予的权限。 这有助于了解存储的访问令牌 (Access token) 可执行哪些操作。（仅当提供商在令牌响应中包含 scope 字段时可用。）
  • tokenType：访问令牌 (Access token) 的类型，通常为 "Bearer"。 （仅当提供商在令牌响应中包含 token_type 字段时可用。）

令牌检索​

启用令牌存储并将令牌安全存储在 Logto 密钥库后，终端用户可以通过集成 Logto 的 用户账户 API 从你的客户端应用检索他们的第三方访问令牌 (Access token)。

  • GET /my-account/identities/:target/access-token：通过指定连接器 target（如 github、google）获取社交身份的访问令牌 (Access token)。

  • GET /my-account/sso-identities/:connectorId/access-token：通过指定连接器 ID 获取企业单点登录 (SSO) 身份的访问令牌 (Access token)。

信息:

了解如何使用 Logto 颁发的访问令牌 (Access token) 启用 和 访问 账户 API。

令牌轮换​

令牌检索接口返回：

  • 200 OK：成功检索到访问令牌 (Access token) 且仍然有效。
  • 404 Not Found：用户没有与指定 target 或连接器 ID 关联的社交或企业单点登录 (SSO) 身份，或未存储访问令牌 (Access token)。
  • 401 Unauthorized：访问令牌 (Access token) 已过期。

如果访问令牌 (Access token) 已过期且有刷新令牌 (Refresh token) 可用，Logto 会自动尝试刷新访问令牌 (Access token)，并在响应中返回新的访问令牌 (Access token)。密钥库中的令牌存储也会同步更新为新的访问令牌 (Access token) 及其元数据。

令牌存储删除​

第三方令牌存储直接绑定到每个用户的社交或企业单点登录 (SSO) 连接。这意味着在以下情况下，存储的令牌集会被自动删除：

  • 关联的社交或企业单点登录 (SSO) 身份从用户账户中移除。
  • 用户账户从你的租户中被删除。
  • 社交或企业单点登录 (SSO) 连接器从你的租户中被删除。

撤销令牌​

你也可以手动删除用户的第三方令牌集以撤销访问权限：

  • 通过控制台： 进入用户身份详情页，滚动到 访问令牌 (Access token) 区域（如有令牌存储），点击该区域末尾的 删除令牌 按钮。
  • 通过管理 API：
    • DELETE /api/secret/:id：通过密钥 ID 删除指定密钥，可在用户身份详情中获取该 ID。

撤销令牌集后，用户需重新通过第三方提供商认证 (Authentication) 才能再次获取访问第三方 API 的访问令牌 (Access token)。

重新认证与令牌续期​

在存储的访问令牌 (Access token) 已过期或应用需要请求更多 API 权限 (Scope) 的场景下，终端用户可以通过第三方提供商重新认证 (Authentication) 以获取新的访问令牌 (Access token)——无需再次登录 Logto。 这可以通过 Logto 的 社交验证 API 实现，允许用户重新发起联合社交授权流程并更新其存储的令牌集。

备注:

重新发起联合授权目前仅限于社交连接器。 对于企业单点登录 (SSO) 连接器，重新认证 (Authentication) 和令牌续期需要用户重新发起完整的 Logto 认证 (Authentication) 流程，因为目前登录后不支持直接与企业单点登录 (SSO) 提供商重新授权。

  1. 用户通过调用 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 颁发的用户访问令牌 (Access token)。
    • connectorId：Logto 中的社交连接器 ID。
    • redirectUri：认证 (Authentication) 后将用户跳转回你应用的 URI。你需要在提供商的应用设置中注册该 URI。
    • scope：（可选）自定义权限 (Scope)，用于请求第三方提供商的额外权限。如果未指定，则使用连接器中配置的默认权限 (Scope)。

  2. Logto 创建新的社交验证记录，并返回社交验证 ID 及授权 URL，用于将用户跳转到第三方提供商进行认证 (Authentication)。

    响应示例：

    {
      "verificationRecordId": "<social_verification_id>",
      "authorizationUri": "<authorization_url>",
      "expiresAt": "<expiration_time>"
    }

  3. 跳转用户到授权 URL。用户在第三方提供商处认证 (Authentication) 并授权。

  4. 第三方提供商将用户跳转回你的客户端应用，并携带授权码。

  5. 处理授权回调，将授权码转发到 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 颁发的用户访问令牌 (Access token)。
    • verificationRecordId：上一步返回的社交验证 ID。
    • connectorData：授权码及第三方提供商回调时返回的其他数据。
    备注:

    不要忘记校验 state 参数，以防止 CSRF 攻击。

  6. Logto 验证授权码，并向第三方提供商换取新的访问令牌 (Access token) 和刷新令牌 (Refresh token)，然后在响应中返回社交验证 ID。

  7. 最后，通过调用 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 颁发的用户访问令牌 (Access token)。
    • socialVerificationId：上一步返回的已验证社交验证记录 ID。

    这将用新的访问令牌 (Access token) 和刷新令牌 (Refresh token) 更新 Logto 密钥库中的用户令牌集，使用户无需再次登录 Logto 即可访问第三方 API。

    更新后的访问令牌 (Access token) 会被返回。