> ## Documentation Index
> Fetch the complete documentation index at: https://docs.molesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 多因素认证与 Passkey

> 登录时在密码之外再验证一次：Passkey（iCloud 钥匙串、Google 密码管理器、硬件密钥）和身份验证器 App，免密码登录、恢复码、哪些登录方式要第二步、管理员重置和离线重置。

多因素认证让登录在密码之外再验证一次，只知道密码的人登录不进来。账号有下面任何一种第二因素，就算开启了多因素认证；两种可以同时用。每个账号在 **账号设置 → 安全与登录** 中自己设置，工作区也可以[要求成员开启](https://docs.molesignal.com/zh-Hans/identity/sso.md#登录要求)，这时还没开启的成员在登录时现场开启。

| 第二因素 | 怎么验证 |
| - | - |
| Passkey | 用指纹、面容或设备密码确认。不用输验证码，钓鱼网站也骗不走。可以存在 iCloud 钥匙串、Google 密码管理器、1Password 或硬件密钥里，也能单独用来登录，不输密码。 |
| 身份验证器 App | 输入 App 里的 6 位验证码，例如 Google Authenticator、Microsoft Authenticator 或 1Password。 |

## 先确认是本人

开启身份验证器和添加 Passkey 之前，都要先确认操作的是账号本人。光是已经登录不够：否则拿到会话的人可以给账号加上自己的第二因素，再把本人锁在外面。

| 账号 | 确认方式 |
| - | - |
| 已经有第二因素 | 用已有的 Passkey、身份验证器或一个恢复码。 |
| 还没有第二因素 | 输入账号密码。 |
| 没有密码（由单点登录创建） | 在登录后 10 分钟内操作，不用额外确认。超过 10 分钟要重新登录。 |

## 添加 Passkey

**1. 打开设置**

在 **账号设置 → 安全与登录** 的 **Passkey** 一行点击 **添加 Passkey**，按上面的方式确认是本人。

**2. 创建**

可以起个名字，例如「我的 MacBook」，然后点击 **创建**，按浏览器或系统的提示操作。

**3. 保存恢复码**

这是账号的第一个第二因素时，多因素认证随之开启，并显示 10 个恢复码，只显示这一次。点击 **复制** 或 **下载** 保存，再点击 **我已保存**。

实例能[发送邮件](https://docs.molesignal.com/zh-Hans/configuration.md#告警与邮件)时，账号邮箱会收到通知。第一个 Passkey 还会结束这个账号在其他浏览器和电脑上的登录，当前浏览器保持登录；再添加时不影响别的登录。

Passkey 存在哪里由浏览器和系统决定，提示里可以选：

| 存放位置 | 说明 |
| - | - |
| iCloud 钥匙串 | Apple 设备上的 Safari。同一个 Apple 账户的设备上都能用。 |
| Google 密码管理器 | Chrome 和安卓。同一个 Google 账号的设备上都能用。 |
| 密码管理器 | 1Password、Bitwarden 等。 |
| 硬件密钥 | YubiKey 等 FIDO2 密钥。 |

电脑上没有可用的 Passkey 时，浏览器还可以显示二维码，用手机上的 Passkey 扫码确认。

列表里没起名字的 Passkey 显示它的存放位置；浏览器没有报告存放位置时只显示 Passkey。

### 实例的要求

Passkey 绑定实例的域名，所以有下面这些要求，不满足时 **添加 Passkey** 置灰并说明原因，登录页也不显示 Passkey 入口。

| 要求 | 说明 |
| - | - |
| 配置了 `[http].external_url` | 见[配置](https://docs.molesignal.com/zh-Hans/configuration.md)。 |
| 是域名 | 浏览器不接受 IP 地址。 |
| 是 HTTPS | `localhost` 除外。 |
| 从这个地址打开控制台 | 从别的主机名打开时，浏览器会拒绝使用 Passkey。 |

`external_url` 的主机名改变后，原来的 Passkey 不再可用：要用密码或恢复码登录，再重新添加。

## 开启身份验证器

**1. 打开设置**

在 **账号设置 → 安全与登录** 的 **身份验证器 App** 一行点击 **开启**，按上面的方式确认是本人。

**2. 添加到身份验证器 App**

用身份验证器 App 扫描二维码，或手动输入二维码下方的密钥。App 里显示的名称是 MoleSignal；配置了 `[http].external_url` 时名称里带着它的主机名，方便分清几套实例。

**3. 输入第一个验证码**

输入 App 显示的 6 位验证码，点击 **开启**。验证码对上才会开启。

**4. 保存恢复码**

这是账号的第一个第二因素时，显示 10 个恢复码，只显示这一次。点击 **复制** 或 **下载** 保存，再点击 **我已保存**。

账号原来没有第二因素时，开启后这个账号在其他浏览器和电脑上的登录全部结束，当前浏览器保持登录，账号邮箱收到通知。

## 登录

### 用 Passkey 免密码登录

在登录页点击 **使用 Passkey 继续**；或者点击 **用邮箱登录**，再点击邮箱输入框，从浏览器的建议里选择 Passkey。Passkey 本身要求指纹、面容或设备密码，所以算过了多因素认证，不再要第二步。

### 输错密码太多次

密码输错太多次时，登录页提示要等多久。这时可以用 Passkey 登录，也可以重置密码：Passkey 不计入输错次数，也不受限，账号被别人试密码时本人仍能进来；重置密码成功后立即解开账号。次数和时长见[登录限速](https://docs.molesignal.com/zh-Hans/settings/platform.md#登录限速)。

### 密码之后的第二步

输入密码后，登录页要求 **验证身份**，按账号有的第二因素选择：

| 方式 | 做法 |
| - | - |
| Passkey | 点击 **使用 Passkey 验证**，按浏览器或系统的提示确认。 |
| 身份验证器 App | 输入 6 位验证码，输满即提交。手机与服务器的时钟相差 30 秒以内的验证码都有效，同一个验证码只能用一次。 |
| 恢复码 | 输入一个还没用过的恢复码。每个恢复码只能用一次；用掉后登录页显示还剩几个，账号邮箱也会收到通知。 |

| 情况 | 结果 |
| - | - |
| 一次登录里输错 5 次 | 这次登录作废，要重新输入密码。 |
| 一小时内输错 10 次验证码或恢复码 | 验证码和恢复码锁定一小时，账号邮箱收到通知。Passkey 不受影响，仍可以用来免密码登录。 |
| 输入密码后 5 分钟内没有完成第二步 | 这次登录过期，要重新输入密码。 |

## 哪些登录要第二步

| 登录方式 | 第二步 |
| - | - |
| 账号密码 | 要。 |
| Passkey 免密码登录 | 不要：Passkey 本身就是多因素认证。 |
| LDAP | 要：LDAP 只核对目录里的密码。 |
| OIDC、OAuth 2.0、SAML 单点登录 | 不要：多因素认证由身份提供方负责。 |
| 第一次用单点登录关联已有账号 | 要：确认关联之后再完成第二步，关联才完成，见[关联已有账号](https://docs.molesignal.com/zh-Hans/identity/sso.md#关联已有账号)。 |
| 数据库客户端的账号登录（Flight SQL） | 不能用账号密码连接，改用 `ms_` 开头的 [API Token](https://docs.molesignal.com/zh-Hans/identity/tokens.md)，见[数据库客户端](https://docs.molesignal.com/zh-Hans/query/database-clients.md#鉴权)。 |
| API Token | 不受影响。 |

## 管理恢复码

丢了身份验证器和 Passkey 时，每个恢复码可以代替它们登录一次。**安全与登录** 的 **恢复码** 一行显示还剩几个。点击 **重新生成** 并确认，得到新的 10 个恢复码，原来的全部作废。

## 更改第二因素

下面的操作都要当场用 Passkey、验证码或一个恢复码确认，改名除外。

| 操作 | 做法 |
| - | - |
| 给 Passkey 改名 | 点击它那一行的 **改名**。 |
| 删除 Passkey | 点击 **删除**。iCloud 钥匙串或密码管理器里的副本要到那里删除；支持的浏览器在下次试图用它登录时会提示系统清理。 |
| 更换身份验证器 | 点击 **更换身份验证器**，确认后扫描新的二维码、输入新验证码。恢复码保持不变。 |
| 关闭身份验证器 | 点击 **关闭**。 |

删掉账号最后一种第二因素时，多因素认证随之关闭，恢复码作废，账号邮箱收到通知。账号所在的工作区[要求多因素认证](https://docs.molesignal.com/zh-Hans/identity/sso.md#登录要求)时不能这样做：**关闭** 和 **删除** 置灰，说明是哪个工作区要求的。

## 管理员重置

成员丢了所有第二因素、恢复码也用完时，管理员在 **身份与访问 → 用户** 打开成员的操作菜单，点击 **重置多因素认证**。这需要 `org.members.mfa_reset`。重置后成员的身份验证器、Passkey 和恢复码全部失效，所有设备退出登录，账号邮箱收到通知；成员之后用密码登录，再重新设置；工作区要求多因素认证时，成员在登录时现场开启。

| 成员 | 谁能重置 |
| - | - |
| 只属于本组织 | 本组织的管理员。 |
| 也属于其他组织 | 只有平台管理员：重置会影响成员所在的每个组织。 |
| Root 用户 | 只能在服务器上[离线重置](#离线重置)。 |

**用户** 列表的 **多因素认证** 一列显示每个成员是否已开启。

## 离线重置

Root 用户丢了所有第二因素，或所有管理员都无法登录时，在服务器上运行：

```bash theme={null}
molesignal --config /etc/molesignal/config.toml reset-mfa --email root@example.com
```

命令关闭这个账号的多因素认证，结束它的所有登录，然后退出，不启动服务。

## 登录作废

下列操作会结束账号在其他浏览器和电脑上的登录，在那边的下一个请求时生效：

* 第一次加上第二因素，多因素认证随之开启；
* 更换或关闭身份验证器，删除 Passkey；
* 管理员重置多因素认证；
* **活跃会话** 中的 **退出其他所有设备**；
* 通过邮件链接重置密码，这会结束账号的所有登录。

工作区开启[登录要求](https://docs.molesignal.com/zh-Hans/identity/sso.md#登录要求)后，不满足的会话最迟 15 分钟后结束。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.