# 内置文件认证

EMQX Edge 支持基于内置文件的认证，允许客户端使用简单的用户名和密码组合登录。该方式符合 [MQTT 协议认证规范](https://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html#_Toc398718116)，Broker 可根据客户端在 `CONNECT` 报文中提供的登录凭据进行认证。

## 工作原理

当客户端发送带有用户名和密码的 `CONNECT` 请求时，EMQX Edge 会将凭据与本地认证源进行比对。如果找到匹配的用户名和密码组合，客户端认证成功并允许连接。

这种方式简单、轻量，适用于不需要通过外部认证服务进行认证的场景。

### 认证配置方式

你可以通过以下两种方式之一配置内置认证凭据：

#### 使用独立密码文件

创建本地密码文件，例如 `nanomq_pwd.conf`，格式如下：

```bash
admin: public
client: test123
```

该示例定义了两组用户名/密码：`admin`/`public` 和 `client`/`test123`。

然后，在 EMQX Edge 配置文件 `nanomq.conf` 中使用 `include` 指令引用该密码文件：

```hocon
auth {
  allow_anonymous = false
  password = {include "/etc/nanomq_pwd.conf"}
}
```

该配置会指示 EMQX Edge 从指定密码文件中加载认证凭据。

#### 在配置文件中直接定义凭据

你也可以使用 `auth.passwd` 配置块直接在 `nanomq.conf` 文件中配置凭据：

```hocon
auth {
  allow_anonymous = false
  password = {}

  acl = {}
}

auth.passwd {
  "admin": "public"
  "client": "test123"
}
```

这种方式适用于不需要集中管理密码文件，并希望将认证逻辑保留在同一个配置文件中的环境。

#### 密码要求与安全建议

- 用户名必须是 UTF-8 编码字符串，这是 MQTT 规范的要求。
- EMQX Edge 支持明文密码，同时也提供 **密码加密** 能力以提升安全性。启用加密需要额外工具支持。如需配置协助，请[联系 EMQX](https://www.emqx.com/zh/contact)。
- 如果 `allow_anonymous = false`，则只有具备有效凭据的客户端才能连接，除非授权规则另有放行。

### 通过 Dashboard 配置内置文件认证

1. 在 EMQX Edge Dashboard 中，进入 **Authentication** > **Default**。
2. 点击 **Settings**，并启用 **Enable Default Authentication**。该选项默认关闭。
3. 点击 **Add**，输入用户名和密码。
4. 点击 **Confirm**。

新添加的凭据会显示在列表中。你可以点击 **Actions** 列中的删除图标删除用户。

![img](./assets/authentication-file.png)

### 通过配置文件配置内置文件认证

你可以直接编辑 `nanomq.conf` 文件配置内置文件认证，也可以在 Dashboard 中进入 **Settings** > **All Configurations** 进行配置。有关配置项的完整说明，请参见[基础认证配置示例](../access-control/introduction.md)。