# 扩展授权

扩展授权帮助用户使用自己服务进行授权，支持外部数据库如 MySQL， Redis 作为数据源，或者连接到 HTTP 服务做授权。

::: tip 提示

Serverless 部署不支持扩展授权功能。

:::


## 扩展授权数据源

[基于 HTTP 授权](./http_authz.md)

[基于 MySQL 授权](./mysql_authz.md)

[基于 PostgreSQL 授权](./pgsql_authz.md)

[基于 Redis 授权](./redis_authz.md)

::: tip

虽然最多支持两种扩展授权，但为确保性能，不建议同时使用多种扩展授权。

:::

## 授权排序

在添加扩展授权数据源后，您可以对授权源进行排序。部署将按照从左到右的顺序执行授权检查。默认情况下，最近添加的授权源排在最前，而“默认授权”位于最后。

- 系统会将客户端的操作与权限进行匹配，并基于权限决定是否允许或拒绝该操作。
- 如果当前授权源未匹配到权限，将继续传递给下一个授权源进行检查。

::: 提示

如果外置认证/授权服务出现异常（例如服务不可用、请求超时或返回非预期状态码），该授权源将被跳过，并继续由下一个授权源进行判断；如果后续没有任何授权规则命中，则客户端将被允许发布和订阅主题。

:::

### 如何创建授权链

您可以在部署页面的**访问控制** -> **客户端授权** -> **扩展授权**中创建授权链。当扩展授权数据源配置并连接成功后，页面将显示顺序设置区域。

1. 点击**授权排序**，进入授权顺序设置页面。
2. 通过左右拖动授权数据源图标调整授权顺序。
3. 完成后点击**确认**保存顺序设置。

![add_acl](./_assets/acl_v5_order.png)

### 启用白名单模式的授权链要求

启用白名单模式后，默认拒绝所有客户端的订阅和发布操作，必须显式授予权限才能进行这些操作。详细设置步骤请参见：[开启授权白名单模式](./default_authz.md#开启授权白名单模式)。

要启用白名单模式，必须确保**默认授权**位于授权链的最后一位。您可以在**授权排序**页面下的顺序设置区域中调整其位置。

## 外部资源缓存

::: tip 提示

外部资源缓存功能适用于 EMQX 5.9 及以上版本的专有版部署。

:::

EMQX Cloud 支持对来自外部后端（如 MySQL 或 Redis）的授权结果进行缓存。该缓存机制可提升授权查询的性能，减少在高吞吐量场景下对外部资源的重复访问。

:::

### 外部资源缓存的工作原理

外部资源缓存用于存储客户端授权的结果，这些结果在整个集群中的所有客户端会话之间共享，有效避免重复访问外部授权后端。

授权流程如下：

1. 客户端连接并触发授权操作。
2. EMQX Cloud 首先在缓存中查找是否已有对应的授权结果：
   - 如果找到了有效的结果，则视为**缓存命中**，无需访问外部后端。
   - 如果未找到缓存结果，则视为**缓存未命中**，EMQX Cloud 会向外部后端发起查询。
3. 从后端返回的授权结果将被存入缓存，用于后续请求，并计入**缓存写入**指标。

该机制有助于降低授权延迟、减少外部资源调用，并在高负载下维持系统响应能力。

### 启用和配置外部资源缓存

您可以在部署页面的**访问控制** -> **客户端授权** -> **扩展授权**中启用并配置外部资源缓存。当扩展授权数据源已配置并连接后，页面将显示**缓存设置**区域。

1. 点击**外部资源缓存设置**打开侧边栏面板。
2. 在面板中点击**启用外部资源缓存**开关以开启或关闭缓存功能。
3. 启用后，可配置以下缓存参数：
   - **最大缓存数量**：每个节点可缓存的最大条目数。默认值：1,000,000。
   - **最大内存**：缓存可占用的最大内存。默认值：100 MB。
   - **缓存过期时间**：每条缓存项的有效时长。默认值：1 分钟。
4. 点击**更新**应用配置。

### 监控外部资源缓存状态

若要实时查看缓存指标和使用情况：

1. 将鼠标悬停在**外部资源缓存设置**右侧的箭头上；
2. 点击**外部资源缓存状态**，弹出侧边栏查看实时缓存指标。

可查看的缓存指标包括：

- **内存占用**：当前缓存占用的总内存。
- **缓存条目数**：当前存储的缓存授权结果总数。
- **缓存命中**：EMQX Cloud 成功在缓存中找到有效结果，避免访问外部后端的次数。
  - 展示数据包括：当前速率、5 分钟平均值、最大速率
- **缓存未命中**：EMQX Cloud 未能在缓存中找到结果，因而查询外部后端的次数。
  - 展示数据包括：当前速率、5 分钟平均值、最大速率
- **缓存插入**：在未命中后新增写入缓存结果的次数。
  - 展示数据包括：当前速率、5 分钟平均值、最大速率

您可以通过面板右上角的按钮刷新或重置这些统计数据。