跳到主要内容

MFA 受信任设备

MFA 受信任设备允许用户在他们信任的浏览器上跳过重复的 MFA 提示。在合格的 MFA 验证或设置后，用户可以在登录或注册流程结束时，在单独的 信任此设备 页面选择信任该浏览器。Logto 随后会在一方 Cookie 中存储一个有时效的凭证。在后续登录时，有效的凭证可以在无需用户交互的情况下完成 MFA 验证步骤。

受信任设备不是新的 MFA 因子，也不会改变 Logto 何时要求 MFA。它只能满足登录流程中的 MFA 步骤。它无法满足身份验证、近期验证、账户恢复、MFA 因子管理或其他敏感账户操作。

受信任设备的工作原理​

当登录流程进入 MFA 验证步骤时，Logto 会：

  1. 评估现有的 MFA 策略，以决定是否需要 MFA。
  2. 检查租户是否启用了受信任设备，并且用户所属的每个组织 (Organization) 是否允许使用受信任设备。
  3. 针对已识别用户，验证浏览器 Cookie 是否与服务器端的活动记录匹配。
  4. 当凭证有效时自动完成 MFA。否则，Logto 会清除无效凭证，并继续常规的 MFA 流程。

在登录或注册时信任设备​

内置登录体验会在合格的登录或注册流程结束时，在必需的资料完善和 MFA 步骤之后，单独展示 信任此设备 页面。在此页面上信任浏览器是一个明确的选择，与 MFA 验证或设置分开。

仅当租户启用了受信任设备、用户所属的每个组织 (Organization) 允许使用受信任设备，并且当前交互包含合格的 MFA 证明时，页面才会出现：

  • 使用已启用的身份验证器应用 OTP、密钥 (WebAuthn)、邮箱验证码或短信验证码成功完成 MFA 验证。
  • 在 MFA 设置期间成功绑定身份验证器应用或密钥，包括注册期间的设置。

在重置密码期间或交互没有合格的 MFA 证明时，页面不会显示。仅使用备份码验证或已有受信任设备凭证并不符合条件，因此页面不会在每次登录或注册时都显示。之前选择 跳过 也会抑制该页面，详见下文。

在该页面，用户可以选择：

  • 信任此设备 N 天：选择配置的信任时长。Logto 仅在整个交互成功后才创建受信任设备记录和 Cookie 凭证。
  • 跳过：继续而不创建受信任设备。跳过此页面不会跳过任何必需的 MFA 验证或设置。

当用户选择 跳过 时，Logto 会在当前浏览器中为该租户和用户存储一个单独的退出 Cookie。其有效期为跳过时配置的信任时长。在浏览器保留此 Cookie 期间，后续登录不会再次显示该页面。Cookie 过期或被清除后，后续合格流程可以再次显示该页面。退出 Cookie 不授予设备信任，也不能满足 MFA。

跳过后信任设备:

如果用户选择了 跳过，之后又想信任当前浏览器，推荐的方法是通过浏览器的 Cookie 设置或开发者工具删除 Logto 域下对应的退出 Cookie。其名称以 __Host-logto-device-trust-opt-out- 开头。

或者，清除 Logto 域下的所有 Cookie。

完成上述操作后，重新登录，完成合格的 MFA 验证或设置，并在页面出现时选择 信任此设备 N 天。

受信任设备的创建和登录后元数据更新是尽力而为，因此失败不会导致本应成功的认证 (Authentication) 交互失败。

配置受信任设备策略​

全局策略​

进入 控制台 > 多因素认证 (MFA) 并配置 受信任设备：

  • 为租户启用或禁用受信任设备。默认情况下策略是禁用的。
  • 设置 1 到 365 天的整数信任时长。默认值为 30 天。

受信任设备创建时信任时长即被固定。使用该设备不会延长其过期时间，修改时长只影响之后新创建的设备。

禁用全局策略会阻止现有受信任设备满足 MFA，但不会删除它们。如果你再次启用策略，未过期或未被移除的记录可以再次使用。

组织级限制​

组织 (Organization) 可以允许或禁止其成员使用受信任设备。此设置只能收紧租户级策略：

  • 当全局策略被禁用时，组织 (Organization) 不能启用受信任设备。
  • 如果用户所属的任何组织 (Organization) 禁止受信任设备，则该用户的受信任设备凭证无法满足 MFA，无论该组织 (Organization) 是否要求 MFA。
  • 组织 (Organization) 没有单独的信任时长。全局时长适用。

禁止组织 (Organization) 使用受信任设备会暂停受影响成员的使用，但不会删除其记录，也不会阻止用户或管理员列出或移除它们。

复用受信任设备要求浏览器环境为同一 Logto 端点保留并返回持久性一方 Cookie。它代表的是浏览器配置文件，而不是物理设备。

WebView、系统浏览器、自定义标签页、隐私模式、禁用 Cookie 的浏览器及其他临时环境，仅当其 Cookie 存储持久保存凭证时才能使用受信任设备。如果后续登录时 Cookie 不可用，Logto 会继续常规 MFA 流程，而不会导致认证 (Authentication) 失败。不同浏览器、浏览器配置文件、Logto 域、租户和用户之间不会共享受信任设备凭证。

备注:

Logto 不使用浏览器指纹，也不会预先检测客户端是否会持久保存 Cookie。原生应用和自定义登录流程应将受信任设备的创建视为尽力而为，并始终保留常规 MFA 流程。

管理受信任设备​

仅会列出 expiresAt 在未来的活动记录。设备名称取自最新的 User Agent，国家和城市为最新可用请求上下文的近似元数据。原始 IP 地址不会在 UI 或公开 API 中显示或返回。

管理员管理​

在 控制台 > 用户管理 中，打开某个用户以查看和移除其受信任设备。移除受信任设备仅影响后续登录，不会终止用户的活动会话。

你也可以使用 Management API：

  • GET /api/users/{userId}/trusted-devices 列出用户所有活动的受信任设备。
  • DELETE /api/users/{userId}/trusted-devices/{trustedDeviceId} 移除用户拥有的某个受信任设备。

列表响应包含 id、userAgent、country、city、createdAt、lastUsedAt 和 expiresAt。

curl https://[tenant-id].logto.app/api/users/[user-id]/trusted-devices \
  -H "Authorization: Bearer [management-api-access-token]"

curl -X DELETE \
  https://[tenant-id].logto.app/api/users/[user-id]/trusted-devices/[trusted-device-id] \
  -H "Authorization: Bearer [management-api-access-token]"

了解如何通过 Management API 认证 (Authentication)。

账户中心自助管理​

在 控制台 > 登录与账户 > 账户中心，配置 受信任设备 字段：

  • 关闭：用户无法列出或移除受信任设备。
  • 只读：用户可以列出受信任设备，但无法移除。
  • 可编辑：用户可以列出和移除受信任设备。

预置账户中心会在安全页面显示活动的受信任设备，并在当前浏览器的完整 Cookie 凭证有效时标记该浏览器。移除当前浏览器会清除其受信任设备 Cookie，但会保持当前登录会话。移除其他浏览器的记录无法立即清除该浏览器的 Cookie；陈旧 Cookie 会在下次被提交时被拒绝并清除。

对于自定义账户中心，请请求 urn:logto:scope:trusted_devices 权限 (Scope)，并在拥有有效身份验证记录时使用 Account API：

  • GET /api/my-account/trusted-devices 列出已登录用户的活动受信任设备，并为每项添加 isCurrent。
  • DELETE /api/my-account/trusted-devices/{trustedDeviceId} 移除已登录用户拥有的某个受信任设备。删除操作仅对一方应用可用。
curl https://[tenant-id].logto.app/api/my-account/trusted-devices \
  -H "Authorization: Bearer [account-api-access-token]" \
  -H "logto-verification-id: [verification-record-id]"

curl -X DELETE \
  https://[tenant-id].logto.app/api/my-account/trusted-devices/[trusted-device-id] \
  -H "Authorization: Bearer [account-api-access-token]" \
  -H "logto-verification-id: [verification-record-id]"

参见 Account API 参考 和 安全验证指南 了解授权 (Authorization) 和验证流程。

安全模型​

受信任设备凭证是不透明令牌 (Opaque token) 持有者凭证，由两部分组成：记录 ID 和加密随机的 32 字节密钥。

  • 在生产环境中，Logto 将其存储在仅主机可见的 Cookie 中，带有 __Host- 前缀、HttpOnly、Secure、SameSite=Lax 和 Path=/ 属性。应用程序 JavaScript 无法读取。
  • 服务器仅存储密钥的 SHA-256 哈希值，并使用安全的时间比较进行凭证校验。
  • 每次凭证查找都限定在租户和用户范围内，并要求 expiresAt 在未来。
  • 过期时间在创建时固定。机会性清理可在稍后删除过期行，但清理时机绝不会作为安全控制手段。
  • 显式移除会立即删除服务器端记录。被复制或陈旧的 Cookie 在记录被移除后无法通过验证。

凭证密钥和哈希值绝不会通过 UI、公开 API、审计日志或 Webhook 公开。公开的设备 ID 不是物理设备标识符，也不足以用于认证 (Authentication)。由于 Cookie 是持有者凭证，复制完整 Cookie 可以在记录过期或被移除前，为同一租户和用户重放信任；受信任设备不提供硬件级设备认证。

审计日志与 Webhook​

受信任设备相关的审计日志包括：

  • TrustedDevice.Created：在成功交互后创建了受信任设备记录和 Cookie 凭证。
  • TrustedDevice.Used：受信任设备凭证满足了 MFA，且登录成功完成。

你可以订阅以下数据变更 Webhook：

  • TrustedDevice.Created：创建了受信任设备记录。
  • TrustedDevice.Deleted：用户或管理员移除了受信任设备记录。

事件数据包含受信任设备的 id、userId 和 expiresAt。不包含 Cookie 凭证、密钥哈希和请求 IP。为避免事件量过大，成功使用不会触发 Webhook，策略变更也不会触发受信任设备生命周期事件，因为它们不会变更记录。

自然过期不会有 TrustedDevice.Expired Webhook。过期发生在时间流逝时，而不是应用变更操作时，物理清理可能稍后进行。如果你的集成需要推导预期过期时间，请使用 TrustedDevice.Created 的 expiresAt 值。

自然过期也不会生成受信任设备相关的审计日志。

参见 审计日志事件类型 和 Webhook 事件 获取事件目录。

生命周期说明​

  • 正常登出不会移除受信任设备。
  • 添加、移除或重置 MFA 因子不会移除受信任设备。
  • 移除受信任设备不会终止活动会话。
  • 删除用户会通过用户数据生命周期删除其受信任设备记录。
  • 没有受信任设备数量限制或自动驱逐机制。