密码策略与双因素认证

除密码外，还有两项控制可以加强控制台登录的安全性：

• 密码策略要求组织成员定期修改密码，并禁止重复使用最近用过的密码。
• 双因素认证（2FA）在每次密码登录时，额外要求输入身份验证器应用生成的一次性验证码。每个人为自己的账号开启，组织也可以要求所有成员开启。

两者在 AISIX Enterprise 和 AISIX Cloud 中都可用。组织级设置位于 设置 页面的 登录安全 卡片。只有组织 Owner 可以修改，其他成员只能查看。

两项控制都不作用于 Admin Token，因为它不登录控制台。通过组织单点登录登录的成员，由身份提供方自己的策略负责。

密码策略

密码策略包含两项设置：

设置	默认值	说明
密码有效期（天）	0（关闭）	0 表示关闭有效期，否则为 1 到 365 天。密码使用时间超过该天数的成员需要先修改密码才能继续。
不可重复使用的最近密码个数	5	0 到 24。新密码不能与当前密码相同，也不能与之前的这么多个密码相同。0 表示只需与当前密码不同。仅在开启有效期时生效。

以 Owner 身份登录，打开 设置，在 登录安全 卡片中修改取值，然后选择 保存更改。修改会记录在组织的审计日志中。

密码到期后

开启有效期后，密码使用时间超过设定天数的成员，在修改密码之前无法打开该组织。控制台会把他们带到修改密码页面，说明组织的密码策略要求设置新密码；修改完成后，回到原本要打开的页面。Owner 不例外。

在密码到期前的最后 7 天，控制台顶部会显示一条横幅，提示剩余天数，并提供 修改密码 入口。

修改密码会结束该账号在所有设备上的其他会话，旧密码随即失效。

密码的使用时间从最近一次设置密码时算起。对于在控制面升级到支持该策略的版本之前设置的密码，从该账号登录记录最近一次变更时算起。因此，如果组织成员很早以前就设置了密码，开启较短的有效期可能会让他们立即被要求修改密码。

密码复用

成员每次设置新密码时都会做复用检查：包括修改密码页面、忘记密码的重置链接和设置密码链接。与当前密码或最近密码相同的新密码会被拒绝，并提示组织的密码策略不允许重复使用。

无论是否有组织开启了策略，控制面都会为每个账号记住最近最多 24 个密码，因此 Owner 一开启有效期，复用检查就立即生效。在控制面升级到支持该策略的版本之前被替换掉的密码不会被记住。

账号属于多个组织

在 AISIX Cloud 中，一个账号可以属于多个组织，每个组织各自设置策略：

• 有效期按组织分别检查。密码对某个组织来说已过期，仍可打开其他组织。
• 复用检查在该账号所属、且开启了有效期的组织中取最严格的设置，即最大的最近密码个数。未开启有效期的组织不计入。

AISIX Enterprise 只有一个组织，因此其策略作用于整个部署。

不受密码策略影响的情况

• 没有密码的账号，例如通过 SCIM 预配或由单点登录创建的成员，没有需要过期的密码。
• 最近 24 小时内完成过本组织单点登录的会话，在本组织内不检查密码有效期，因为它没有使用密码登录。其他组织的单点登录不算数。
• Admin Token。

双因素认证

双因素认证属于账号，而不属于某个组织：开启一次，即对该账号所属的所有组织生效。它使用基于时间的一次性密码（TOTP），即 Google Authenticator、Microsoft Authenticator、1Password 等身份验证器应用生成的六位验证码，另外提供恢复码，供无法使用应用时使用。

开启双因素认证

1. 在顶栏选择 安全设置。
2. 选择 设置双因素认证。
3. 用身份验证器应用扫描二维码，或在应用中手动输入二维码下方显示的密钥。
4. 输入应用中显示的六位验证码。如果账号有密码，还要输入当前密码。没有密码的账号（例如由单点登录创建的账号）只需输入验证码。
5. 选择 开启。
6. 保存页面显示的 10 个恢复码：复制或下载后妥善保存。恢复码只显示这一次。

开启时所用的会话视为已验证，可以继续操作。

验证码与时间相关，因此运行身份验证器应用的设备需要准确的时钟。每个验证码只能使用一次。

使用双因素认证登录

开启了双因素认证的账号使用密码登录时分两步：

1. 输入邮箱地址和密码。
2. 输入身份验证器应用中的六位验证码，或选择 改用恢复码 并输入一个恢复码。

第二步须在 5 分钟内完成，最多允许输错 5 次。超出后需要从输入密码重新开始登录。

通过单点登录登录时不要求输入验证码，第二因素由身份提供方负责。

恢复码

每个恢复码可以代替应用中的验证码使用一次。安全设置 页面会显示剩余数量。

如需一组新的恢复码，在 安全设置 页面选择 重新生成恢复码，并输入应用中的当前验证码或一个恢复码。页面会显示一次 10 个新恢复码，之前的所有恢复码随即失效。

关闭双因素认证

在 安全设置 页面选择 关闭，并输入应用中的当前验证码或一个恢复码。之后密码登录又只需要密码。如果当前所在的组织要求双因素认证，页面会先提示：关闭后，在重新开启之前无法进入该组织。

错误验证码限制

错误验证码在两个层面受到限制：

• 每次登录或每个会话。 一次登录的第二步最多允许输错 5 次，超出后需要重新登录。在已登录的会话上，例如重新生成恢复码、关闭双因素认证，或为进入某个组织验证当前会话时，连续输错 5 次会使该会话退出登录。
• 每个账号。 账号在其所有登录和会话中累计连续输错 10 次后，15 分钟内不接受任何第二因素，即使是正确的验证码或恢复码也不接受。控制台会显示剩余分钟数。时间到后，计数从零重新开始。

一次正确的验证码或恢复码会把两种计数都清零。

丢失身份验证器应用

先用一个恢复码登录，然后在 安全设置 页面用另一个恢复码关闭双因素认证，再在新设备上重新设置。这需要用掉两个恢复码：一个用于登录，一个用于关闭。

既没有应用也没有任何恢复码时，无法完成密码登录。控制台中没有重置入口，组织 Owner 也无法替你重置：

• 在 AISIX Enterprise 中，请运维人员通过命令行重置。
• 在 AISIX Cloud 中，请联系 API7 支持团队。

为账号重置双因素认证

在 AISIX Enterprise 中，运维人员可以在正在运行的 cp-api 容器内执行 cp-api two-factor reset，重置某个账号的双因素认证。该命令使用容器自身的配置连接数据库。它会删除该账号的身份验证器密钥和恢复码，解除错误验证码锁定，并让该账号退出所有会话。之后用密码登录只需要密码；如果组织要求双因素认证，会引导此人重新设置。

在 Kubernetes 上，假设 chart 以 aisix-cp 为名安装在 aisix 命名空间中：

kubectl --namespace aisix exec deployment/aisix-cp-api -- \
  cp-api two-factor reset --email "user@example.com"

使用 Docker Compose 或离线安装包时，在 aisix-self-hosted 安装包目录中执行。run.sh 把 Compose 项目命名为 aisix-self-hosted；如果启动时自行设置了 COMPOSE_PROJECT_NAME，请改用该名称：

COMPOSE_PROJECT_NAME=aisix-self-hosted docker compose exec api \
  cp-api two-factor reset --email "user@example.com"

邮箱地址匹配时不区分大小写。命令会输出执行结果，并以 0 退出。没有账号使用该地址或无法连接数据库时以 1 退出，参数格式错误时以 2 退出。

AISIX Enterprise 的前提条件

控制面用其 master key 加密每个账号生成验证码所用的密钥，与加密已存储的 Provider Key 是同一个密钥：Helm chart 中为 secrets.masterKey，Docker Compose 和离线安装包中为 AISIX_CLOUD_MASTER_KEY。每个安装都必须设置它：没有它时 cp-api 会拒绝启动。

组织备份不包含双因素认证和记住的历史密码，因为它们属于账号而不属于组织。恢复后，成员需要重新设置双因素认证。要求开启双因素认证 属于组织设置，会随备份恢复。

要求开启双因素认证

Owner 可以在 登录安全 卡片中打开 要求开启双因素认证 并选择 保存更改，让双因素认证成为组织的强制要求。Owner 必须先为自己的账号开启双因素认证，否则无法打开此项。修改会记录在审计日志中。

开启后，成员只能通过已验证第二因素的会话打开该组织：

• 未开启双因素认证的成员仍保留在组织中，但控制台会把他们带到 安全设置 页面，并提示组织要求开启双因素认证。设置完成后，回到原来的页面继续。
• 已开启双因素认证、但当前会话尚未验证的成员，例如通过其他组织的单点登录打开的会话，或在开启双因素认证之前打开的会话，需要输入应用中的验证码或一个恢复码。他们不会被退出登录，验证后回到原来的页面继续。
• 最近 24 小时内完成过本组织单点登录的会话无需验证码即可进入，因为第二因素由身份提供方负责。

没有宽限期，Owner 也不例外。Admin Token 继续有效。成员在要求开启期间关闭双因素认证后，下次打开该组织时会再次被拦下。

成员的双因素认证状态

成员 列表显示每个成员的账号是否开启了双因素认证：已开启双因素认证 或 未开启双因素认证。由于双因素认证属于账号，该状态在账号所属的每个组织中都相同。

成员 API 在每个成员上通过 two_factor_enabled 返回同样的信息。

下一步

使用单点登录（SAML）让成员通过身份提供方登录，使用成员管理组织中的成员。