跳到主要内容

MFA 受信任设备

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

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

受信任设备的工作原理​

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

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

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

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

仅当租户启用了受信任设备、用户所属的每个组织都允许使用受信任设备，并且当前交互包含合格的 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，但不会删除它们。如果你再次启用策略，未过期或未被移除的记录可以再次使用。

组织级限制​

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

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

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

复用受信任设备要求浏览器环境为同一 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 权限，并使用最近的 urn:logto:acr:1fa 访问令牌调用 Account API（参见 OIDC 提升认证 (Authentication)）：

  • 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]"

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

参见 Account API 参考 和 提升认证 (Authentication) 了解授权流程。

安全模型​

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

  • 在生产环境中，Logto 将其存储在带有 __Host- 前缀、HttpOnly、Secure、SameSite=Lax 和 Path=/ 属性的主机专用 Cookie 中。应用 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 因素不会移除受信任设备。
  • 移除受信任设备不会终止活跃会话。
  • 删除用户会通过用户数据生命周期删除其受信任设备记录。
  • 没有受信任设备数量限制或自动驱逐机制。