# 密码策略与双因素认证

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

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

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

两项控制都不作用于 [Admin Token](https://docs.apiseven.com/ai-gateway/cloud/admin-tokens.md)，因为它不登录控制台。通过组织[单点登录](https://docs.apiseven.com/ai-gateway/cloud/single-sign-on.md)登录的成员，由身份提供方自己的策略负责。

## 密码策略[​](#password-policy "密码策略的直接链接")

密码策略包含两项设置：

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

以所有者身份登录，打开 **设置**，选择 **身份认证** 标签页，在 **登录安全** 卡片中修改取值，然后选择 **保存更改**。修改会记录在组织的[审计日志](https://docs.apiseven.com/ai-gateway/cloud/logging-and-auditing.md#audit-log)中。

### 密码到期后[​](#when-a-password-expires "密码到期后的直接链接")

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

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

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

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

### 密码复用[​](#password-reuse "密码复用的直接链接")

成员每次设置新密码时都会做复用检查：包括修改密码页面、[忘记密码的重置链接](https://docs.apiseven.com/ai-gateway/cloud/members.md#reset-a-forgotten-password)和[设置密码链接](https://docs.apiseven.com/ai-gateway/cloud/members.md#enable-sign-in-or-reset-a-password)。与当前密码或最近密码相同的新密码会被拒绝，并提示组织的密码策略不允许重复使用。

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

### 账号属于多个组织[​](#accounts-in-several-organizations "账号属于多个组织的直接链接")

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

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

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

### 不受密码策略影响的情况[​](#who-the-policy-does-not-affect "不受密码策略影响的情况的直接链接")

* 没有密码的账号，例如通过 [SCIM](https://docs.apiseven.com/ai-gateway/cloud/scim-directory-sync.md) 预配或由单点登录创建的成员，没有需要过期的密码。
* 最近 24 小时内完成过本组织单点登录的会话，在本组织内不检查密码有效期，因为它没有使用密码登录。其他组织的单点登录不算数。
* Admin Token。

## 双因素认证[​](#two-factor-authentication "双因素认证的直接链接")

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

### 开启双因素认证[​](#enable-two-factor-authentication "开启双因素认证的直接链接")

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

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

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

### 使用双因素认证登录[​](#sign-in-with-two-factor-authentication "使用双因素认证登录的直接链接")

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

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

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

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

### 恢复码[​](#recovery-codes "恢复码的直接链接")

每个恢复码可以代替应用中的验证码使用一次。**账号设置** 页面的 **双因素认证** 卡片会显示剩余数量。

如需一组新的恢复码，在 **双因素认证** 卡片中选择 **重新生成恢复码**，并输入应用中的当前验证码或一个恢复码。页面会显示一次 10 个新恢复码，之前的所有恢复码随即失效。

### 关闭双因素认证[​](#disable-two-factor-authentication "关闭双因素认证的直接链接")

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

### 错误验证码限制[​](#wrong-code-limits "错误验证码限制的直接链接")

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

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

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

### 丢失身份验证器应用[​](#if-you-lose-your-authenticator-app "丢失身份�验证器应用的直接链接")

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

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

* 在 AISIX Enterprise 中，请运维人员[通过命令行重置](#reset-two-factor-authentication-for-an-account)。
* 在 AISIX Cloud 中，请联系 API7 支持团队。

### 为账号重置双因素认证[​](#reset-two-factor-authentication-for-an-account "为账号重置双因素认证的直接链接")

在 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 的前提条件[​](#requirements-for-aisix-enterprise "AISIX Enterprise 的前提条件的直接链接")

控制面用主密钥加密每个账号生成验证码所用的密钥。这与加密已存储的服务提供方密钥使用的是同一把主密钥：Helm Chart 中为 `secrets.masterKey`，Docker Compose 和离线安装包中为 `AISIX_CLOUD_MASTER_KEY`。每个安装都必须配置主密钥，否则 `cp-api` 会拒绝启动。

[组织备份](https://docs.apiseven.com/ai-gateway/cloud/organization-backup-and-restore.md)不包含双因素认证和记住的历史密码，因为它们属于账号而不属于组织。恢复后，成员需要重新设置双因素认证。**要求开启双因素认证** 属于组织设置，会随备份恢复。

## 要求开启双因素认证[​](#require-two-factor-authentication "要求开启双因素认证的直接链接")

所有者可以在 **登录安全** 卡片中打开 **要求开启双因素认证** 并选择 **保存更改**，让双因素认证成为组织的强制要求。所有者必须先为自己的账号开启双因素认证，否则无法打开此项。修改会记录在[审计日志](https://docs.apiseven.com/ai-gateway/cloud/logging-and-auditing.md#audit-log)中。

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

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

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

## 成员的双因素认证状态[​](#two-factor-status-of-members "成员的双因素认证状态的直接链接")

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

[成员 API](https://docs.apiseven.com/ai-gateway/cloud/members.md#list-members-with-the-api) 在每个成员上通过 `two_factor_enabled` 返回同样的信息。

## 下一步[​](#next-steps "下一步的直接链接")

使用[单点登录（SAML）](https://docs.apiseven.com/ai-gateway/cloud/single-sign-on.md)让成员通过身份提供方登录，使用[成员](https://docs.apiseven.com/ai-gateway/cloud/members.md)管理组织中的成员。
