功能说明

key-auth插件实现了基于 API Key 进行认证鉴权的功能，支持从 HTTP 请求的 URL 参数或者请求头解析 API Key，同时验证该 API Key 是否有权限访问。

运行属性

插件执行阶段：认证阶段 插件执行优先级：310

配置字段

注意：

• 在一个规则里，鉴权配置和认证配置不可同时存在
• 对于通过认证鉴权的请求，请求的header会被添加一个X-Mse-Consumer字段，用以标识调用者的名称。

认证配置

consumers中每一项的配置字段说明如下：

鉴权配置（非必需）

配置示例

全局配置认证和路由粒度进行鉴权

以下配置将对网关特定路由或域名开启Key Auth认证和鉴权。credential字段不能重复。

在实例级别做如下插件配置：

global_auth: false
consumers:
- credential: 2bda943c-ba2b-11ec-ba07-00163e1250b5
  name: consumer1
- credential: c8c8e9ca-558e-4a2d-bb62-e700dcc40e35
  name: consumer2
keys:
- apikey
- x-api-key

对 route-a 和 route-b 这两个路由做如下配置：

allow:
- consumer1

对 *.example.com 和 test.com 在这两个域名做如下配置:

allow:
- consumer2

说明：

此例指定的route-a和route-b即在创建网关路由时填写的路由名称，当匹配到这两个路由时，将允许name为consumer1的调用者访问，其他调用者不允许访问。

此例指定的*.example.com和test.com用于匹配请求的域名，当发现域名匹配时，将允许name为consumer2的调用者访问，其他调用者不被允许访问。

根据该配置，下列请求可以允许访问：

假设以下请求会匹配到route-a这条路由 n 将 API Key 设置在 url 参数中

curl  http://xxx.hello.com/test?apikey=2bda943c-ba2b-11ec-ba07-00163e1250b5

将 API Key 设置在 http 请求头中

curl  http://xxx.hello.com/test -H ‘x-api-key: 2bda943c-ba2b-11ec-ba07-00163e1250b5’

认证鉴权通过后，请求的header中会被添加一个X-Mse-Consumer字段，在此例中其值为consumer1，用以标识调用方的名称

下列请求将拒绝访问：

请求未提供 API Key，返回401

curl  http://xxx.hello.com/test

请求提供的 API Key 无权访问，返回401

curl  http://xxx.hello.com/test?apikey=926d90ac-ba2e-11ec-ab68-00163e1250b5

根据请求提供的 API Key匹配到的调用者无访问权限，返回403

# consumer2不在route-a的allow列表里
curl  http://xxx.hello.com/test?apikey=c8c8e9ca-558e-4a2d-bb62-e700dcc40e35

网关实例级别开启

以下配置将对网关实例级别开启 Basic Auth 认证，所有请求均需要经过认证后才能访问。

global_auth: true
consumers:
- credential: 2bda943c-ba2b-11ec-ba07-00163e1250b5
  name: consumer1
- credential: c8c8e9ca-558e-4a2d-bb62-e700dcc40e35
  name: consumer2
keys:
- apikey
- x-api-key

相关错误码