版本：3.18.0

实施 JWT 认证

JWT 认证是一种使用已签名 JSON Web Token 对 API 客户端进行身份认证的安全、无状态方法。令牌可以包含用户身份和角色等声明，使 API 无需查询身份认证数据库即可验证请求。这种方法适合需要轻量级身份认证的分布式应用程序。由于令牌在过期前始终有效，请为敏感 API 设置较短的过期时间或实现令牌撤销。

在本指南中，你将实现一个场景，其中有两个消费者使用 JWT 认证向 APISIX 进行身份认证，每个消费者具有不同的限流限速配额。一旦实施，消费者应该能够访问上游服务并将消费者 ID 转发到上游服务，从而为额外的业务逻辑提供选项。

创建消费者

消费者是指使用 API 的应用程序或开发者。在使用 APISIX 内置身份认证方法时，你应该始终创建消费者。

创建一个具有可选自定义 ID 和 30 秒窗口内一个请求的限流限速配额的消费者 johndoe：

curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "username": "johndoe",
    "labels": {
      "custom_id": "john-doe-junior"
    },
    "plugins": {
      "limit-count": {
        "count": 1,
        "time_window": 30,
        "rejected_code": 429
      }
    }
  }'

如果你希望实施额外的业务逻辑，自定义 ID 将转发到上游服务。

创建另一个具有可选自定义 ID 和 30 秒窗口内两个请求的限流限速配额的消费者 janedoe：

curl "http://127.0.0.1:9180/apisix/admin/consumers" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "username": "janedoe",
    "labels": {
      "custom_id": "jane-doe-senior"
    },
    "plugins": {
      "limit-count": {
        "count": 2,
        "time_window": 30,
        "rejected_code": 429
      }
    }
  }'

创建消费者凭证

凭证用于配置与消费者关联的身份认证凭证。

为 johndoe 创建 jwt-auth 凭证：

curl "http://127.0.0.1:9180/apisix/admin/consumers/johndoe/credentials" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "cred-john-jwt-auth",
    "plugins": {
      "jwt-auth": {
        "key": "john-key",
        "secret": "john-hs256-secret-that-is-very-long"
      }
    }
  }'

为 janedoe 创建 jwt-auth 凭证：

curl "http://127.0.0.1:9180/apisix/admin/consumers/janedoe/credentials" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "cred-jane-jwt-auth",
    "plugins": {
      "jwt-auth": {
        "key": "jane-key",
        "secret": "jane-hs256-secret-that-is-very-long"
      }
    }
  }'

创建路由

创建一个路由并启用 jwt-auth：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "jwt-auth-route",
    "uri": "/anything",
    "plugins": {
      "jwt-auth": {}
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

签发 JWT

要为 johndoe 签发 JWT，你可以使用 JWT.io 的 JWT 编码器或其他工具。如果你使用 JWT.io 的 JWT 编码器，请执行以下操作：

填写 HS256 作为算法。
在 Valid secret 部分中将密钥更新为 john-hs256-secret-that-is-very-long。
使用消费者密钥 john-key 更新有效负载；并将 exp 或 nbf 添加为 UNIX 时间戳。

备注

当 claims_to_verify 是非空列表时，列表中的每个声明都是必填项并会被校验。当该配置未设置或为空时，APISIX 会校验已存在的 exp 和 nbf，但不要求必须提供这两个声明。

JWT 请求头中的 alg 值必须与消费者凭证上配置的算法完全一致。算法不匹配时，APISIX 会在验证签名前返回 401 Unauthorized。

你的有效负载应类似于以下内容：

{
  "key": "john-key",
  "nbf": 1729132271
}

复制生成的 JWT 并保存到变量：

export john_jwt_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJqb2huLWtleSIsIm5iZiI6MTcyOTEzMjI3MX0.TgoM2efMEaSX7KrIWujGLGK5dpPGS2nbaiinmVVjKKw

对 janedoe 重复该步骤并将生成的 JWT 保存到 jane_jwt_token。

验证

使用 john 的密钥向路由发送请求：

curl -i "http://127.0.0.1:9080/anything" -H "Authorization: ${john_jwt_token}"

你应该看到类似以下的 HTTP/1.1 200 OK 响应：

{
  "args": {},
  "data": "",
  "files": {},
  "form": {},
  "headers": {
    "Accept": "*/*",
    "Authorization": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJqb2huLWtleSIsIm5iZiI6MTcyOTEzMjI3MX0.TgoM2efMEaSX7KrIWujGLGK5dpPGS2nbaiinmVVjKKw",
    "Host": "127.0.0.1",
    "User-Agent": "curl/8.6.0",
    "X-Amzn-Trace-Id": "Root=1-6873b51b-5502cfcd72380323266c22e8",
    "X-Consumer-Custom-Id": "john-doe-junior",
    "X-Consumer-Username": "johndoe",
    "X-Credential-Identifier": "cred-john-jwt-auth",
    "X-Forwarded-Host": "127.0.0.1"
  },
  ...
}

使用 john 的密钥向路由生成三个请求：

resp=$(seq 3 | xargs -I{} curl "http://127.0.0.1:9080/anything" -H "Authorization: ${john_jwt_token}" -o /dev/null -s -w "%{http_code}\n") && \
  count_200=$(echo "$resp" | grep "200" | wc -l) && \
  count_429=$(echo "$resp" | grep "429" | wc -l) && \
  echo "200": $count_200, "429": $count_429

你应该看到以下响应，显示在 3 个请求中，1 个请求成功，而其他请求被拒绝：

200:    1, 429:    2

使用 jane 的密钥向路由生成三个请求：

resp=$(seq 3 | xargs -I{} curl "http://127.0.0.1:9080/anything" -H "Authorization: ${jane_jwt_token}" -o /dev/null -s -w "%{http_code}\n") && \
  count_200=$(echo "$resp" | grep "200" | wc -l) && \
  count_429=$(echo "$resp" | grep "429" | wc -l) && \
  echo "200": $count_200, "429": $count_429

你应该看到以下响应，显示在 3 个请求中，2 个请求成功，而另一个被拒绝：

200:    2, 429:    1

最后，发送一个带有无效密钥的请求：

curl -i "http://127.0.0.1:9080/anything" -H 'Authorization: somewrongkey'

你应该看到 HTTP/1.1 401 Unauthorized 响应，并带有以下消息：

{"message":"JWT token invalid"}

下一步

你现在已经学会了如何实施基本认证。APISIX 支持其他内置身份认证方法，例如密钥认证、基本认证和 HMAC 认证。

创建消费者​

创建消费者凭证​

创建路由​

签发 JWT​

验证​

下一步​

创建消费者

创建消费者凭证

创建路由

签发 JWT

验证

下一步