配置 JWT 身份认证

JSON Web Token（JWT）身份认证是一种常用的无状态身份认证方式。与简单 API Key 不同，JWT 可以携带声明，网关无需为每个请求查询其他系统即可验证这些声明。

API7 网关中的 jwt-auth插件会根据所配置的消费者凭证验证传入 JWT 的签名。

本指南介绍常见 JWT 配置流程。有关完整插件字段参考以及声明验证、其他 Token 位置等高级选项，请参阅 jwt-auth。

前置条件

• API7 企业版实例正在运行。
• 已创建网关组且网关实例正在运行。
• 一个 Dashboard Token。

配置 JWT 身份认证

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

1. 创建具有有效上游的服务。
2. 创建启用 jwt-auth 的路由。
3. 创建消费者并挂载 JWT 凭据。

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

Admin API

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

ADC

adc.yaml

services:
  - name: jwt-auth-httpbin-service
    upstream:
      name: default
      scheme: http
      nodes:
        - host: httpbin.org
          port: 80
          weight: 100
    routes:
      - name: jwt-auth-route
        uris:
          - /anything/jwt-auth
        methods:
          - GET
        plugins:
          jwt-auth: {}
consumers:
  - username: jwt-auth-consumer
    credentials:
      - name: jwt-auth-consumer-cred
        type: jwt-auth
        config:
          key: user-1-identity
          secret: my-shared-secret

adc sync -f adc.yaml

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

Admin API

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

ADC

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

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

对于 HS256，请为凭证配置用于标识消费者的 key，以及用于验证签名的共享 secret。

Admin API

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

# 2. Create the jwt-auth credential
curl -k "https://localhost:7443/apisix/admin/consumers/jwt-auth-consumer/credentials/jwt-auth-consumer-cred?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "jwt-auth-consumer-cred",
    "plugins": {
      "jwt-auth": {
        "key": "user-1-identity",
        "secret": "my-shared-secret"
      }
    }
  }'

ADC

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

验证配置

首先发送不含 Token 的请求。网关应返回 401 Unauthorized 拒绝请求：

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

然后为所配置的消费者凭证生成 JWT：

header=$(printf '%s' '{"alg":"HS256","typ":"JWT"}' | openssl base64 -A | tr '+/' '-_' | tr -d '=')
payload=$(printf '%s' '{"key":"user-1-identity","exp":1999999999}' | openssl base64 -A | tr '+/' '-_' | tr -d '=')
signature=$(printf '%s' "$header.$payload" | openssl dgst -binary -sha256 -hmac 'my-shared-secret' | openssl base64 -A | tr '+/' '-_' | tr -d '=')
jwt="$header.$payload.$signature"

在 Authorization 请求头中使用生成的 Token：

curl -i "http://127.0.0.1:9080/anything/jwt-auth" \
  -H "Authorization: Bearer $jwt"

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

{
  "headers": {
    "Authorization": "Bearer <your-jwt>",
    "X-Consumer-Username": "jwt-auth-consumer",
    "X-Credential-Identifier": "jwt-auth-consumer-cred"
  }
}

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

后续步骤

• 配置 HMAC 身份认证——使用请求签名提高安全性。
• 配置 Key 身份认证——使用简单 API Key 快速保护 API。
• 了解消费者和凭证——理解 API7 网关如何管理 API 身份。