Apache APISIX 入门教程：Key Authentication 密钥认证详解-CSDN博客

本文链接：https://blog.csdn.net/gitblog_00657/article/details/148377520

Apache APISIX 入门教程：Key Authentication 密钥认证详解

apisix Apisix是一个基于Nginx的API网关，主要用于微服务架构中的API管理和服务发现。它的特点是高性能、轻量级、易于配置等。适用于API管理和负载均衡场景。项目地址: https://gitcode.com/gh_mirrors/api/apisix

前言

在现代 API 网关架构中，安全认证是保护后端服务的第一道防线。Apache APISIX 作为高性能 API 网关，提供了多种认证机制。本文将深入讲解其中最基础也最常用的 Key Authentication（密钥认证）方式。

什么是密钥认证

密钥认证是一种基于 API Key 的简单认证机制，其工作原理如下：

管理员在路由上配置密钥认证插件
为每个消费者(Consumer)分配唯一的 API Key
客户端在请求头或查询参数中携带该 Key
APISIX 网关验证 Key 的有效性

这种认证方式特别适合机器对机器(M2M)的 API 通信场景。

核心概念解析

Consumer（消费者）

在 APISIX 中，Consumer 代表 API 的使用者，可以是：

移动应用程序
Web 前端
第三方服务
开发者账号

每个 Consumer 需要：

唯一的用户名(username)
至少启用一个认证插件

Key Auth 插件

key-auth 插件是 APISIX 内置的认证插件之一，主要特性包括：

支持 header 和 query string 两种传递方式
可自定义 API Key 的字段名称
可与其它插件组合使用

实战配置指南

前置准备

已完成 APISIX 的安装部署
已创建基本路由（参考路由配置教程）

步骤一：创建 Consumer

我们创建一个名为 "tom" 的消费者，并为其分配 API Key：

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。

安全提示：生产环境务必使用高强度随机密钥，避免使用简单字符串。

步骤二：启用路由认证

为现有路由启用密钥认证：

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

步骤三：验证认证效果

测试场景 1：无密钥请求

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

预期返回 401 Unauthorized，因为未提供认证凭证。

测试场景 2：错误密钥请求

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

同样返回 401，因为密钥不匹配。

测试场景 3：正确密钥请求

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

成功返回 200 OK 和预期响应内容。

高级配置选项

key-auth 插件支持多种自定义配置：

{
  "key-auth": {
    "key": "your-key",
    "header": "x-custom-key",  // 自定义 header 字段
    "query": "api_key"        // 自定义 query 参数名
  }
}

禁用认证功能

当需要临时关闭认证时，可以通过以下方式：

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