跳到正文

双重身份验证 ​

Pocket Alert 在网页控制台和移动应用中都支持基于 TOTP 的双重身份验证。开启后,仅凭密码将无法登录你的账户。

在 账户 → 安全 中进行设置。

设置方法 ​

  1. 打开 账户 → 安全,开始设置。你会看到一个二维码和一串密钥。
  2. 使用任意 TOTP 验证器扫描,例如 Google Authenticator、1Password、Authy、Bitwarden。
  3. 输入六位数验证码以完成确认。只有输入正确的验证码后,双重身份验证才会真正生效。
  4. 保存显示的恢复码。每个恢复码只能使用一次。

中途中断设置是安全的

开始新的设置不会影响你现有的双重身份验证。新密钥会先放在待定位置,只有在你确认验证码之后才会替换当前生效的密钥,因此即使设置到一半关闭了页面,你也不会被锁在外面。

登录流程的变化 ​

开启双重身份验证后,POST /v1/auth/login 不再返回 JWT,而是返回一个短期有效的挑战令牌:

json
{
  "two_factor_required": true,
  "challenge": "eyJhbGciOiJIUzI1NiIs…"
}

将挑战令牌和验证码一起提交,即可换取真正的令牌:

POST https://api.pocketalert.app/v1/auth/2fa/login
bash
curl -X POST "https://api.pocketalert.app/v1/auth/2fa/login" \
  -H "Content-Type: application/json" \
  -d '{
    "challenge": "eyJhbGciOiJIUzI1NiIs…",
    "code": "482913"
  }'

换取成功后,返回的内容与普通登录相同,包括 token、name、email、avatar。code 字段既可以填写六位数 TOTP 验证码,也可以填写你的某个恢复码。

挑战令牌的有效期为 5 分钟。

API 密钥不受影响 ​

脚本照常运行

双重身份验证只作用于交互式登录。来自 API 密钥 的密钥通过 Token 请求头进行认证,不会触发验证。你的 cron 任务、CI 流水线和监控回调会像以前一样继续发送告警。

这也是为什么值得为每个服务单独划分 API 密钥的权限范围:撤销其中一个,不会影响其他密钥。

恢复码 ​

恢复码只能使用一次,并且以原子方式消耗:两个并发登录无法同时使用同一个恢复码。你可以随时在 账户 → 安全 中生成一组新的恢复码;签发新码后,旧码会失效。

如果验证器和恢复码都丢失了,请联系支持团队。系统不提供自助绕过方式,这正是设计初衷。

暴力破解防护 ​

连续五次验证码错误会将账户锁定 15 分钟,锁定期间的尝试将返回 429。登录成功,或开启/关闭双重身份验证时,计数器会重置。由于挑战令牌在完整的五分钟内都有效,正是这个尝试次数限制,而不是挑战令牌的有效期,使得猜测六位数验证码变得不切实际。

邮件通知 ​

每当你的账户上开启或关闭双重身份验证时,你都会收到一封邮件。如果收到的邮件不是你本人操作的,请立即修改密码。

接口端点 ​

方法端点用途
GET/v1/auth/2fa/status双重身份验证是否已开启,以及剩余多少个恢复码
POST/v1/auth/2fa/setup开始注册流程,返回密钥和二维码数据
POST/v1/auth/2fa/enable确认验证码并启用双重身份验证
POST/v1/auth/2fa/disable关闭双重身份验证,需要验证码和密码
POST/v1/auth/2fa/recovery-codes签发一组新的恢复码
POST/v1/auth/2fa/login用挑战令牌加验证码换取 JWT(无需认证请求头)

除 /auth/2fa/login 外,所有端点都需要已认证的会话。

相关链接 ​

Pocket Alert 文档