# 通过 HTTP 查询进行授权

HTTP 授权方式将访问控制决策委托给外部 HTTP 服务。当客户端尝试发布或订阅时，EMQX Edge 会向配置的 URL 发送 HTTP 请求。如果服务器返回 HTTP 200，则允许该操作；否则拒绝该操作。

这种方式支持动态、细粒度的访问控制，并且无需重启 EMQX Edge。

## 工作原理

EMQX Edge 会针对每次发布或订阅尝试发送 HTTP 请求，请求使用你配置的方法、URL、请求头和参数。授权服务器评估请求后，返回 200 响应表示允许操作，返回其他状态码表示拒绝操作。

**示例：** 客户端 ID 为 `sensor-01`、用户名为 `sensor-user` 的客户端尝试向主题 `home/temp` 发布消息。使用以下参数配置：

| Key | Value |
|---|---|
| `clientid` | `%c` |
| `username` | `%u` |
| `topic` | `%t` |
| `access` | `%A` |

EMQX Edge 会填充占位符并发送以下请求：

```bash
POST http://127.0.0.1:8991/mqtt/acl
Content-Type: application/x-www-form-urlencoded

clientid=sensor-01&username=sensor-user&topic=home%2Ftemp&access=2
```

授权服务器检查规则后，返回 `HTTP 200` 表示允许发布，返回其他状态码则表示拒绝。

### ACL Cache TTL

为减少发送到授权服务器的 HTTP 请求数，EMQX Edge 支持缓存授权结果。当 **ACL Cache TTL** 设置为非零值时，授权请求结果会在指定时间内缓存。在该时间窗口内，如果后续请求使用相同参数，会立即返回缓存结果，而不会再次向服务器发送 HTTP 请求。

例如，将 ACL Cache TTL 设置为 `30s` 后，某个客户端的订阅或发布请求一旦通过授权，相同操作可在 30 秒内直接放行，无需重新查询服务器。

要配置 ACL Cache TTL，请在 Authorization 页面 **Extended** 标签页中点击 **Settings** 按钮。

将该值设置为 `0`（默认值）会禁用缓存，此时每次授权判断都会触发新的 HTTP 请求。

## 通过 Dashboard 配置

1. 在 EMQX Edge Dashboard 中，进入 **Authorization** > **Extended**。
2. 使用 **Enable** 列中的开关启用 **HTTP** 或 **HTTP Super User**。
3. 点击 **Actions** 列中的编辑图标，打开配置表单。
4. 填写 **Method**、**URL**、**Headers** 和 **Parameters** 字段。
5. 点击 **Save**。

### HTTP 授权

配置该项用于对发布和订阅操作进行授权：

![HTTP authorization configuration](./assets/authorization-http.png)

### HTTP Super User

配置该项可通过 HTTP 授予超级用户权限。超级用户会绕过主题级 ACL 检查。

![HTTP Super User configuration](./assets/authorization-http-superuser.png)

## 配置参考

### Method

HTTP 请求方法。可选值：`POST` 或 `GET`。默认值：`POST`。

### URL

授权服务器端点的 URL。例如：`http://127.0.0.1:8991/mqtt/acl`。

### Headers

每次授权请求中包含的 HTTP 请求头。

| Key | Description |
|---|---|
| `content-type` | 请求体的媒体类型。可使用 `application/x-www-form-urlencoded` 或 `application/json`。 |
| `accept` | 可选。你也可以添加 `cookie` 或 `date` 等请求头。 |

### Parameters

用于构造请求体（POST）或查询字符串（GET）的参数。

#### HTTP 授权

| Key | Placeholder | Description |
|---|---|---|
| `clientid` | `%c` | MQTT Client ID |
| `username` | `%u` | 用户名 |
| `password` | `%P` | 密码 |
| `access` | `%A` | 待验证的权限：`1` 表示订阅，`2` 表示发布 |
| `topic` | `%t` | 客户端尝试发布或订阅的主题。 |
| `ipaddr` | `%a` | 客户端网络 IP 地址 |
| `mountpoint` | `%m` | 挂载点 |
| `common` | `%C` | 客户端 TLS 证书中的 Common Name。从 EMQX Edge 1.4.0 开始支持。 |
| `subject` | `%d` | 客户端 TLS 证书中的 Subject。从 EMQX Edge 1.4.0 开始支持。 |

:::tip 注意
以下键已在界面中定义，但当前版本尚不支持：`sockport`、`protocol`。
:::

#### HTTP Super User

| Key | Placeholder | Description |
|---|---|---|
| `clientid` | `%c` | MQTT Client ID |
| `username` | `%u` | 用户名 |
| `password` | `%P` | 密码 |
| `access` | `%A` | 待验证的权限：`1` 表示订阅，`2` 表示发布 |
| `topic` | `%t` | 客户端尝试发布或订阅的主题。 |