# 密码策略

API7 企业版从 3.10.10 版本开始支持。

密码策略要求内置用户在设定的天数后修改密码，并禁止重复使用最近用过的密码。该策略默认关闭。

## 适用范围[​](#适用范围 "适用范围的直接链接")

该策略适用于拥有本地密码的内置用户，包括默认的 `admin` 账户。

它不适用于通过 [SSO](https://docs.apiseven.com/api7-gateway/security-and-compliance/sso-dashboard.md) 登录或通过 [SCIM](https://docs.apiseven.com/api7-gateway/security-and-compliance/authenticate/scim.md) 预配的用户。使用 [Token](https://docs.apiseven.com/api7-gateway/reference/obtain-dashboard-token.md) 认证的请求同样不受影响，即使 Token 所有者的密码已过期。

## 配置策略[​](#配置策略 "配置策略的直接链接")

在控制台中启用该策略：

1. 在 API7 控制台中，进入 **组织 > 设置**。
2. 在 **登录选项** 标签页中找到 **密码策略**，然后点击 **启用**。
3. 设置 **密码有效期（天）** 和 **密码历史数量**。表单预填 `90` 天和已保存的历史数量，历史数量默认为 `5`。
4. 点击 **启用**。

策略开启后，卡片会显示这两个值，其操作菜单中提供 **编辑** 和 **禁用**。**禁用** 需要确认，之后密码不再过期，也不再检查重用。历史数量会保留，供下次启用时使用。

也可以通过 Admin API 配置相同的设置，在 `PUT` 请求中发送这两个字段。两个字段都是必需的。向同一路径发送 `GET` 请求可获取当前值。

```
curl -k "https://localhost:7443/api/system_settings/password_policy" -X PUT \

  -H "X-API-KEY: ${API_KEY}" \

  -H "Content-Type: application/json" \

  -d '{

    "password_max_age_days": 90,

    "password_history_count": 5

  }'
```

| 控制台字段           | API 字段                 | 取值                 | 默认值 | 描述                                                                                                                                |
| -------------------- | ------------------------ | -------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| **密码有效期（天）** | `password_max_age_days`  | `0`，或 `1` 到 `365` | `0`    | 密码保持有效的天数。在 API 中，`0` 表示关闭该策略。控制台表单接受 `1` 到 `365`，并通过 **禁用** 关闭该策略。                        |
| **密码历史数量**     | `password_history_count` | `0` 到 `24`          | `5`    | 除当前密码外，用户不能重复使用的历史密码个数。仅在 `password_max_age_days` 大于 `0` 时生效。设为 `0` 时，新密码只需与当前密码不同。 |

警告

密码有效期从密码上次设置的时间开始计算，而不是从启用策略的时间开始计算。如果密码已超过有效期，那么在启用策略或缩短有效期后，它会立即过期。

### 所需权限[​](#所需权限 "所需权限的直接链接")

以下操作作用于 `arn:api7:iam:organization/*` 资源。在权限策略编辑器中，它们显示在 **Password Policy** 资源类型下。

| 操作                       | 允许的行为                                               |
| -------------------------- | -------------------------------------------------------- |
| `iam:GetPasswordPolicy`    | 查看策略。没有此操作权限的用户看不到 **密码策略** 卡片。 |
| `iam:UpdatePasswordPolicy` | 修改策略。                                               |

每次更新都会记录到[审计日志](https://docs.apiseven.com/api7-gateway/security-and-compliance/audit-logs.md)中，事件类型为 `UpdateSystemSettings`。

## 密码过期后[​](#密码过期后 "密码过期后的直接链接")

用户下次登录时，控制台会打开 **修改已过期的密码** 对话框，要求输入旧密码和新密码。如果用户已处于登录状态，其下一次操作或刷新页面时也会打开该对话框。在修改密码之前，用户只能修改密码或退出登录。如果同时要求启用[两步验证](https://docs.apiseven.com/api7-gateway/security-and-compliance/two-factor-authentication.md)且用户尚未启用，则先修改密码。

修改完成后，旧密码失效，该用户的所有会话都会结束。用户随后需要使用新密码重新登录。

如果用户已不记得旧密码，管理员可以[重置其密码](#%E9%87%8D%E7%BD%AE%E5%BF%98%E8%AE%B0%E7%9A%84%E5%AF%86%E7%A0%81)。用户在下次登录时设置新密码。

使用过期密码的 HTTP Basic Auth 请求会被拒绝，返回状态码 `401`，`warning_msg` 的值为 `password expired`。唯一的例外是修改密码的调用 `PUT /api/password`。自动化任务请使用 [Token](https://docs.apiseven.com/api7-gateway/reference/obtain-dashboard-token.md)，避免受密码有效期影响。已启用两步验证的用户同样无法使用 Basic Auth；[要求内置用户启用两步验证](https://docs.apiseven.com/api7-gateway/security-and-compliance/two-factor-authentication.md#%E8%A6%81%E6%B1%82%E5%86%85%E7%BD%AE%E7%94%A8%E6%88%B7%E5%90%AF%E7%94%A8%E4%B8%A4%E6%AD%A5%E9%AA%8C%E8%AF%81)时，所有内置用户都无法使用。

## 密码重用[​](#密码重用 "密码重用的直接链接")

策略开启时，用户修改自己的密码时不能使用当前密码，也不能使用最近 **密码历史数量** 个历史密码。这同样适用于管理员重置密码后用户必须进行的修改。管理员重置其他用户的密码时不做此检查。

即使策略处于关闭状态，API7 网关也会记录被替换的密码，每个用户最多保留 24 个。因此，之后启用策略或调大历史数量时，策略关闭期间或历史数量较小时被替换的密码同样会被检查。升级前被替换的密码不在历史记录中。

## 过期提醒[​](#过期提醒 "过期提醒的直接链接")

从密码过期前 7 天起，控制台会显示一条横幅，其中包含剩余时间和 **修改密码** 链接。剩余时间向下取整，因此在 7 天有效期的策略下，刚修改的密码会显示 `6 天`。

API 客户端可以从 `GET /api/me` 的 `password_expires_at` 字段读取过期时间。该值是 RFC 3339 格式的 UTC 时间戳。如果密码不会过期，或请求不是通过会话或 Basic Auth 认证的，该值为 `null`。

## 升级行为[​](#升级行为 "升级行为的直接链接")

该策略默认关闭，因此仅升级不会改变任何行为。升级前设置的密码从升级时刻开始计算有效期，因此升级后立即启用策略不会让这些密码立刻过期。

## 重置忘记的密码[​](#重置忘记的密码 "重置忘记的密码的直接链接")

拥有 `iam:ResetPassword` 操作权限的用户可以调用 `PUT /api/users/{user_id}/password_reset` 重置其他用户的密码。用户随后在下次登录时设置新密码。此操作不适用于默认的 `admin` 账户。对该账户请使用下面的重置命令。

### 使用重置命令恢复访问[​](#使用重置命令恢复访问 "使用重置命令恢复访问的直接链接")

API7 企业版从 3.10.11 版本开始支持。

重置命令不需要登录，因此当 `admin` 账户忘记密码时，可以用它恢复访问。它适用于任何拥有本地密码的用户，并立即生效：

* 设置一个由字母、数字和符号 `!@#$%^&*-_=+` 组成的 20 位随机密码，并且只输出一次。
* 新密码是一次性密码，用户必须在下次登录时修改。
* 结束该用户的会话，原因为 `the administrator has reset your password`。
* 清除因密码输错而产生的登录锁定。

该命令不会更改用户的[两步验证](https://docs.apiseven.com/api7-gateway/security-and-compliance/two-factor-authentication.md)或 Token。如果用户既忘记了密码又丢失了身份验证器应用，还需要运行[两步验证重置命令](https://docs.apiseven.com/api7-gateway/security-and-compliance/two-factor-authentication.md#%E4%BD%BF%E7%94%A8%E9%87%8D%E7%BD%AE%E5%91%BD%E4%BB%A4%E6%81%A2%E5%A4%8D%E8%AE%BF%E9%97%AE)。因验证码输错而产生的第二因素锁定同样会保留，直到执行该重置或锁定到期。

该命令包含在控制台二进制文件中。它直接连接数据库，因此可以在控制台运行期间执行。请使用 `exec` 在运行中的控制台容器内执行。镜像中没有 shell，因此需要直接调用二进制文件。

在 Helm 和 Kubernetes 上，该命令读取默认配置路径。请根据你的 Release 调整命名空间和 Deployment 名称：

```
kubectl -n api7 exec deploy/api7ee3-dashboard -- \

  /usr/local/api7/api7-ee-dashboard password reset --username admin
```

在 Docker Compose 上，请在 `docker-compose.yaml` 所在目录中运行该命令，并传入 Compose 文件挂载的配置路径。快速安装脚本和离线安装包中的控制台服务名为 `api7-ee-dashboard`，即下面的写法。如果按照[使用 Docker Compose 部署](https://docs.apiseven.com/api7-gateway/install/deploy-with-docker-compose.md)中的手动部署方式安装，服务名则为 `dashboard`：

```
docker compose exec api7-ee-dashboard \

  /usr/local/api7/api7-ee-dashboard password reset --username admin \

  -c /usr/local/api7/conf/conf.yaml
```

运行成功时会输出新密码：

```
password reset for user "admin", sessions expired; the new password must be changed at the next login

new password: Example-Pa55word-001
```

使用该密码登录，然后设置新密码。如果命令执行失败，它会输出原因并以状态码 `1` 退出。例如，通过 SSO 或 SCIM 登录的用户没有本地密码，命令会报告 `user "<username>" has no local password: it signs in through an identity provider`。

警告

该命令不会写入审计日志。请限制可以 `exec` 进入控制台容器的人员。

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

* [查看审计日志](https://docs.apiseven.com/api7-gateway/security-and-compliance/audit-logs.md)，了解谁修改了策略。
* [权限策略操作和资源](https://docs.apiseven.com/api7-gateway/reference/permission-policy-action-and-resource.md)，查看完整的 IAM 操作列表。
* [从控制台获取 Token](https://docs.apiseven.com/api7-gateway/reference/obtain-dashboard-token.md)，用于不依赖密码的自动化任务。
