Key 认证

功能说明

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

配置字段

名称数据类型填写要求默认值描述
global_authbool选填-若配置为true，则全局生效认证机制; 若配置为false，则只对做了配置的域名和路由生效认证机制; 若不配置则仅当没有域名和路由配置时全局生效（兼容机制）
consumersarray of object必填-配置服务的调用者，用于对请求进行认证
keysarray of string必填-API Key 的来源字段名称，可以是 URL 参数或者 HTTP 请求头名称
in_queryboolin_query 和 in_header 至少有一个为 truetrue配置 true 时，网关会尝试从 URL 参数中解析 API Key
in_headerboolin_query 和 in_header 至少有一个为 truetrue配置 true 时，网关会尝试从 HTTP 请求头中解析 API Key

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

名称数据类型填写要求默认值描述
credentialstring必填-配置该 consumer 的访问凭证
namestring必填-配置该 consumer 的名称

注意：

  • 对于通过认证鉴权的请求，请求的 header 会被添加一个 X-Mse-Consumer 字段，用以标识调用者的名称。

配置示例

对特定路由或域名开启

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

  1. 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

路由级配置

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

  1. allow:
    - consumer1

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

  1. allow:
    - consumer2

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

假设以下请求会匹配到 route-a 这条路由。

将 API Key 设置在 url 参数中。

将 API Key 设置在 http 请求头中。

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

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

下列请求将拒绝访问。

请求未提供 API Key，返回 401。

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

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

  1. # consumer2不在route-a的allow列表里

网关实例级别开启

以下配置未指定 matchRules 字段，因此将对网关实例级别开启全局 Key Auth 认证.

  1. defaultConfig
      consumers:
      - credential: 2bda943c-ba2b-11ec-ba07-00163e1250b5
        name: consumer1
      - credential: c8c8e9ca-558e-4a2d-bb62-e700dcc40e35
        name: consumer2
      keys:
      - apikey
      in_query: true

开启 matchRules 方式如下：

  1. matchRules:
      - config:
          allow:
            - consumer1

相关错误码

HTTP 状态码出错信息原因说明
401Request denied by Key Auth check. Muti API key found in request请求提供多个 API Key
401Request denied by Key Auth check. No API key found in request请求未提供 API Key
401Request denied by Key Auth check. Invalid API key不允许当前 API Key 访问
403Request denied by Key Auth check. Unauthorized consumer请求的调用方无访问权限