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

概览

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

适用场景

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

消费者凭证参考

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

支持的算法

系列	算法
HMAC	HS256、HS384、HS512
RSA	RS256, RS384, RS512
RSA-PSS	PS256, PS384, PS512
ECDSA	ES256, ES384, ES512
EdDSA	EdDSA

路由/服务配置参考

字段	类型	是否必填	默认值	说明
header	string	否	"authorization"	从请求头提取 JWT
query	string	否	"jwt"	从查询参数提取 JWT
cookie	string	否	"jwt"	从 Cookie 提取 JWT
hide_credentials	boolean	否	false	转发到上游前移除 JWT
key_claim_name	string	否	"key"	包含消费者 key 的 JWT 声明，必须与凭证配置匹配
anonymous_consumer	string	否	—	用于未通过身份认证的请求的消费者
claims_to_verify	array	否	["exp","nbf"]	要校验的声明（exp、nbf）

令牌查找优先级

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 签发令牌。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
  }
}

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

查询参数中的令牌

{
  "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 中没有令牌
401	"JWT token invalid"	令牌格式错误
401	"failed to verify jwt"	签名错误、已过期或声明无效
401	"Invalid user key in JWT token"	未找到消费者 key

故障排查

现象	原因	修复方式
401 "failed to verify jwt"	令牌已过期	使用未来的 exp 生成新令牌
401 "failed to verify jwt"	算法不匹配	确保凭证 algorithm 与令牌匹配
401 "Invalid user key"	声明名称错误	在凭证和路由上同时设置 key_claim_name
公钥被拒绝	PEM 中缺少换行	在 PEM 头部之后、尾部之前包含 \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 页面查看所有技能。