key-auth.md

title	keywords	description
key-auth	Apache APISIX API 网关 Plugin Key Auth key-auth	本文介绍了关于 Apache APISIX `key-auth` 插件的基本信息及使用方法。

描述

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

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

属性

Consumer 端：

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

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

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：

:::note

您可以这样从 config.yaml 中获取 admin_key 并存入环境变量：

admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g')

:::

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

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

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

curl http://127.0.0.1:9180/apisix/admin/routes/1 \
-H "X-API-KEY: $admin_key" -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:9180/apisix/admin/routes/1 \
-H "X-API-KEY: $admin_key" -X PUT -d '
{
    "methods": ["GET"],
    "uri": "/index.html",
    "id": 1,
    "plugins": {
    },
    "upstream": {
        "type": "roundrobin",
        "nodes": {
            "127.0.0.1:1980": 1
        }
    }
}'