key-auth

描述

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

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

属性

Consumer 端:

名称类型必选项描述
keystring不同的 Consumer 应有不同的 key,它应当是唯一的。如果多个 Consumer 使用了相同的 key,将会出现请求匹配异常。该字段支持使用 APISIX Secret 资源,将值保存在 Secret Manager 中。

注意:schema 中还定义了 encrypt_fields = {"key"},这意味着该字段将会被加密存储在 etcd 中。具体参考 加密存储字段

Router 端:

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

启用插件

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

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

  1. curl http://127.0.0.1:9180/apisix/admin/consumers \
  2. -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  3. {
  4. "username": "jack",
  5. "plugins": {
  6. "key-auth": {
  7. "key": "auth-one"
  8. }
  9. }
  10. }'

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

创建 Consumer 对象后,你可以创建 Route 进行验证:

  1. curl http://127.0.0.1:9180/apisix/admin/routes/1 \
  2. -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  3. {
  4. "methods": ["GET"],
  5. "uri": "/index.html",
  6. "id": 1,
  7. "plugins": {
  8. "key-auth": {}
  9. },
  10. "upstream": {
  11. "type": "roundrobin",
  12. "nodes": {
  13. "127.0.0.1:1980": 1
  14. }
  15. }
  16. }'

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

  1. {
  2. "key-auth": {
  3. "header": "Authorization"
  4. }
  5. }

测试插件

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

  1. curl http://127.0.0.2:9080/index.html -H 'apikey: auth-one' -i
  1. HTTP/1.1 200 OK
  2. ...

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

  1. curl http://127.0.0.2:9080/index.html -i
  1. HTTP/1.1 401 Unauthorized
  2. ...
  3. {"message":"Missing API key found in request"}
  1. curl http://127.0.0.2:9080/index.html -H 'apikey: abcabcabc' -i
  1. HTTP/1.1 401 Unauthorized
  2. ...
  3. {"message":"Invalid API key in request"}

禁用插件

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

  1. curl http://127.0.0.1:9180/apisix/admin/routes/1 \
  2. -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  3. {
  4. "methods": ["GET"],
  5. "uri": "/index.html",
  6. "id": 1,
  7. "plugins": {
  8. },
  9. "upstream": {
  10. "type": "roundrobin",
  11. "nodes": {
  12. "127.0.0.1:1980": 1
  13. }
  14. }
  15. }'