# 实施密钥认证

密钥认证是一种轻量级且有效的控制 API 访问的方法。通过向消费者颁发唯一的 API 密钥，APISIX 可以识别和验证请求，而无需复杂的 Token 交换或用户凭证。此方法非常适合优先考虑简单性的用例，例如保护内部 API、为受信任的合作伙伴启用访问权限或记录每位消费者的使用情况。但是，对于需要更强身份认证方法（如 OAuth）的高度敏感或面向公众的 API，通常应避免使用此方法。

在本指南中，你将实现一个场景，其中有两个消费者使用 [密钥认证](https://docs.apiseven.com/hub/key-auth.md) 向 APISIX 进行身份认证，每个消费者具有不同的限流限速配额。一旦实施，消费者应该能够访问上游服务并将消费者 ID 转发到上游服务，从而为额外的业务逻辑提供选项。

## 前置条件[​](#前置条件 "前置条件的直接链接")

* 安装 [Docker](https://docs.docker.com/get-docker/)。
* 安装 [cURL](https://curl.se/) 以向服务发送请求进行验证。
* 按照 [快速入门教程](https://docs.apiseven.com/apisix/getting-started.md) 在 Docker 或 Kubernetes 中启动一个新的 APISIX 实例。

## 创建消费者[​](#创建消费者 "创建消费者的直接链接")

消费者是指使用 API 的应用程序或开发者。在使用 APISIX 内置身份认证方法时，你应该始终创建消费者。

创建一个具有可选自定义 ID 和 30 秒窗口内一个请求的限流限速配额的消费者 `johndoe`：

```
curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \

  -H "X-API-KEY: ${ADMIN_API_KEY}" \

  -d '{

    "username": "johndoe",

    "labels": {

      "custom_id": "john-doe-junior"

    },

    "plugins": {

      "limit-count": {

        "count": 1,

        "time_window": 30,

        "rejected_code": 429

      }

    }

  }'
```

如果你希望实施额外的业务逻辑，自定义 ID 将转发到上游服务。

创建另一个具有可选自定义 ID 和 30 秒窗口内两个请求的限流限速配额的消费者 `janedoe`：

```
curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \

  -H "X-API-KEY: ${ADMIN_API_KEY}" \

  -d '{

    "username": "janedoe",

    "labels": {

      "custom_id": "jane-doe-senior"

    },

    "plugins": {

      "limit-count": {

        "count": 2,

        "time_window": 30,

        "rejected_code": 429

      }

    }

  }'
```

## 创建消费者凭证[​](#创建消费者凭证 "创建消费者凭证的直接链接")

凭证用于配置与消费者关联的身份认证凭证。

为 `johndoe` 创建 `key-auth` 凭证：

```
curl "http://127.0.0.1:9180/apisix/admin/consumers/johndoe/credentials" -X PUT \

  -H "X-API-KEY: ${ADMIN_API_KEY}" \

  -d '{

    "id": "cred-john-key-auth",

    "plugins": {

      "key-auth": {

        "key": "john-key"

      }

    }

  }'
```

为 `janedoe` 创建 `key-auth` 凭证：

```
curl "http://127.0.0.1:9180/apisix/admin/consumers/janedoe/credentials" -X PUT \

  -H "X-API-KEY: ${ADMIN_API_KEY}" \

  -d '{

    "id": "cred-jane-key-auth",

    "plugins": {

      "key-auth": {

        "key": "jane-key"

      }

    }

  }'
```

## 创建路由[​](#创建路由 "创建路由的直接链接")

创建一个路由并启用 `key-auth`：

```
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \

  -H "X-API-KEY: ${ADMIN_API_KEY}" \

  -d '{

    "id": "key-auth-route",

    "uri": "/anything",

    "plugins": {

      "key-auth": {}

    },

    "upstream": {

      "type": "roundrobin",

      "nodes": {

        "httpbin.org:80": 1

      }

    }

  }'
```

## 验证[​](#验证 "验证的直接链接")

使用 `john` 的密钥向路由发送请求：

```
curl "http://127.0.0.1:9080/anything" -H 'apikey: john-key'
```

你应该看到类似以下的 `HTTP/1.1 200 OK` 响应：

```
{

  "args": {},

  "data": "",

  "files": {},

  "form": {},

  "headers": {

    ...

    "X-Consumer-Username": "johndoe",

    "X-Credential-Identifier": "cred-john-key-auth",

    "X-Consumer-Custom-Id": "john-doe-junior",

    "X-Forwarded-Host": "127.0.0.1"

  },

  ...

}
```

上一次成功请求已用完 `john` 在当前 30 秒窗口内的一次请求配额。等待进入下一个窗口，再使用 `john` 的密钥向路由发送三个请求：

```
sleep 31



resp=$(seq 3 | xargs -I{} curl "http://127.0.0.1:9080/anything" -H 'apikey: john-key' -o /dev/null -s -w "%{http_code}\n") && \

  count_200=$(echo "$resp" | grep "200" | wc -l) && \

  count_429=$(echo "$resp" | grep "429" | wc -l) && \

  echo "200": $count_200, "429": $count_429
```

你应该看到以下响应，显示在 3 个请求中，1 个请求成功，而其他请求被拒绝：

```
200:    1, 429:    2
```

使用 `jane` 的密钥向路由生成三个请求：

```
resp=$(seq 3 | xargs -I{} curl "http://127.0.0.1:9080/anything" -H 'apikey: jane-key' -o /dev/null -s -w "%{http_code}\n") && \

  count_200=$(echo "$resp" | grep "200" | wc -l) && \

  count_429=$(echo "$resp" | grep "429" | wc -l) && \

  echo "200": $count_200, "429": $count_429
```

你应该看到以下响应，显示在 3 个请求中，2 个请求成功，而另一个被拒绝：

```
200:    2, 429:    1
```

最后，发送一个带有无效密钥的请求：

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

你应该看到 `HTTP/1.1 401 Unauthorized` 响应，并带有以下消息：

```
{"message":"Invalid API key in request"}
```

## 下一步[​](#下一步 "下一步的直接链接")

你现在已经学会了如何实施密钥认证。APISIX 支持其他内置身份认证方法，例如 [基本认证](https://docs.apiseven.com/apisix/how-to-guide/authentication/implement-basic-auth.md)、[JWT 认证](https://docs.apiseven.com/apisix/how-to-guide/authentication/implement-jwt-auth.md) 和 [HMAC 认证](https://docs.apiseven.com/apisix/how-to-guide/authentication/implement-hmac-auth.md)。
