两步验证
内置控制台用户可以使用两步验证（2FA，也称双因素认证）保护账户，登录时需要输入身份验证器应用生成的动态验证码。管理员还可以要求所有内置用户启用两步验证。该要求默认关闭。
为你的账户启用两步验证
API7 企业版从 3.10.3 版本开始支持。
- 在 API7 控制台中，打开你的用户个人资料。
- 在 两步验证 一项中，点击 启用。
- 使用身份验证器应用扫描二维码，或手动输入密钥。
- 输入生成的验证码，然后点击 验证并启用。
- 妥善保存恢复码，然后点击 完成。
系统会生成 10 个恢复码，且只显示一次。此后每次登录都需要先输入密码，再输入应用中的验证码或恢复码。
HTTP Basic Auth 无法携带第二因素，因此启用两步验证后，你的账户使用 Basic Auth 的请求会被拒绝，返回状态码 401。自动化任务请改用 Token。
要求内置用户启用两步验证
API7 企业版从 3.10.10 版本开始支持。
该要求适用于使用用户名和密码登录的内置用户，包括默认的 admin 账户。SSO 登录不受此要求约束，无论使用 LDAP、OIDC、CAS 还是 SAML。
使用 Token 或网关组 admin key 认证的请求同样不受影响，即使 Token 所有者尚未启用两步验证。
开启前的准备
该要求立即生效，没有宽限期。请按以下顺序做好准备：
- 将使用 HTTP Basic Auth 的脚本和集成迁移到 Token。开启后，所有内置用户的 Basic Auth 都会返回
401，已启用两步验证的用户也一样。 - 为你自己的账户启用两步验证。如果你是尚未启用两步验证的内置用户，开启该要求会失败，返回状态码
409和错误信息enable two-factor authentication for your own account before requiring it。使用你名下的 Token 操作时也是如此。 - 告知内置用户，他们接下来在控制台中要做的第一件事就是启用两步验证。
配置该要求
在控制台中开启该要求：
- 在 API7 控制台中，进入 组织 > 设置。
- 在 登录选项 标签页中找到 强制两步验证，然后打开开关。
- 查看对话框中列出的影响，然后点击 启用。
关闭开关时立即生效，不需要确认。
也可以通过 Admin API 配置相同的设置，发送 PUT 请求即可。向同一路径发送 GET 请求可获取当前值。
curl -k "https://localhost:7443/api/system_settings/two_factor_policy" -X PUT \
-H "X-API-KEY: ${API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"require_two_factor": true
}'
| 字段 | 类型 | 必需 | 默认值 | 描述 |
|---|---|---|---|---|
require_two_factor | Boolean | 是 | false | 是否要求内置用户启用两步验证。 |
所需权限
以下操作作用于 arn:api7:iam:organization/* 资源。在权限策略编辑器中，它们显示在 Two-Factor Policy 资源类型下。
| 操作 | 允许的行为 |
|---|---|
iam:GetTwoFactorPolicy | 查看该设置。没有此操作权限的用户看不到 强制两步验证 卡片。 |
iam:UpdateTwoFactorPolicy | 修改该设置。 |
每次更新都会记录到审计日志中，事件类型为 UpdateSystemSettings。
未启用两步验证的用户会看到什么
未启用两步验证的内置用户只能启用两步验证或退出登录，已经处于登录状态的用户也不例外。控制台会把他们带到一个只提供这两种操作的页面。启用并保存恢复码后，他们可以回到原来的位置继续操作。
如果同时需要修改密码，则先修改密码。用户修改密码后使用新密码登录，然后再启用两步验证。
API 客户端遵循相同的顺序。POST /api/login 仍返回状态码 200 并创建会话，warning_msg 的值为 two factor enrollment required。后续请求返回状态码 401 和相同的 warning_msg，但以下请求除外：
GET /api/mePOST /api/me/2fa/setupPOST /api/me/2fa/enablePOST /api/logout
用户之后如果停用了自己的两步验证，或者管理员重置了其两步验证，也会受到同样的限制，直到重新启用。
验证码的限制
API7 企业版从 3.10.10 版本开始支持。
以下限制始终适用于已启用两步验证的内置用户，与是否开启上述要求无关。这些都是固定值。
输错验证码后锁定
连续输错 5 次验证码后，该用户的第二因素会被锁定 15 分钟。身份验证器应用的验证码和恢复码都计入次数，登录和停用两步验证时的尝试也都计入。
锁定期间，所有验证码都会被拒绝，包括正确的验证码，恢复码也不会被消耗。请求返回状态码 400 和错误信息 too many failed login attempts, this account is temporarily locked; please try again in about N minute(s)。第 5 次输错本身仍然返回 invalid verification code。
输入正确的验证码或锁定到期后，计数归零。要提前解除锁定，请重置该用户的两步验证。
进入锁定状态时，会向审计日志写入一条事件类型为 UserLoginBanned 的记录。密码连续输错导致的封禁也写入相同的事件，记录中不会说明是哪一种情况。
验证码只能使用一次
每个验证码只能使用一次。重复使用身份验证器应用的验证码会计为一次输错，使用同一应用中更早的验证码也一样。恢复码使用后即被移除。
因此，如果你登录后要停用两步验证，请等待应用显示新的验证码。确认新设置时使用的验证码是个例外，可以马上用它登录。
重置两步验证
重置会清除用户的第二因素，以及恢复码和锁定状态。用户随后只需密码即可登录；如果开启了上述要求，用户会回到启用两步验证的流程。
重置其他用户的两步验证
API7 企业版从 3.10.3 版本开始支持。
拥有 iam:ResetTwoFactor 操作权限的用户可以进入 组织 > 用户，为该用户选择 重置两步验证。也可以调用 PUT /api/users/{user_id}/2fa_reset 完成相同的重置。此操作不会结束该用户现有的会话。
此操作不适用于默认的 admin 账户。对该账户请使用下面的恢复命令。
使用重置命令恢复访问
API7 企业版从 3.10.10 版本开始支持。
恢复命令不需要登录，因此当 admin 账户丢失了身份验证器应用和恢复码时，可以用它恢复访问。它会清除指定用户的第二因素，同时结束该用户的会话，并立即生效。
该命令包含在控制台二进制文件中。请使用 exec 在运行中的控制台容器内执行。镜像中没有 shell，因此需要直接调用二进制文件。
在 Helm 和 Kubernetes 上，该命令读取默认配置路径。请根据你的 Release 调整命名空间和 Deployment 名称：
kubectl -n api7 exec deploy/api7ee3-dashboard -- \
/usr/local/api7/api7-ee-dashboard two-factor reset --username admin
在 Docker Compose 上，请在 docker-compose.yaml 所在目录中运行该命令，并传入 Compose 文件挂载的配置路径。快速安装脚本和离线安装包中的控制台服务名为 api7-ee-dashboard，即下面的写法。如果按照使用 Docker Compose 部署中的手动部署方式安装，服务名则为 dashboard：
docker compose exec api7-ee-dashboard \
/usr/local/api7/api7-ee-dashboard two-factor reset --username admin \
-c /usr/local/api7/conf/conf.yaml
运行成功时输出如下：
two-factor authentication reset for user "admin", sessions expired
该命令直接连接数据库，不会写入审计日志。请限制可以 exec 进入控制台容器的人员。
下一步
- 密码策略，要求相同的用户定期修改密码。
- 从控制台获取 Token，用于无法提供第二因素的自动化任务。
- 权限策略操作和资 源，查看完整的 IAM 操作列表。