API 网关通过 Key Auth 插件提供基于 API Key 的认证鉴权能力。本文介绍如何创建并配置 Key Auth 插件，对 API 请求进行身份校验。 ## 背景信息 API Key 是一种简单且被广泛使用的用户认证机制，广泛应用于 API 接口的访问控制场景。其核心原理是客户端在请求头或者请求参数中添加唯一的 API Key，服务端或者代理获取 API Key 之后查询是否存在对应的消费者身份，来判断请求是否被授权。API Key 认证的具体流程如下所示。 1. 管理员在 API 网关中创建消费者，并为其生成 API Key。 2. 管理员在目标服务或路由上创建 Key Auth 插件，并指定允许通过认证的消费者。 3. 客户端发起请求时，在请求头或请求参数中携带 API Key。 4. API 网关收到请求后，提取 API Key 并校验其合法性。 5. 校验通过则将请求转发至后端 Upstream；校验失败则返回认证错误响应。 ## 前提条件 * 已创建网关实例，详情请参见 [创建实例](https://www.volcengine.com/docs/6569/85693)。 * 已将网关实例升级至 3.1.0 及以上版本，详情请参见 [版本管理](https://www.volcengine.com/docs/6569/1657695)。 * 已创建服务，详情请参见 [创建服务](https://www.volcengine.com/docs/6569/85695#.5Yib5bu65pyN5Yqh)。 * 已创建消费者，并生成或上传 API Key 信息。详情请参见 [生成认证信息](https://www.volcengine.com/docs/6569/1215181)。 ## 使用限制 * 同一插件在同一资源上只能绑定一次。 * 同一插件在不同级别的资源上绑定时，只匹配生效优先级最高的资源，生效优先级由高到低：路由 \> 服务。例如，服务 Ⅰ 具有两条路由：路由 A 和路由 B，将插件配置在服务 Ⅰ 和路由 A 上，此时路由 A 的生效规则遵循路由 A 的插件配置，路由 B 的生效规则遵循服务 Ⅰ 的插件配置。 ## 操作步骤 1. 登录 [API 网关控制台](https://console.volcengine.com/veapig)。 2. 在顶部导航栏，选择目标地域。 3. 在左侧导航栏 **实例管理** 下拉框中选择目标实例后，单击 **插件中心** ** \> 认证鉴权 \> Key Auth 插件**。 4. 单击 **创建插件**，配置插件参数。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_584c5171e392b686f2776183cdbd40ba.png) |配置项 |说明 | |---|---| |生效级别 |选择 Key Auth 插件的生效级别，包括：

* **服务级别**： Key Auth 认证在服务内生效，需要指定生效的目标实例和目标服务。

* **路由级别**： Key Auth 在路由内生效，需要指定生效的目标实例、目标服务和目标路由。 | |备注 |输入关于当前 Key Auth 插件的备注信息，可以为空。 | |认证配置 |选择需要附带 Key Auth 认证信息的位置。

* **header**：在请求头中附带 Key Auth 认证信息，默认来源为 Authorization。

* **querystring**：在请求参数中附带 Key Auth 认证信息。当选择该选项时，需要指定请求参数中认证信息的来源。 | |隐藏认证信息 |配置是否对 Upstream 隐藏认证信息。

* 勾选 **启用**：表示对后端 Upstream 隐藏认证信息。

* 不勾选 **启用**：表示不对后端 Upstream 隐藏认证信息。相关的 Key 将会透传至后端。 | |允许匿名访问 |配置是否允许匿名访问，即是否放行不包含 Key Auth 认证信息的请求。

* 勾选 **启用**：表示允许匿名访问，网关会放行不包含 Key Auth 认证信息的请求。

* 不勾选 **启用**：表示禁止匿名访问，网关会阻断不包含 Key Auth 认证信息的请求。 | |忽略 Options |配置是否忽略 Options。

* 勾选 **启用**：表示忽略 Options。

* 不勾选 **启用**：表示不忽略 Options。 | |消费者 |指定插件对应的消费者。插件会使用该消费者生成的 API Key 来进行认证鉴权。

当选择 **全部** 时，插件将对当前已存在的消费者及后续新创建的消费者生效。当用户生成一个新的认证信息后，会自动加入到插件的认证鉴权范围内。 | 5. 单击 **确定**，完成配置。 ## 结果验证 ### 查看配置配置完成后，在插件列表中，选择 **服务级别** 或 **路由级别** 页签，查看已配置的 Key Auth 插件，若插件状态为 **已启用**，表示插件已生效，只有携带 API Key 认证信息的请求能够正常访问 API 网关的后端 Upstream。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_cbed75a95b2337ce3e2d0070ecbacc2d.png) ### 认证测试在 API 网关实例中配置 Key Auth 插件，并使用消费者生成 API Key 认证信息后。仅携带该认证信息的访问请求，能够通过 API 网关访问到后端 Upstream。 1. 使用 API 网关实例中配置的域名访问服务，当未携带 API Key 认证信息时。 ```Bash curl -H "Host: apig-example.com" http://14.xxx.xxx.xxx ``` 预期结果如下，表示认证失败，无法通过 API 网关访问到后端的服务。 ```Bash Consumer authentication failed. ``` 2. 使用 API 网关实例中配置的域名访问服务，当携带 API Key 认证信息时。 ```Bash curl -H "Host: apig-example.com" http://14.xxx.xxx.xxx -H "Authorization: Bearer e8cc8b4f-***" ``` 预期结果如下，表示能够通过 API 网关访问到后端的服务。 ```HTML Welcome to nginx!

Welcome to nginx!

If you see this page, the nginx web server is successfully installed and working. Further configuration is required.

For online documentation and support please refer to nginx.org.
Commercial support is available at nginx.com.

Thank you for using nginx.

``` ## 相关文档 * [使用 API Key 实现网关认证鉴权](https://www.volcengine.com/docs/6569/1515844) * [JWT Token 迁移 API Key 最佳实践（不保留 JWT Token）](https://www.volcengine.com/docs/6569/1544091) * [JWT Token 迁移 API Key 最佳实践（保留 JWT Token）](https://www.volcengine.com/docs/6569/1544092)