API Key 是一种简单且被广泛使用的用户认证机制。客户端在请求头或者请求参数中添加唯一的 API key。服务端或者代理获取 API key 之后查询是否存在对应的 Consumer/Client 身份，即可完成对应认证。API 网关使用 Key Auth 插件实现基于 API Key 的认证鉴权。本文介绍如何为 API 网关配置 API Key 认证。 ## 前提条件 * 已创建网关实例，详情请参见 [创建实例](https://www.volcengine.com/docs/6569/85693)。 * 已将网关实例升级至 3.1.0 及以上版本，详情请参见 [版本管理](https://www.volcengine.com/docs/6569/1657695)。 * 已创建服务，详情请参见 [创建服务](https://www.volcengine.com/docs/6569/85695#%E5%88%9B%E5%BB%BA%E6%9C%8D%E5%8A%A1)。 * 已创建消费者，并生成或上传 API Key 信息。详情请参见 [生成认证信息](https://www.volcengine.com/docs/6569/1215181)。 ## 使用限制 * 同一插件在同一资源上只能绑定一次。 * 同一插件在不同级别的资源上绑定时，只匹配生效优先级最高的资源，生效优先级由高到低：路由 \> 服务。例如，服务 Ⅰ 具有两条路由：路由 A 和路由 B，将插件配置在服务 Ⅰ 和路由 A 上，此时路由 A 的生效规则遵循路由 A 的插件配置，路由 B 的生效规则遵循服务 Ⅰ 的插件配置。 ## 操作步骤 1. 登录 [API 网关控制台](https://console.volcengine.com/veapig)。 2. 在左侧导航栏选择 **插件管理 \> Key Auth 插件**，单击 **创建插件**，配置插件参数。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_584c5171e392b686f2776183cdbd40ba.png =682x) |配置项 |说明 | |---|---| |生效级别 |选择 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 来进行认证鉴权。|\ | |当选择 **全部** 时，插件将对当前已存在的消费者及后续新创建的消费者生效。当用户生成一个新的认证信息后，会自动加入到插件的认证鉴权范围内。 | 3. 单击 **确定**，完成配置。 ## 结果验证 ### 查看配置配置完成后，在插件列表中，选择 **服务级别** 或 **路由级别** 页签，查看已配置的 Key Auth 插件，若插件状态为 **已启用**，表示插件已生效，只有携带 API Key 认证信息的请求能够正常访问 API 网关的后端 Upstream。 ![图片](https://portal.volccdn.com/obj/volcfe/cloud-universal-doc/upload_cbed75a95b2337ce3e2d0070ecbacc2d.png =849x) ### 认证测试在 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)