key-auth

描述

key-auth 插件用于向 Route 或 Service 添加身份验证密钥（API key）。

它需要与 Consumer 一起配合才能工作，通过 Consumer 将其密钥添加到查询字符串参数或标头中以验证其请求。

属性

Consumer 端：

名称	类型	必选项	描述
key	string	是	不同的 Consumer 应有不同的 key，它应当是唯一的。如果多个 Consumer 使用了相同的 key，将会出现请求匹配异常。

Router 端：

名称	类型	必选项	默认值	描述
header	string	否	apikey	设置我们从哪个 header 获取 key。
query	string	否	apikey	设置我们从哪个 query string 获取 key，优先级低于 header。
hide_credentials	bool	否	false	当设置为 false 时将含有认证信息的 header 或 query string 传递给 Upstream。 如果为 true 时将删除对应的 header 或 query string，具体删除哪一个取决于是从 header 获取 key 还是从 query string 获取 key。

启用插件

如果你要启用插件，就必须使用身份验证密钥创建一个 Consumer 对象，并且需要配置 Route 才可以对请求进行身份验证。

首先，你可以通过 Admin API 创建一个具有唯一 key 的 Consumer：

curl http://127.0.0.1:9080/apisix/admin/consumers \-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '{    "username": "jack",    "plugins": {        "key-auth": {            "key": "auth-one"        }    }}'

你还可以通过 APISIX Dashboard 的 Web 界面完成上述操作。

创建 Consumer 对象后，你可以创建 Route 进行验证：

curl http://127.0.0.1:9080/apisix/admin/routes/1 \-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '{    "methods": ["GET"],    "uri": "/index.html",    "id": 1,    "plugins": {        "key-auth": {}    },    "upstream": {        "type": "roundrobin",        "nodes": {            "127.0.0.1:1980": 1        }    }}'

如果你不想从默认的 apikey header 获取 key，可以自定义 header，如下所示：

{    "key-auth": {        "header": "Authorization"    }}

测试插件

通过上述方法配置插件后，可以通过以下命令测试插件：

curl http://127.0.0.2:9080/index.html -H 'apikey: auth-one' -i

HTTP/1.1 200 OK...

如果当前请求没有正确配置 apikey，将得到一个 401 的应答：

curl http://127.0.0.2:9080/index.html -i

HTTP/1.1 401 Unauthorized...{"message":"Missing API key found in request"}

curl http://127.0.0.2:9080/index.html -H 'apikey: abcabcabc' -i

HTTP/1.1 401 Unauthorized...{"message":"Invalid API key in request"}

禁用插件

当你需要禁用 key-auth 插件时，可以通过以下命令删除相应的 JSON 配置，APISIX 将会自动重新加载相关配置，无需重启服务：

curl http://127.0.0.1:9080/apisix/admin/routes/1 \-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '{    "methods": ["GET"],    "uri": "/index.html",    "id": 1,    "plugins": {    },    "upstream": {        "type": "roundrobin",        "nodes": {            "127.0.0.1:1980": 1        }    }}'