跳到主要内容
版本：3.10.x

API7 网关 AI Agent Skill：jwt-auth 插件

概览​

jwt-auth 插件使用 JSON Web Token 对请求进行认证。消费者 会注册 key 和 secret（或用于非对称算法的公钥）。客户端 在请求头、查询参数或 Cookie 中包含已签名 JWT。API7 企业版 会校验签名和声明，然后携带消费者 身份请求头转发请求。

适用场景​

  • 基于 Token 的无状态认证
  • 非对称密钥校验（RS256、ES256、EdDSA），API7 企业版只需要公钥
  • 基于自定义声明识别消费者
  • 与外部 Token 签发方集成，例如自建认证服务、Auth0 等

消费者凭证参考​

字段类型是否必填默认值说明
keystring是—JWT 载荷中用于匹配消费者的唯一标识符
secretstring有条件—用于 HMAC 算法（HS256/HS384/HS512）的共享密钥，在数据库中加密存储
public_keystring有条件—用于 RSA/ECDSA/EdDSA 算法的 PEM 公钥
algorithmstring否"HS256"签名算法，参见下方支持的算法列表
expinteger否86400Token 有效期，单位为秒，不是 UNIX 时间戳
base64_secretboolean否false如果 secret 使用 Base64 编码，则设为 true
lifetime_grace_periodinteger否0允许的时钟偏差，单位为秒
key_claim_namestring否"key"包含消费者 key 的 JWT 声明

支持的算法​

系列算法
HMACHS256, HS384, HS512
RSARS256, RS384, RS512
RSA-PSSPS256, PS384, PS512
ECDSAES256, ES384, ES512
EdDSAEdDSA

路由/服务配置参考​

字段类型是否必填默认值说明
headerstring否"authorization"从请求头提取 JWT
querystring否"jwt"从查询参数提取 JWT
cookiestring否"jwt"从 Cookie 提取 JWT
hide_credentialsboolean否false转发到上游前移除 JWT
key_claim_namestring否"key"包含消费者 key 的 JWT 声明，必须与凭证配置匹配
anonymous_consumerstring否—用于未认证请求的消费者
claims_to_verifyarray否["exp","nbf"]要校验的声明（exp、nbf）

Token 查找优先级​

  1. 请求头（默认：authorization）：支持 Bearer <token> 前缀
  2. 查询参数（默认：jwt）
  3. Cookie（默认：jwt）

分步操作：使用 HS256 启用 jwt-auth​

1. 创建消费者​

a7 consumer create -g default -f - <<'EOF'
{
  "username": "alice"
}
EOF

2. 添加 jwt-auth 凭证​

curl -k "https://$(a7 context current -o json | jq -r .server):7443/apisix/admin/consumers/alice/credentials" \
  -X PUT \
  -H "X-API-KEY: $(a7 context current -o json | jq -r .token)" \
  -d '{
    "id": "cred-alice-jwt",
    "plugins": {
      "jwt-auth": {
        "key": "alice-key",
        "secret": "alice-secret-minimum-32-chars-long",
        "algorithm": "HS256",
        "exp": 86400
      }
    }
  }'

3. 创建启用 jwt-auth 的路由​

a7 route create -g default -f - <<'EOF'
{
  "id": "jwt-protected",
  "uri": "/api/*",
  "plugins": {
    "jwt-auth": {}
  },
  "upstream": {
    "type": "roundrobin",
    "nodes": [{"host": "backend", "port": 8080, "weight": 1}]
  }
}
EOF

4. 生成 JWT 并测试​

创建载荷为 {"key": "alice-key", "exp": <future_timestamp>} 的 JWT 并使用 alice-secret-minimum-32-chars-long 通过 HS256 签名。

curl -i http://127.0.0.1:9080/api/test \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9..."

分步操作：使用 RS256 启用 jwt-auth​

1. 生成 RSA 密钥对​

openssl genrsa -out private.pem 2048
openssl rsa -in private.pem -pubout -out public.pem

2. 使用公钥创建凭证​

curl -k "https://$(a7 context current -o json | jq -r .server):7443/apisix/admin/consumers/bob/credentials" \
  -X PUT \
  -H "X-API-KEY: $(a7 context current -o json | jq -r .token)" \
  -d '{
    "id": "cred-bob-jwt",
    "plugins": {
      "jwt-auth": {
        "key": "bob-key",
        "algorithm": "RS256",
        "public_key": "-----BEGIN PUBLIC KEY-----\nMIIBIjAN...\n-----END PUBLIC KEY-----"
      }
    }
  }'

在外部使用 private.pem 签发 Token。API7 企业版只需要公钥。

常见模式​

自定义声明名称（使用 iss 代替 key）​

# 凭证配置：
{
  "jwt-auth": {
    "key": "my-issuer-id",
    "secret": "my-secret",
    "key_claim_name": "iss"
  }
}

# 路由配置：
{
  "jwt-auth": {
    "key_claim_name": "iss"
  }
}

# JWT 载荷：
{
  "iss": "my-issuer-id",
  "exp": 1879318541
}

时钟偏移容忍度​

{
  "jwt-auth": {
    "key": "consumer-key",
    "secret": "my-secret",
    "lifetime_grace_period": 30
  }
}

允许 Token 签发方与 API7 企业版之间存在 30 秒时钟偏移。

查询参数中的 Token​

{
  "plugins": {
    "jwt-auth": {
      "query": "token"
    }
  }
}

客户端发送：curl "http://127.0.0.1:9080/api/test?token=eyJ..."

使用环境变量管理密钥​

{
  "jwt-auth": {
    "key": "consumer-key",
    "secret": "$env://JWT_SECRET"
  }
}

使用 HashiCorp Vault 管理密钥​

{
  "jwt-auth": {
    "key": "consumer-key",
    "secret": "$secret://vault/jwt/consumer-name/jwt-secret"
  }
}

添加到上游的请求头​

请求头值
X-Consumer-Username消费者用户名
X-Credential-Identifier凭证 ID
X-Consumer-Custom-Id消费者的 labels.custom_id（如已设置）

错误响应​

HTTP 状态码消息原因
401"Missing JWT token in request"请求头、查询参数或 Cookie 中没有 Token
401"JWT token invalid"Token 格式错误
401"failed to verify jwt"签名错误、已过期或声明无效
401"Invalid user key in JWT token"未找到消费者 key

故障排查​

现象原因修复方式
401 "failed to verify jwt"Token 已过期使用未来的 exp 生成新 Token
401 "failed to verify jwt"算法不匹配确保凭证 algorithm 与 Token 匹配
401 "Invalid user key"声明名称错误在凭证和路由上同时设置 key_claim_name
公钥被拒绝PEM 中缺少换行在 header 后、footer 前包含 \n
时钟偏移错误存在时间漂移在凭证上设置 lifetime_grace_period

配置同步示例​

version: "1"
gateway_groups:
  - name: default
    consumers:
      - username: alice
    routes:
      - id: jwt-protected
        uri: /api/*
        plugins:
          jwt-auth: {}
        upstream:
          type: roundrobin
          nodes:
            - host: backend
              port: 8080
              weight: 1

注意：消费者凭证（包括 JWT key/secret）必须通过 Admin API 单独管理；a7 config sync 会管理消费者资源，但凭证属于子资源。

本页面由 api7/a7 仓库中的 a7-plugin-jwt-auth/SKILL.md 生成。你可以在 AI Agent Skills 页面查看所有技能。