---

title: 密钥验证 slug: /getting-started/key-authentication

本教程由 API7.ai 编写。

API 网关主要作用是连接 API 消费者和提供者。出于安全考虑，在访问内部资源之前，应先对消费者进行身份验证和授权。

APISIX 拥有灵活的插件扩展系统，目前有很多可用于用户身份验证和授权的插件。例如：

• Key Authentication
• Basic Authentication
• JSON Web Token (JWT) Authentication
• Keycloak
• Casdoor
• Wolf RBAC
• OpenID Connect
• Central Authentication Service (CAS)
• HMAC
• Casbin
• LDAP
• Open Policy Agent (OPA)
• Forward Authentication
• Multiple Authentications

本教程中，你将创建一个带有 密钥验证 插件的 消费者，并学习如何启用和停用身份验证插件。

Consumer 是什么

Consumer（也称之为消费者）是指使用 API 的应用或开发人员。

在 APISIX 中，消费者需要一个全局唯一的 名称，并从上面的列表中选择一个身份验证 插件。

Key Authentication 是什么

Key Authentication（也称之为密钥验证）是一个相对比较简单但是应用广泛的身份验证方法，它的设计思路如下：

1. 管理员为路由添加一个身份验证密钥（API 密钥）。
2. API 消费者在发送请求时，在查询字符串或者请求头中添加密钥。

启用 Key Authentication

前置条件

1. 参考快入门指南完成 APISIX 的安装。
2. 完成配置路由。

创建消费者

创建一个名为 tom 的消费者，并启用 key-auth 插件，密钥设置为 secret-key。所有携带密钥 secret-key 的请求都会被识别为消费者 tom。

:::caution

生产环境请使用复杂的密钥。

:::

curl -i "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT -d '
{
  "username": "tom",
  "plugins": {
    "key-auth": {
      "key": "secret-key"
    }
  }
}'

如果消费者创建成功，你将得到返回 HTTP/1.1 201 Created。

启用 Authentication

在教程配置路由中，我们已经创建了路由 getting-started-ip，我们通过 PATCH 方法为该路由增加 key-auth 插件：

curl -i "http://127.0.0.1:9180/apisix/admin/routes/getting-started-ip" -X PATCH -d '
{
  "plugins": {
    "key-auth": {}
  }
}'

如果增加插件成功，你将得到返回 HTTP/1.1 201 Created。

验证

我们可以在以下场景中进行验证：

1. 发送不带任何密钥的请求

发送一个不带请求头 apikey 的请求。

curl -i "http://127.0.0.1:9080/ip"

如果你已经启用了密钥身份验证，你将会得到返回 HTTP/1.1 401 Unauthorized，即未授权。

HTTP/1.1 401 Unauthorized
Date: Wed, 08 Feb 2023 09:38:36 GMT
Content-Type: text/plain; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Server: APISIX/3.1.0

2. 发送携带错误密钥的请求

发送一个携带错误密钥（比如 wrong-key）的请求。

curl -i "http://127.0.0.1:9080/ip" -H 'apikey: wrong-key'

如果密钥错误，你也将得到返回 HTTP/1.1 401 Unauthorized，即未授权。

HTTP/1.1 401 Unauthorized
Date: Wed, 08 Feb 2023 09:38:27 GMT
Content-Type: text/plain; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Server: APISIX/3.1.0

3. 发送携带正确密钥的请求

发送一个携带正确密钥（secret-key）的请求。

curl -i "http://127.0.0.1:9080/ip" -H 'apikey: secret-key'

你将会得到返回 HTTP/1.1 200 OK。

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 44
Connection: keep-alive
Date: Thu, 09 Feb 2023 03:27:57 GMT
Access-Control-Allow-Origin: *
Access-Control-Allow-Credentials: true
Server: APISIX/3.1.0

禁用 Authentication

将参数设置 _meta.disable 为 true，即可禁用密钥验证插件。

curl "http://127.0.0.1:9180/apisix/admin/routes/getting-started-ip" -X PATCH -d '
{
  "plugins": {
    "key-auth": {
      "_meta": {
        "disable": true
      }
    }
  }
}'

你可以发送一个不带任何密钥的请求来验证：

curl -i "http://127.0.0.1:9080/ip"

因为你已经禁用了密钥验证插件，所以你将会得到返回 HTTP/1.1 200 OK。

下一步

你已经学习了如何为路由配置密钥验证。在下个教程中，你将学习如何配置限速。