配置 Basic 身份认证

Basic 身份认证是保护 Web 服务的常见方式。它使用标准 HTTP Authorization 请求头和 Basic 方案，后跟经过 Base64 编码的 username:password 字符串。

API7 网关提供 basic-auth 插件来处理此身份认证流程，并根据消费者凭证数据库验证凭证。

本指南介绍标准配置流程。有关完整的插件字段参考和高级行为，请参阅 basic-auth。

前置条件

• API7 企业版实例正在运行。
• 已创建网关组且网关实例正在运行。
• 已从控制台获取令牌。

配置 Basic 身份认证

配置 Basic 身份认证包含三个步骤：

1. 创建具有有效上游的服务。
2. 创建启用 basic-auth 的路由。
3. 创建消费者并挂载 Basic 身份认证凭证。

第 1 步：创建具有上游的服务

Admin API

curl -k "https://localhost:7443/apisix/admin/services/basic-auth-httpbin-service?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "basic-auth-httpbin-service",
    "upstream": {
      "type": "roundrobin",
      "scheme": "http",
      "nodes": [
        {
          "host": "httpbin.org",
          "port": 80,
          "weight": 100
        }
      ]
    }
  }'

ADC

adc.yaml

services:
  - name: basic-auth-httpbin-service
    upstream:
      name: default
      scheme: http
      nodes:
        - host: httpbin.org
          port: 80
          weight: 100
    routes:
      - name: basic-auth-route
        uris:
          - /anything/basic-auth
        methods:
          - GET
        plugins:
          basic-auth:
            hide_credentials: true
consumers:
  - username: basic-auth-consumer
    credentials:
      - name: basic-auth-consumer-cred
        type: basic-auth
        config:
          username: alice
          password: secret-password

adc sync -f adc.yaml

第 2 步：创建路由并启用 basic-auth

Admin API

curl -k "https://localhost:7443/apisix/admin/routes/basic-auth-route?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "basic-auth-route",
    "paths": ["/anything/basic-auth"],
    "methods": ["GET"],
    "service_id": "basic-auth-httpbin-service",
    "plugins": {
      "basic-auth": {
        "hide_credentials": true
      }
    }
  }'

ADC

该路由已包含在前面的 adc.yaml 示例中。

第 3 步：创建消费者和凭证

Admin API

# 1. 创建消费者
curl -k "https://localhost:7443/apisix/admin/consumers/basic-auth-consumer?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "basic-auth-consumer"
  }'

# 2. 创建 basic-auth 凭证
curl -k "https://localhost:7443/apisix/admin/consumers/basic-auth-consumer/credentials/basic-auth-consumer-cred?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "basic-auth-consumer-cred",
    "plugins": {
      "basic-auth": {
        "username": "alice",
        "password": "secret-password"
      }
    }
  }'

ADC

消费者和凭证已包含在前面的 adc.yaml 示例中。

验证配置

发送不含 Authorization 请求头的请求。网关应返回 401 Unauthorized 拒绝请求：

curl -i "http://127.0.0.1:9080/anything/basic-auth"

然后使用正确凭证发送请求：

curl -i "http://127.0.0.1:9080/anything/basic-auth" \
  -u alice:secret-password

应收到 200 OK，上游响应应包含类似以下的请求头：

{
  "headers": {
    "X-Consumer-Username": "basic-auth-consumer",
    "X-Credential-Identifier": "basic-auth-consumer-cred"
  }
}

如果应用配置后，已认证请求仍返回 401 或路由返回 404，请等待几秒，让最新配置下发到网关后重试。

后续步骤

• 配置 Key 身份认证——使用唯一 API Key（API 密钥）保护 API。
• 配置 JWT 身份认证——使用 JSON Web Token 实现无状态身份认证。
• 消费者和凭证——理解 API7 网关如何管理 API 身份。