账号锁定¶

账号锁定是一项功能：当用户输入错误密码、OTP 或恢复代码的次数超过允许的最大尝试次数时，会对该用户账号施加临时锁定。

账号锁定的尝试次数在所有已支持的身份验证方式之间共享计数。例如，如果账号锁定的最大尝试次数为 5 次，那么用户输错密码 2 次、又输错恢复代码 3 次后，账号就会被锁定（2+3 累计达到 5 次尝试）。

如何启用账号锁定¶

账号锁定功能默认不启用。要启用它，请在 Authany 管理台中进入身份验证 > 登录方式，然后切换到账号锁定策略标签页，打开"启用账号锁定策略"单选按钮。

启用账号锁定策略后，您可以查看并配置控制账号锁定功能行为的各项策略。

账号锁定策略¶

以下是您可以配置的各项策略，用于控制账号锁定在您的 Authany 项目中如何生效。

1.0 锁定阈值

账号锁定策略的这一部分用于配置：在多长时间限制内，用户可以进行多少次失败的登录尝试，超过后账号将被锁定。

1.1 失败登录尝试次数

失败登录尝试次数的值是用户在账号被锁定之前，最多可以进行的登录失败尝试次数。

1.2 失败尝试重置时间（分钟）

用于指定系统在最后一次失败登录尝试之后，需要经过多长时间才重置失败登录尝试计数器。例如，如果失败登录尝试次数的值为 10，失败尝试重置时间为 1440 分钟，则表示用户在最后一次未触发锁定的失败尝试之后 24 小时（1440 分钟），会重新获得 10 次尝试机会。

2.0 锁定时长

您可以在账号锁定策略的这一部分，配置账号超过锁定阈值后将被锁定的分钟数。

2.1 锁定时长（分钟）

用于确定账号将被锁定多长时间。

2.2 退避系数

该值是一个乘数，每次后续的失败尝试都会用它去乘以锁定时长，从而使锁定时长呈指数级增长。例如，如果退避系数为 2，初始锁定时长为 1 分钟，那么锁定时长会依次增长为 2、4、8 分钟，以此类推，直到达到最大锁定时长。

2.3 最大锁定时长（分钟）

用于设置锁定时长的上限。

3.0 锁定类型

用于确定账号锁定是仅在用户使用同一 IP 地址尝试登录时生效，还是在用户使用任何设备尝试登录时都生效。

4.0 将策略应用于选定的身份验证方式

在这一部分，您可以选择哪些身份验证方式的失败登录尝试会被计入统计。可选项包括：

密码
通过手机/邮箱的无密码登录
身份验证器 App（TOTP）
恢复代码

如何在管理台解锁用户¶

管理员无需等待锁定时长自动结束，即可立即解锁被锁定的用户。在 Authany 管理台中，进入用户，打开受影响的用户，切换到账号状态标签页。在账号锁定部分，您会看到类似"该用户因登录尝试失败次数过多而被锁定。"的提示信息，以及锁定自动失效的时间。点击重置账号锁定即可立即解除锁定。

通过 Admin API 解锁用户¶

您也可以使用 Admin GraphQL API，以编程方式查看用户的锁定状态并解除锁定。这对于自动化客户支持流程或搭建内部工具非常有用。

使用 User 类型上的 accountLockout 字段来检查用户当前是否被锁定：

query {
  node(id: "<ENCODED USER ID>") {
    ... on User {
      id
      accountLockout {
        lockoutType
        isLocked
        lockedUntil
        lockedIPs {
          ipAddress
          lockedUntil
        }
      }
    }
  }
}

响应的结构取决于所配置的锁定类型：

对于 per_user，lockedUntil 是锁定失效的时间（UTC），lockedIPs 为空。
对于 per_user_per_ip，lockedUntil 为 null，lockedIPs 会列出每个当前被锁定的 IP 及其各自的失效时间，按失效时间降序排列。

要立即解锁用户，调用 resetAccountLockout mutation：

mutation {
  resetAccountLockout(input: { userID: "<ENCODED USER ID>" }) {
    user {
      id
      accountLockout {
        isLocked
      }
    }
  }
}

该 mutation 会清除所有参与统计的身份验证方式（密码、TOTP、OOB OTP、恢复代码）的锁定状态。对于 per_user_per_ip 类型的锁定，它会清除该用户在所有 IP 上的锁定。调用成功后，用户可以立即从任意 IP 进行身份验证。如果账号锁定功能未配置或未启用，该 mutation 执行成功但不会产生任何效果。

完整的 Admin API 参考请参阅 API Queries and Mutations。