This is an automated email from the ASF dual-hosted git repository.
wenming pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix.git
The following commit(s) were added to refs/heads/master by this push:
new 82cd45dcb docs: update `jwt-auth` docs (#12450)
82cd45dcb is described below
commit 82cd45dcbe3b917756980b9fbf4ec8809e32d411
Author: Traky Deng <trakyd...@gmail.com>
AuthorDate: Mon Jul 28 10:17:06 2025 +0800
docs: update `jwt-auth` docs (#12450)
---
docs/en/latest/plugins/jwt-auth.md | 234 ++++++++++++++-----------------
docs/zh/latest/plugins/jwt-auth.md | 278 +++++++++++++++++--------------------
2 files changed, 226 insertions(+), 286 deletions(-)
diff --git a/docs/en/latest/plugins/jwt-auth.md
b/docs/en/latest/plugins/jwt-auth.md
index 773a304e9..36bac34e0 100644
--- a/docs/en/latest/plugins/jwt-auth.md
+++ b/docs/en/latest/plugins/jwt-auth.md
@@ -49,7 +49,7 @@ For Consumer/Credential:
| key | string | True
| | non-empty | Unique key for a Consumer.
|
| secret | string | False
| | non-empty | Shared key used to sign and verify the
JWT when the algorithm is symmetric. Required when using `HS256` or `HS512` as
the algorithm. If unspecified, the secret will be auto-generated. This field
supports saving the value in Secret Manager using the [APISIX
Secret](../terminology/secret.md) resource. |
| public_key | string | True if `RS256` or `ES256` is set for the
`algorithm` attribute. | | | RSA or ECDSA
public key. This field supports saving the value in Secret Manager using the
[APISIX Secret](../terminology/secret.md) resource. |
-| algorithm | string | False
| HS256 | ["HS256", "HS512", "RS256", "ES256"] | Encryption algorithm.
|
+| algorithm | string | False
| HS256 | ["HS256","HS512","RS256","ES256"] | Encryption algorithm.
|
| exp | integer | False
| 86400 | [1,...] | Expiry time of the token in
seconds.
|
| base64_secret | boolean | False
| false | | Set to true if the secret is
base64 encoded.
|
| lifetime_grace_period | integer | False
| 0 | [0,...] | Grace period in seconds. Used to
account for clock skew between the server generating the JWT and the server
validating the JWT. |
@@ -99,7 +99,7 @@ curl "http://127.0.0.1:9180/apisix/admin/consumers"; -X PUT \
}'
```
-Create `jwt-auth` Credential for the Consumer:
+Create `jwt-auth` Credential for the consumer:
```shell
curl "http://127.0.0.1:9180/apisix/admin/consumers/jack/credentials"; -X PUT \
@@ -109,13 +109,13 @@ curl
"http://127.0.0.1:9180/apisix/admin/consumers/jack/credentials"; -X PUT \
"plugins": {
"jwt-auth": {
"key": "jack-key",
- "secret": "jack-hs256-secret"
+ "secret": "jack-hs256-secret-that-is-very-long"
}
}
}'
```
-Create a Route with `jwt-auth` plugin:
+Create a Route with `jwt-auth` Plugin:
```shell
curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
@@ -135,10 +135,10 @@ curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
}'
```
-To issue a JWT for `jack`, you could use [JWT.io's
debugger](https://jwt.io/#debugger-io) or other utilities. If you are using
[JWT.io's debugger](https://jwt.io/#debugger-io), do the following:
+To issue a JWT for `jack`, you could use [JWT.io's JWT
encoder](https://jwt.io) or other utilities. If you are using [JWT.io's JWT
encoder](https://jwt.io), do the following:
-* Select __HS256__ in the __Algorithm__ dropdown.
-* Update the secret in the __Verify Signature__ section to be
`jack-hs256-secret`.
+* Fill in `HS256` as the algorithm.
+* Update the secret in the __Valid secret__ section to be
`jack-hs256-secret-that-is-very-long`.
* Update payload with Consumer key `jack-key`; and add `exp` or `nbf` in UNIX
timestamp.
Your payload should look similar to the following:
@@ -150,10 +150,10 @@ To issue a JWT for `jack`, you could use [JWT.io's
debugger](https://jwt.io/#deb
}
```
-Copy the generated JWT under the __Encoded__ section and save to a variable:
+Copy the generated JWT and save to a variable:
-```text
-jwt_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJqYWNrLWtleSIsIm5iZiI6MTcyOTEzMjI3MX0.0VDKUzNkSaa_H5g_rGNbNtDcKJ9fBGgcGC56AsVsV-I
+```shell
+export
jwt_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJqYWNrLWtleSIsIm5iZiI6MTcyOTEzMjI3MX0.UEPXy5jpid624T1XpfjM0PLY73LZPjV3Qt8yZ92kVuU
```
Send a request to the Route with the JWT in the `Authorization` header:
@@ -164,7 +164,7 @@ curl -i "http://127.0.0.1:9080/headers"; -H "Authorization:
${jwt_token}"
You should receive an `HTTP/1.1 200 OK` response similar to the following:
-```text
+```json
{
"headers": {
"Accept": "*/*",
@@ -179,10 +179,10 @@ You should receive an `HTTP/1.1 200 OK` response similar
to the following:
}
```
-In 30 seconds, the token should expire. Send a request with the same token to
verify:
+Send a request with an invalid token:
```shell
-curl -i "http://127.0.0.1:9080/headers"; -H "Authorization: ${jwt_token}"
+curl -i "http://127.0.0.1:9080/headers"; -H "Authorization:
eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE3MjY2NDk2NDAsImtleSI6ImphY2sta2V5In0.kdhumNWrZFxjU_random_random"
```
You should receive an `HTTP/1.1 401 Unauthorized` response similar to the
following:
@@ -215,13 +215,13 @@ curl
"http://127.0.0.1:9180/apisix/admin/consumers/jack/credentials"; -X PUT \
"plugins": {
"jwt-auth": {
"key": "jack-key",
- "secret": "jack-hs256-secret"
+ "secret": "jack-hs256-secret-that-is-very-long"
}
}
}'
```
-Create a Route with `jwt-auth` Plugin, and specify that the request can either
carry the token in the header, query, or the cookie:
+Create a Route with `jwt-auth` plugin, and specify the request parameters
carrying the token:
```shell
curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
@@ -245,10 +245,10 @@ curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
}'
```
-To issue a JWT for `jack`, you could use [JWT.io's
debugger](https://jwt.io/#debugger-io) or other utilities. If you are using
[JWT.io's debugger](https://jwt.io/#debugger-io), do the following:
+To issue a JWT for `jack`, you could use [JWT.io's JWT
encoder](https://jwt.io) or other utilities. If you are using [JWT.io's JWT
encoder](https://jwt.io), do the following:
-* Select __HS256__ in the __Algorithm__ dropdown.
-* Update the secret in the __Verify Signature__ section to be
`jack-hs256-secret`.
+* Fill in `HS256` as the algorithm.
+* Update the secret in the __Valid secret__ section to be
`jack-hs256-secret-that-is-very-long`.
* Update payload with Consumer key `jack-key`; and add `exp` or `nbf` in UNIX
timestamp.
Your payload should look similar to the following:
@@ -260,10 +260,10 @@ To issue a JWT for `jack`, you could use [JWT.io's
debugger](https://jwt.io/#deb
}
```
-Copy the generated JWT under the __Encoded__ section and save to a variable:
+Copy the generated JWT and save to a variable:
-```text
-jwt_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJqYWNrLWtleSIsIm5iZiI6MTcyOTEzMjI3MX0.0VDKUzNkSaa_H5g_rGNbNtDcKJ9fBGgcGC56AsVsV-I
+```shell
+export
jwt_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJqYWNrLWtleSIsIm5iZiI6MTcyOTEzMjI3MX0.UEPXy5jpid624T1XpfjM0PLY73LZPjV3Qt8yZ92kVuU
```
#### Verify With JWT in Header
@@ -276,13 +276,13 @@ curl -i "http://127.0.0.1:9080/get"; -H "jwt-auth-header:
${jwt_token}"
You should receive an `HTTP/1.1 200 OK` response similar to the following:
-```text
+```json
{
"args": {},
"headers": {
"Accept": "*/*",
"Host": "127.0.0.1",
- "Jwt-Auth-Header":
"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJrZXkiOiJ1c2VyLWtleSIsImV4cCI6MTY5NTEyOTA0NH0.EiktFX7di_tBbspbjmqDKoWAD9JG39Wo_CAQ1LZ9voQ",
+ "Jwt-Auth-Header":
"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJqYWNrLWtleSIsIm5iZiI6MTcyOTEzMjI3MX0.UEPXy5jpid624T1XpfjM0PLY73LZPjV3Qt8yZ92kVuU",
...
},
...
@@ -299,10 +299,10 @@ curl -i "http://127.0.0.1:9080/get?jwt-query=${jwt_token}";
You should receive an `HTTP/1.1 200 OK` response similar to the following:
-```text
+```json
{
"args": {
- "jwt-query":
"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJrZXkiOiJ1c2VyLWtleSIsImV4cCI6MTY5NTEyOTA0NH0.EiktFX7di_tBbspbjmqDKoWAD9JG39Wo_CAQ1LZ9voQ"
+ "jwt-query":
"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJqYWNrLWtleSIsIm5iZiI6MTcyOTEzMjI3MX0.UEPXy5jpid624T1XpfjM0PLY73LZPjV3Qt8yZ92kVuU"
},
"headers": {
"Accept": "*/*",
@@ -323,12 +323,12 @@ curl -i "http://127.0.0.1:9080/get"; --cookie
jwt-cookie=${jwt_token}
You should receive an `HTTP/1.1 200 OK` response similar to the following:
-```text
+```json
{
"args": {},
"headers": {
"Accept": "*/*",
- "Cookie":
"jwt-cookie=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJrZXkiOiJ1c2VyLWtleSIsImV4cCI6MTY5NTEyOTA0NH0.EiktFX7di_tBbspbjmqDKoWAD9JG39Wo_CAQ1LZ9voQ",
+ "Cookie":
"jwt-cookie=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJqYWNrLWtleSIsIm5iZiI6MTcyOTEzMjI3MX0.UEPXy5jpid624T1XpfjM0PLY73LZPjV3Qt8yZ92kVuU",
...
},
...
@@ -344,9 +344,15 @@ APISIX supports referencing system and user environment
variables configured thr
Save the key to an environment variable:
```shell
-JACK_JWT_AUTH_KEY=jack-key
+export JACK_JWT_SECRET=jack-hs256-secret-that-is-very-long
```
+:::tip
+
+If you are running APISIX in Docker, you should set the environment variable
using the `-e` flag when starting the container.
+
+:::
+
Create a Consumer `jack`:
```shell
@@ -357,7 +363,7 @@ curl "http://127.0.0.1:9180/apisix/admin/consumers"; -X PUT \
}'
```
-Create `jwt-auth` Credential for the Consumer and reference the environment
variable in the key:
+Create `jwt-auth` Credential for the Consumer and reference the environment
variable:
```shell
curl "http://127.0.0.1:9180/apisix/admin/consumers/jack/credentials"; -X PUT \
@@ -366,8 +372,9 @@ curl
"http://127.0.0.1:9180/apisix/admin/consumers/jack/credentials"; -X PUT \
"id": "cred-jack-jwt-auth",
"plugins": {
"jwt-auth": {
- "key": "$env://JACK_JWT_AUTH_KEY",
- "secret": "jack-hs256-secret"
+ # highlight-next-line
+ "key": "jack-key",
+ "secret": "$env://JACK_JWT_SECRET"
}
}
}'
@@ -393,10 +400,10 @@ curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
}'
```
-To issue a JWT for `jack`, you could use [JWT.io's
debugger](https://jwt.io/#debugger-io) or other utilities. If you are using
[JWT.io's debugger](https://jwt.io/#debugger-io), do the following:
+To issue a JWT for `jack`, you could use [JWT.io's JWT
encoder](https://jwt.io) or other utilities. If you are using [JWT.io's JWT
encoder](https://jwt.io), do the following:
-* Select __HS256__ in the __Algorithm__ dropdown.
-* Update the secret in the __Verify Signature__ section to be
`jack-hs256-secret`.
+* Fill in `HS256` as the algorithm.
+* Update the secret in the __Valid secret__ section to be
`jack-hs256-secret-that-is-very-long`.
* Update payload with Consumer key `jack-key`; and add `exp` or `nbf` in UNIX
timestamp.
Your payload should look similar to the following:
@@ -408,10 +415,10 @@ To issue a JWT for `jack`, you could use [JWT.io's
debugger](https://jwt.io/#deb
}
```
-Copy the generated JWT under the __Encoded__ section and save to a variable:
+Copy the generated JWT and save to a variable:
-```text
-jwt_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJqYWNrLWtleSIsIm5iZiI6MTcyOTEzMjI3MX0.0VDKUzNkSaa_H5g_rGNbNtDcKJ9fBGgcGC56AsVsV-I
+```shell
+export
jwt_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJqYWNrLWtleSIsIm5iZiI6MTcyOTEzMjI3MX0.UEPXy5jpid624T1XpfjM0PLY73LZPjV3Qt8yZ92kVuU
```
Sending request with JWT in the header:
@@ -420,23 +427,11 @@ Sending request with JWT in the header:
curl -i "http://127.0.0.1:9080/get"; -H "Authorization: ${jwt_token}"
```
-You should receive an `HTTP/1.1 200 OK` response similar to the following:
-
-```text
-{
- "args": {},
- "headers": {
- "Accept": "*/*",
- "Authorization":
"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE2OTUxMzMxNTUsImtleSI6Imp3dC1rZXkifQ.jiKuaAJqHNSSQCjXRomwnQXmdkC5Wp5VDPRsJlh1WAQ",
- ...
- },
- ...
-}
-```
+You should receive an `HTTP/1.1 200 OK` response.
### Manage Secrets in Secret Manager
-The following example demonstrates how to manage `jwt-auth` Consumer key in
[HashiCorp Vault](https://www.vaultproject.io) and reference it in Plugin
configuration.
+The following example demonstrates how to manage `jwt-auth` consumer key in
[HashiCorp Vault](https://www.vaultproject.io) and reference it in plugin
configuration.
Start a Vault development server in Docker:
@@ -463,13 +458,13 @@ You should see a response similar to the following:
Success! Enabled the kv secrets engine at: kv/
```
-Create a secret and configure the Vault address and other connection
information:
+Create a Secret and configure the Vault address and other connection
information. Update the Vault address accordingly:
```shell
curl "http://127.0.0.1:9180/apisix/admin/secrets/vault/jwt"; -X PUT \
- -H "X-API-KEY: ${admin_key}" \
+ -H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
- "uri": "https://127.0.0.1:8200"，
+ "uri": "https://127.0.0.1:8200";,
"prefix": "kv/apisix",
"token": "root"
}'
@@ -479,23 +474,23 @@ Create a Consumer `jack`:
```shell
curl "http://127.0.0.1:9180/apisix/admin/consumers"; -X PUT \
- -H "X-API-KEY: ${admin_key}" \
+ -H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"username": "jack"
}'
```
-Create `jwt-auth` Credential for the Consumer and reference the secret in the
key:
+Create `jwt-auth` Credential for the Consumer and reference the Secret:
```shell
curl "http://127.0.0.1:9180/apisix/admin/consumers/jack/credentials"; -X PUT \
- -H "X-API-KEY: ${admin_key}" \
+ -H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"id": "cred-jack-jwt-auth",
"plugins": {
"jwt-auth": {
- "key": "$secret://vault/jwt/jack/jwt-key",
- "secret": "vault-hs256-secret"
+ "key": "jwt-vault-key",
+ "secret": "$secret://vault/jwt/jack/jwt-secret"
}
}
}'
@@ -505,7 +500,7 @@ Create a Route with `jwt-auth` enabled:
```shell
curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
- -H "X-API-KEY: ${admin_key}" \
+ -H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"id": "jwt-route",
"uri": "/get",
@@ -521,10 +516,10 @@ curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
}'
```
-Set `jwt-auth` key value to be `jwt-vault-key` in Vault:
+Set `jwt-auth` key value to be `vault-hs256-secret-that-is-very-long` in Vault:
```shell
-docker exec -i vault sh -c "VAULT_TOKEN='root'
VAULT_ADDR='http://0.0.0.0:8200' vault kv put kv/apisix/jack
jwt-key=jwt-vault-key"
+docker exec -i vault sh -c "VAULT_TOKEN='root'
VAULT_ADDR='http://0.0.0.0:8200' vault kv put kv/apisix/jack
jwt-secret=vault-hs256-secret-that-is-very-long"
```
You should see a response similar to the following:
@@ -533,11 +528,11 @@ You should see a response similar to the following:
Success! Data written to: kv/apisix/jack
```
-To issue a JWT, you could use [JWT.io's debugger](https://jwt.io/#debugger-io)
or other utilities. If you are using [JWT.io's
debugger](https://jwt.io/#debugger-io), do the following:
+To issue a JWT, you could use [JWT.io's JWT encoder](https://jwt.io) or other
utilities. If you are using [JWT.io's JWT encoder](https://jwt.io), do the
following:
-* Select __HS256__ in the __Algorithm__ dropdown.
-* Update the secret in the __Verify Signature__ section to be
`vault-hs256-secret`.
-* Update payload with Consumer key `jwt-vault-key`; and add `exp` or `nbf` in
UNIX timestamp.
+* Fill in `HS256` as the algorithm.
+* Update the secret in the __Valid secret__ section to be
`vault-hs256-secret-that-is-very-long`.
+* Update payload with consumer key `jwt-vault-key`; and add `exp` or `nbf` in
UNIX timestamp.
Your payload should look similar to the following:
@@ -548,35 +543,23 @@ To issue a JWT, you could use [JWT.io's
debugger](https://jwt.io/#debugger-io) o
}
```
-Copy the generated JWT under the __Encoded__ section and save to a variable:
+Copy the generated JWT and save to a variable:
-```text
-jwt_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJqd3QtdmF1bHQta2V5IiwibmJmIjoxNzI5MTMyMjcxfQ.faiN93LNP1lGSXqAb4empNJKMRWop8-KgnU58VQn1EE
+```shell
+export
jwt_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJqd3QtdmF1bHQta2V5IiwibmJmIjoxNzI5MTMyMjcxfQ.i2pLj7QcQvnlSjB7iV5V522tIV43boQRtee7L0rwlkQ
```
-Sending request with the token as header:
+Send a request with the token in the header:
```shell
curl -i "http://127.0.0.1:9080/get"; -H "Authorization: ${jwt_token}"
```
-You should receive an `HTTP/1.1 200 OK` response similar to the following:
-
-```text
-{
- "args": {},
- "headers": {
- "Accept": "*/*",
- "Authorization":
"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJqd3QtdmF1bHQta2V5IiwiZXhwIjoxNjk1MTM4NjM1fQ.Au2liSZ8eQXUJR3SJESwNlIfqZdNyRyxIJK03L4dk_g",
- ...
- },
- ...
-}
-```
+You should receive an `HTTP/1.1 200 OK` response.
### Sign JWT with RS256 Algorithm
-The following example demonstrates how you can use asymmetric algorithms, such
as RS256, to sign and validate JWT when implementing JWT for Consumer
authentication. You will be generating RSA key pairs using
[openssl](https://openssl-library.org/source/) and generating JWT using
[JWT.io](https://jwt.io/#debugger-io) to better understand the composition of
JWT.
+The following example demonstrates how you can use asymmetric algorithms, such
as RS256, to sign and validate JWT when implementing JWT for Consumer
authentication. You will be generating RSA key pairs using
[openssl](https://openssl-library.org/source/) and generating JWT using
[JWT.io](https://jwt.io) to better understand the composition of JWT.
Generate a 2048-bit RSA private key and extract the corresponding public key
in PEM format:
@@ -587,28 +570,25 @@ openssl rsa -in jwt-rsa256-private.pem -pubout -out
jwt-rsa256-public.pem
You should see `jwt-rsa256-private.pem` and `jwt-rsa256-public.pem` generated
in your current working directory.
-Visit [JWT.io's debugger](https://jwt.io/#debugger-io) and do the following:
+Visit [JWT.io's JWT encoder](https://jwt.io) and do the following:
-* Select __RS256__ in the __Algorithm__ dropdown.
-* Copy and paste the key content into the __Verify Signature__ section.
-* Update the payload with `key` matching the Consumer key you would like to
use; and `exp` or `nbf` in UNIX timestamp.
+* Fill in `RS256` as the algorithm.
+* Copy and paste the private key content into the __SIGN JWT: PRIVATE KEY__
section.
+* Update payload with Consumer key `jack-key`; and add `exp` or `nbf` in UNIX
timestamp.
-The configuration should look similar to the following:
+ Your payload should look similar to the following:
-<br />
-<div style={{textAlign: 'center'}}>
-<img
- src="https://static.apiseven.com/uploads/2024/12/12/SRe7AXMw_jwt_token.png";
- alt="complete configuration of JWT generation on jwt.io"
- width="70%"
-/>
-</div>
-<br />
+ ```json
+ {
+ "key": "jack-key",
+ "nbf": 1729132271
+ }
+ ```
-Copy the JWT on the left and save to an environment variable:
+Copy the generated JWT and save to a variable:
```shell
-jwt_token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJqYWNrLWtleSIsImV4cCI6MTczNDIzMDQwMH0.XjqM0oszmCggwZs-8PUIlJv8wPJON1la2ET5v70E6TCE32Yq5ibrl-1azaK7IreAer3HtnVHeEfII2rR02v8xfR1TPIjU_oHov4qC-A4tLTbgqGVXI7fCy2WFm3PFh6MEKuRe6M3dCQtCAdkRRQrBr1gWFQZhV3TNeMmmtyIfuJpB7cp4DW5pYFsCcoE1Nw6Tz7dt8k0tPBTPI2Mv9AYfMJ30LHDscOaPNtz8YIk_TOkV9b9mhQudUJ7J_suCZMRxD3iL655jTp2gKsstGKdZa0_W9Reu4-HY3LSc5DS1XtfjuftpuUqgg9FvPU0mK_b0wT_Rq3lbYhcHb9GZ72qiQ
+export
jwt_token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJqYWNrLWtleSIsIm5iZiI6MTcyOTEzMjI3MX0.K-I13em84kAcyH1jfIJl7ls_4jlwg1GzEzo5_xrDu-3wt3Xa3irS6naUsWpxX-a-hmcZZxRa9zqunqQjUP4kvn5e3xg2f_KyCR-_ZbwqYEPk3bXeFV1l4iypv6z5L7W1Niharun-dpMU03b1Tz64vhFx6UwxNL5UIZ7bunDAo_BXZ7Xe8rFhNHvIHyBFsDEXIBgx8lNYMq8QJk3iKxZhZZ5Om7lgYjOOKRgew4WkhBAY0v1AkO77nTlvSK0OEeeiwhkROyntggyx-S-U222ykMQ6mBLxkP4Cq5qHwXD8AUcLk5mhEij-3QhboYnt7yhKeZ3wDSpcjDvvL2aasC25ng
```
Create a Consumer `jack`:
@@ -632,8 +612,8 @@ curl
"http://127.0.0.1:9180/apisix/admin/consumers/jack/credentials"; -X PUT \
"jwt-auth": {
"key": "jack-key",
"algorithm": "RS256",
- "public_key": "-----BEGIN PUBLIC
KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAnE0h4k/GWfEbYO/yE2MPjHtNKDLNz4mv1KNIPLxY2ccjPYOtjuug+iZ4MujLV59YfrHriTs0H8jweQfff3pRSMjyEK+4qWTY3TeKBXIEa3pVDeoedSJrgjLBVio6xH7et8ir+QScScfLaJHGB4/l3DDGyEhO782a9teY8brn5hsWX5uLmDJvxtTGAHYi847XOcx2UneW4tZ8wQ6JGBSiSg5qAHan4dFZ7CpixCNNqEcSK6EQ7lKOLeFGG8ys/dHBIEasU4oMlCuJH77+XQQ/shchy+vm9oZfP+grLZkV+nKAd8MQZsid7ZJ/fiB/BmnhGrjtIfh98jwxSx4DgdLhdwIDAQAB\n-----END
PUBLIC KEY-----",
- "private_key": "-----BEGIN PRIVATE
KEY-----\nMIIEvwIBADANBgkqhkiG9w0BAQEFAASCBKkwggSlAgEAAoIBAQCcTSHiT8ZZ8Rtg7/ITYw+Me00oMs3Pia/Uo0g8vFjZxyM9g62O66D6Jngy6MtXn1h+seuJOzQfyPB5B99/elFIyPIQr7ipZNjdN4oFcgRrelUN6h51ImuCMsFWKjrEft63yKv5BJxJx8tokcYHj+XcMMbISE7vzZr215jxuufmGxZfm4uYMm/G1MYAdiLzjtc5zHZSd5bi1nzBDokYFKJKDmoAdqfh0VnsKmLEI02oRxIroRDuUo4t4UYbzKz90cEgRqxTigyUK4kfvv5dBD+yFyHL6+b2hl8/6CstmRX6coB3wxBmyJ3tkn9+IH8GaeEauO0h+H3yPDFLHgOB0uF3AgMBAAECggEARpY68Daw0Funzq5uN70r/3iLztSqx8hZpQE
[...]
+ "public_key": "-----BEGIN PUBLIC
KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAoTxe7ZPycrEP0SK4OBA2\n0OUQsDN9gSFSHVvx/t++nZNrFxzZnV6q6/TRsihNXUIgwaOu5icFlIcxPL9Mf9UJ\na5/XCQExp1TxpuSmjkhIFAJ/x5zXrC8SGTztP3SjkhYnQO9PKVXI6ljwgakVCfpl\numuTYqI+ev7e45NdK8gJoJxPp8bPMdf8/nHfLXZuqhO/btrDg1x+j7frDNrEw+6B\nCK2SsuypmYN+LwHfaH4Of7MQFk3LNIxyBz0mdbsKJBzp360rbWnQeauWtDymZxLT\nATRNBVyl3nCNsURRTkc7eyknLaDt2N5xTIoUGHTUFYSdE68QWmukYMVGcEHEEPkp\naQIDAQAB\n-----END
PUBLIC KEY-----"
+ # highlight-end
}
}
}'
@@ -641,7 +621,7 @@ curl
"http://127.0.0.1:9180/apisix/admin/consumers/jack/credentials"; -X PUT \
:::tip
-You should add a newline character after the opening line and before the
closing line, for example `-----BEGIN PRIVATE KEY-----\n......\n-----END
PRIVATE KEY-----`.
+You should add a newline character after the opening line and before the
closing line, for example `-----BEGIN PUBLIC KEY-----\n......\n-----END PUBLIC
KEY-----`.
The key content can be directly concatenated.
@@ -673,17 +653,7 @@ To verify, send a request to the Route with the JWT in the
`Authorization` heade
curl -i "http://127.0.0.1:9080/headers"; -H "Authorization: ${jwt_token}"
```
-You should receive an `HTTP/1.1 200 OK` response similar to the following:
-
-```json
-{
- "headers": {
- "Accept": "*/*",
- "Authorization":
"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJqYWNrLWtleSIsImV4cCI6MTczNDIzMDQwMH0.XjqM0oszmCggwZs-8PUIlJv8wPJON1la2ET5v70E6TCE32Yq5ibrl-1azaK7IreAer3HtnVHeEfII2rR02v8xfR1TPIjU_oHov4qC-A4tLTbgqGVXI7fCy2WFm3PFh6MEKuRe6M3dCQtCAdkRRQrBr1gWFQZhV3TNeMmmtyIfuJpB7cp4DW5pYFsCcoE1Nw6Tz7dt8k0tPBTPI2Mv9AYfMJ30LHDscOaPNtz8YIk_TOkV9b9mhQudUJ7J_suCZMRxD3iL655jTp2gKsstGKdZa0_W9Reu4-HY3LSc5DS1XtfjuftpuUqgg9FvPU0mK_b0wT_Rq3lbYhcHb9GZ72qiQ",
- ...
- }
-}
-```
+You should receive an `HTTP/1.1 200 OK` response.
### Add Consumer Custom ID to Header
@@ -712,7 +682,7 @@ curl
"http://127.0.0.1:9180/apisix/admin/consumers/jack/credentials"; -X PUT \
"plugins": {
"jwt-auth": {
"key": "jack-key",
- "secret": "jack-hs256-secret"
+ "secret": "jack-hs256-secret-that-is-very-long"
}
}
}'
@@ -738,10 +708,10 @@ curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
}'
```
-To issue a JWT for `jack`, you could use [JWT.io's
debugger](https://jwt.io/#debugger-io) or other utilities. If you are using
[JWT.io's debugger](https://jwt.io/#debugger-io), do the following:
+To issue a JWT for `jack`, you could use [JWT.io's JWT
encoder](https://jwt.io) or other utilities. If you are using [JWT.io's JWT
encoder](https://jwt.io), do the following:
-* Select __HS256__ in the __Algorithm__ dropdown.
-* Update the secret in the __Verify Signature__ section to be
`jack-hs256-secret`.
+* Fill in `HS256` as the algorithm.
+* Update the secret in the __Valid secret__ section to be
`jack-hs256-secret-that-is-very-long`.
* Update payload with Consumer key `jack-key`; and add `exp` or `nbf` in UNIX
timestamp.
Your payload should look similar to the following:
@@ -753,10 +723,10 @@ To issue a JWT for `jack`, you could use [JWT.io's
debugger](https://jwt.io/#deb
}
```
-Copy the generated JWT under the __Encoded__ section and save to a variable:
+Copy the generated JWT and save to a variable:
-```text
-jwt_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJqYWNrLWtleSIsIm5iZiI6MTcyOTEzMjI3MX0.0VDKUzNkSaa_H5g_rGNbNtDcKJ9fBGgcGC56AsVsV-I
+```shell
+export
jwt_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJqYWNrLWtleSIsIm5iZiI6MTcyOTEzMjI3MX0.UEPXy5jpid624T1XpfjM0PLY73LZPjV3Qt8yZ92kVuU
```
To verify, send a request to the Route with the JWT in the `Authorization`
header:
@@ -765,19 +735,19 @@ To verify, send a request to the Route with the JWT in
the `Authorization` heade
curl -i "http://127.0.0.1:9080/headers"; -H "Authorization: ${jwt_token}"
```
-You should see an `HTTP/1.1 200 OK` response similar to the following, where
`X-Consumer-Custom-Id` is attached:
+You should see an `HTTP/1.1 200 OK` response similar to the following:
```json
{
"headers": {
"Accept": "*/*",
- "Authorization":
"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE3MjY2NDk2NDAsImtleSI6ImphY2sta2V5In0.kdhumNWrZFxjUvYzWLt4lFr546PNsr9TXuf0Az5opoM",
+ "Authorization":
"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJqYWNrLWtleSIsIm5iZiI6MTcyOTEzMjI3MX0.UEPXy5jpid624T1XpfjM0PLY73LZPjV3Qt8yZ92kVuU",
"Host": "127.0.0.1",
"User-Agent": "curl/8.6.0",
- "X-Amzn-Trace-Id": "Root=1-66ea951a-4d740d724bd2a44f174d4daf",
+ "X-Amzn-Trace-Id": "Root=1-6873b19d-329331db76e5e7194c942b47",
+ "X-Consumer-Custom-Id": "495aec6a",
"X-Consumer-Username": "jack",
"X-Credential-Identifier": "cred-jack-jwt-auth",
- "X-Consumer-Custom-Id": "495aec6a",
"X-Forwarded-Host": "127.0.0.1"
}
}
@@ -814,7 +784,7 @@ curl
"http://127.0.0.1:9180/apisix/admin/consumers/jack/credentials"; -X PUT \
"plugins": {
"jwt-auth": {
"key": "jack-key",
- "secret": "jack-hs256-secret"
+ "secret": "jack-hs256-secret-that-is-very-long"
}
}
}'
@@ -859,11 +829,11 @@ curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
}'
```
-To issue a JWT for `jack`, you could use [JWT.io's
debugger](https://jwt.io/#debugger-io) or other utilities. If you are using
[JWT.io's debugger](https://jwt.io/#debugger-io), do the following:
+To issue a JWT for `jack`, you could use [JWT.io's JWT
encoder](https://jwt.io) or other utilities. If you are using [JWT.io's JWT
encoder](https://jwt.io), do the following:
-* Select __HS256__ in the __Algorithm__ dropdown.
-* Update the secret in the __Verify Signature__ section to be
`jack-hs256-secret`.
-* Update payload with role `user`, permission `read`, and Consumer key
`jack-key`; as well as `exp` or `nbf` in UNIX timestamp.
+* Fill in `HS256` as the algorithm.
+* Update the secret in the __Valid secret__ section to be
`jack-hs256-secret-that-is-very-long`.
+* Update payload with Consumer key `jack-key`; and add `exp` or `nbf` in UNIX
timestamp.
Your payload should look similar to the following:
@@ -874,10 +844,10 @@ To issue a JWT for `jack`, you could use [JWT.io's
debugger](https://jwt.io/#deb
}
```
-Copy the generated JWT under the __Encoded__ section and save to a variable:
+Copy the generated JWT and save to a variable:
```shell
-jwt_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJqYWNrLWtleSIsIm5iZiI6MTcyOTEzMjI3MX0.hjtSsEILpko14zb8-ibyxrB2tA5biYY9JrFm3do69vs
+export
jwt_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJqYWNrLWtleSIsIm5iZiI6MTcyOTEzMjI3MX0.UEPXy5jpid624T1XpfjM0PLY73LZPjV3Qt8yZ92kVuU
```
To verify the rate limiting, send five consecutive requests with `jack`'s JWT:
diff --git a/docs/zh/latest/plugins/jwt-auth.md
b/docs/zh/latest/plugins/jwt-auth.md
index 8977d8283..de4ca1c12 100644
--- a/docs/zh/latest/plugins/jwt-auth.md
+++ b/docs/zh/latest/plugins/jwt-auth.md
@@ -45,7 +45,7 @@ Consumer/Credential 端：
| key | string | 是 | | |
消费者的唯一密钥。 |
| secret | string | 否 | | |
当使用对称算法时，用于对 JWT 进行签名和验证的共享密钥。使用 `HS256` 或 `HS512`
作为算法时必填。如果未指定，后台将会自动生成。该字段支持使用 [APISIX Secret](../terminology/secret.md)
资源，将值保存在 Secret Manager 中。 |
| public_key | string | 否 | | | RSA
或 ECDSA 公钥， `algorithm` 属性选择 `RS256` 或 `ES256` 算法时必选。该字段支持使用 [APISIX
Secret](../terminology/secret.md) 资源，将值保存在 Secret Manager 中。 |
-| algorithm | string | 否 | "HS256" | ["HS256", "HS512", "RS256",
"ES256"] | 加密算法。
|
+| algorithm | string | 否 | "HS256" | ["HS256","HS512","RS256","ES256"]
| 加密算法。
|
| exp | integer | 否 | 86400 | [1,...] |
token 的超时时间。
|
| base64_secret | boolean | 否 | false | |
当设置为 `true` 时，密钥为 base64 编码。
|
| lifetime_grace_period | integer | 否 | 0 | [0,...] |
宽限期（以秒为单位）。用于解决生成 JWT 的服务器与验证 JWT 的服务器之间的时钟偏差。 |
@@ -83,7 +83,7 @@ admin_key=$(yq '.deployment.admin.admin_key[0].key'
conf/config.yaml | sed 's/"/
### 使用 JWT 进行消费者身份验证
-以下示例演示如何实现 JWT 进行消费者密钥身份验证。
+以下示例演示了如何使用 JWT 进行消费者密钥身份验证。
创建消费者 `jack`：
@@ -105,7 +105,7 @@ curl
"http://127.0.0.1:9180/apisix/admin/consumers/jack/credentials"; -X PUT \
"plugins": {
"jwt-auth": {
"key": "jack-key",
- "secret": "jack-hs256-secret"
+ "secret": "jack-hs256-secret-that-is-very-long"
}
}
}'
@@ -131,11 +131,11 @@ curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
}'
```
-要为 `jack` 签发 JWT，您可以使用 [JWT.io 的调试器](https://jwt.io/#debugger-io)
或其他实用程序。如果您使用的是 [JWT.io 的调试器](https://jwt.io/#debugger-io)，请执行以下操作：
+要为 `jack` 颁发 JWT，您可以使用 [JWT.io 的 JWT 编码器](https://jwt.io) 或其他实用程序。如果您使用
[JWT.io 的 JWT 编码器](https://jwt.io)，请执行以下操作：
-* 在 __Algorithm__ 下拉菜单中选择 __HS256__。
-* 将 __Verify Signature__ 部分中的密钥更新为 `jack-hs256-secret`。
-* 使用消费者密钥 `jack-key` 更新有效 payload；并在 UNIX 时间戳中添加 `exp` 或 `nbf`。
+* 填写 `HS256` 作为算法。
+* 将 __Valid secret__ 部分中的密钥更新为 `jack-hs256-secret-that-is-very-long`。
+* 使用消费者密钥 `jack-key` 更新有效 payload；并添加 `exp` 或 `nbf` UNIX 时间戳。
您的 payload 应类似于以下内容：
@@ -146,10 +146,10 @@ curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
}
```
-将生成的 JWT 复制到 __Encoded__ 部分并保存到变量中：
+将生成的 JWT 保存到变量中：
-```text
-jwt_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJqYWNrLWtleSIsIm5iZiI6MTcyOTEzMjI3MX0.0VDKUzNkSaa_H5g_rGNbNtDcKJ9fBGgcGC56AsVsV-I
+```shell
+export
jwt_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJqYWNrLWtleSIsIm5iZiI6MTcyOTEzMjI3MX0.UEPXy5jpid624T1XpfjM0PLY73LZPjV3Qt8yZ92kVuU
```
使用 `Authorization` 标头中的 JWT 向路由发送请求：
@@ -160,7 +160,7 @@ curl -i "http://127.0.0.1:9080/headers"; -H "Authorization:
${jwt_token}"
您应该收到类似于以下内容的 `HTTP/1.1 200 OK` 响应：
-```text
+```json
{
"headers": {
"Accept": "*/*",
@@ -175,10 +175,10 @@ curl -i "http://127.0.0.1:9080/headers"; -H
"Authorization: ${jwt_token}"
}
```
-30 秒后，令牌将过期。使用相同令牌发送请求以验证：
+使用无效的令牌发送请求以验证：
```shell
-curl -i "http://127.0.0.1:9080/headers"; -H "Authorization: ${jwt_token}"
+curl -i "http://127.0.0.1:9080/headers"; -H "Authorization:
eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE3MjY2NDk2NDAsImtleSI6ImphY2sta2V5In0.kdhumNWrZFxjU_random_random"
```
您应该收到类似于以下内容的 `HTTP/1.1 401 Unauthorized` 响应：
@@ -211,7 +211,7 @@ curl
"http://127.0.0.1:9180/apisix/admin/consumers/jack/credentials"; -X PUT \
"plugins": {
"jwt-auth": {
"key": "jack-key",
- "secret": "jack-hs256-secret"
+ "secret": "jack-hs256-secret-that-is-very-long"
}
}
}'
@@ -241,13 +241,13 @@ curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
}'
```
-要为 `jack` 签发 JWT，您可以使用 [JWT.io 的调试器](https://jwt.io/#debugger-io)
或其他实用程序。如果您使用的是 [JWT.io 的调试器](https://jwt.io/#debugger-io)，请执行以下操作：
+要为 `jack` 颁发 JWT，您可以使用 [JWT.io 的 JWT 编码器](https://jwt.io) 或其他实用程序。如果您使用
[JWT.io 的 JWT 编码器](https://jwt.io)，请执行以下操作：
-* 在 __Algorithm__ 下拉菜单中选择 __HS256__。
-* 将 __Verify Signature__ 部分中的密钥更新为 `jack-hs256-secret`。
-* 使用消费者密钥 `jack-key` 更新有效 payload；并在 UNIX 时间戳中添加 `exp` 或 `nbf`。
+* 填写 `HS256` 作为算法。
+* 将 __Valid secret__ 部分中的密钥更新为 `jack-hs256-secret-that-is-very-long`。
+* 使用消费者密钥 `jack-key` 更新有效 payload；并添加 `exp` 或 `nbf` UNIX 时间戳。
- 您的有效 payload 应类似于以下内容：
+ 您的 payload 应类似于以下内容：
```json
{
@@ -256,10 +256,10 @@ curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
}
```
-将生成的 JWT 复制到 __Encoded__ 部分并保存到变量中：
+将生成的 JWT 保存到变量中：
-```text
-jwt_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJqYWNrLWtleSIsIm5iZiI6MTcyOTEzMjI3MX0.0VDKUzNkSaa_H5g_rGNbNtDcKJ9fBGgcGC56AsVsV-I
+```shell
+export
jwt_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJqYWNrLWtleSIsIm5iZiI6MTcyOTEzMjI3MX0.UEPXy5jpid624T1XpfjM0PLY73LZPjV3Qt8yZ92kVuU
```
#### 使用标头中的 JWT 进行验证
@@ -272,13 +272,13 @@ curl -i "http://127.0.0.1:9080/get"; -H "jwt-auth-header:
${jwt_token}"
您应该收到类似于以下内容的 `HTTP/1.1 200 OK` 响应：
-```text
+```json
{
"args": {},
"headers": {
"Accept": "*/*",
"Host": "127.0.0.1",
- "Jwt-Auth-Header":
"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJrZXkiOiJ1c2VyLWtleSIsImV4cCI6MTY5NTEyOTA0NH0.EiktFX7di_tBbspbjmqDKoWAD9JG39Wo_CAQ1LZ9voQ",
+ "Jwt-Auth-Header":
"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJqYWNrLWtleSIsIm5iZiI6MTcyOTEzMjI3MX0.UEPXy5jpid624T1XpfjM0PLY73LZPjV3Qt8yZ92kVuU",
...
},
...
@@ -295,10 +295,10 @@ curl -i "http://127.0.0.1:9080/get?jwt-query=${jwt_token}";
您应该收到类似于以下内容的 `HTTP/1.1 200 OK` 响应：
-```text
+```json
{
"args": {
- "jwt-query":
"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJrZXkiOiJ1c2VyLWtleSIsImV4cCI6MTY5NTEyOTA0NH0.EiktFX7di_tBbspbjmqDKoWAD9JG39Wo_CAQ1LZ9voQ"
+ "jwt-query":
"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJqYWNrLWtleSIsIm5iZiI6MTcyOTEzMjI3MX0.UEPXy5jpid624T1XpfjM0PLY73LZPjV3Qt8yZ92kVuU"
},
"headers": {
"Accept": "*/*",
@@ -319,19 +319,19 @@ curl -i "http://127.0.0.1:9080/get"; --cookie
jwt-cookie=${jwt_token}
您应该收到类似于以下内容的 `HTTP/1.1 200 OK` 响应：
-```text
+```json
{
"args": {},
"headers": {
"Accept": "*/*",
- "Cookie":
"jwt-cookie=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJrZXkiOiJ1c2VyLWtleSIsImV4cCI6MTY5NTEyOTA0NH0.EiktFX7di_tBbspbjmqDKoWAD9JG39Wo_CAQ1LZ9voQ",
+ "Cookie":
"jwt-cookie=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJqYWNrLWtleSIsIm5iZiI6MTcyOTEzMjI3MX0.UEPXy5jpid624T1XpfjM0PLY73LZPjV3Qt8yZ92kVuU",
...
},
...
}
```
-### 管理环境变量中的机密
+### 在环境变量中管理密钥
以下示例演示了如何将 `jwt-auth` 消费者密钥保存到环境变量并在配置中引用它。
@@ -340,9 +340,15 @@ APISIX 支持引用通过 [NGINX `env`
指令](https://nginx.org/en/docs/ngx_cor
将密钥保存到环境变量中：
```shell
-JACK_JWT_AUTH_KEY=jack-key
+export JACK_JWT_SECRET=jack-hs256-secret-that-is-very-long
```
+:::tip
+
+如果您在 Docker 中运行 APISIX，需要在启动容器时使用 `-e` flag 设置环境变量。
+
+:::
+
创建一个消费者 `jack`：
```shell
@@ -353,7 +359,7 @@ curl "http://127.0.0.1:9180/apisix/admin/consumers"; -X PUT \
}'
```
-为消费者创建 `jwt-auth` 凭证并在密钥中引用环境变量：
+为消费者创建 `jwt-auth` 凭证并引用环境变量：
```shell
curl "http://127.0.0.1:9180/apisix/admin/consumers/jack/credentials"; -X PUT \
@@ -362,14 +368,15 @@ curl
"http://127.0.0.1:9180/apisix/admin/consumers/jack/credentials"; -X PUT \
"id": "cred-jack-jwt-auth",
"plugins": {
"jwt-auth": {
- "key": "$env://JACK_JWT_AUTH_KEY",
- "secret": "jack-hs256-secret"
+ # highlight-next-line
+ "key": "jack-key",
+ "secret": "$env://JACK_JWT_SECRET"
}
}
}'
```
-创建路由并启用 `jwt-auth`：
+创建启用 `jwt-auth` 的路由：
```shell
curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
@@ -389,13 +396,13 @@ curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
}'
```
-要为 `jack` 签发 JWT，您可以使用 [JWT.io 的调试器](https://jwt.io/#debugger-io)
或其他实用程序。如果您使用 [JWT.io 的调试器](https://jwt.io/#debugger-io)，请执行以下操作：
+要为 `jack` 颁发 JWT，您可以使用 [JWT.io 的 JWT 编码器](https://jwt.io) 或其他实用程序。如果您使用
[JWT.io 的 JWT 编码器](https://jwt.io)，请执行以下操作：
-* 在 __Algorithm__ 下拉列表中选择 __HS256__。
-* 将 __Verify Signature__ 部分中的密钥更新为 `jack-hs256-secret` 。
-* 使用消费者密钥 `jack-key` 更新有效 payload；并在 UNIX 时间戳中添加 `exp` 或 `nbf`。
+* 填写 `HS256` 作为算法。
+* 将 __Valid secret__ 部分中的密钥更新为 `jack-hs256-secret-that-is-very-long`。
+* 使用消费者密钥 `jack-key` 更新有效 payload；并添加 `exp` 或 `nbf` UNIX 时间戳。
- 您的有效 payload 应类似于以下内容：
+ 您的 payload 应类似于以下内容：
```json
{
@@ -404,10 +411,10 @@ curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
}
```
-将生成的 JWT 复制到 __Encoded__ 部分并保存到变量中：
+将生成的 JWT 保存到变量中：
-```text
-jwt_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJqYWNrLWtleSIsIm5iZiI6MTcyOTEzMjI3MX0.0VDKUzNkSaa_H5g_rGNbNtDcKJ9fBGgcGC56AsVsV-I
+```shell
+export
jwt_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJqYWNrLWtleSIsIm5iZiI6MTcyOTEzMjI3MX0.UEPXy5jpid624T1XpfjM0PLY73LZPjV3Qt8yZ92kVuU
```
发送标头中包含 JWT 的请求：
@@ -416,23 +423,11 @@
jwt_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJqYWNrLWtleSIsIm5iZiI6M
curl -i "http://127.0.0.1:9080/get"; -H "Authorization: ${jwt_token}"
```
-您应该收到类似于以下内容的 `HTTP/1.1 200 OK` 响应：
-
-```text
-{
- "args": {},
- "headers": {
- "Accept": "*/*",
- "Authorization":
"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE2OTUxMzMxNTUsImtleSI6Imp3dC1rZXkifQ.jiKuaAJqHNSSQCjXRomwnQXmdkC5Wp5VDPRsJlh1WAQ",
- ...
- },
- ...
-}
-```
+您应该会收到 `HTTP/1.1 200 OK` 响应。
-### 在秘密管理器中管理秘密
+### 在 Secret Manager 中管理 Secret
-以下示例演示了如何管理 [HashiCorp Vault](https://www.vaultproject.io) 中的 `jwt-auth`
消费者密钥并在插件配置中引用它。
+以下示例演示了如何在 [HashiCorp Vault](https://www.vaultproject.io) 中管理 `jwt-auth`
消费者密钥，并在插件配置中引用它。
在 Docker 中启动 Vault 开发服务器：
@@ -447,61 +442,61 @@ docker run -d \
vault server -dev
```
-APISIX 目前支持 [Vault KV 引擎版本
1](https://developer.hashicorp.com/vault/docs/secrets/kv#kv-version-1)。在 Vault
中启用它：
+APISIX 目前支持 [Vault KV 引擎版本
1](https://developer.hashicorp.com/vault/docs/secrets/kv#kv-version-1)。请在 Vault
中启用它：
```shell
docker exec -i vault sh -c "VAULT_TOKEN='root'
VAULT_ADDR='http://0.0.0.0:8200' vault secrets enable -path=kv -version=1 kv"
```
-您应该看到类似于以下内容的响应：
+您应该会看到类似以下内容的响应：
```text
Success! Enabled the kv secrets engine at: kv/
```
-创建一个 secret 并配置 Vault 地址和其他连接信息：
+创建一个 Secret，并配置 Vault 地址和其他连接信息。根据情况相应地更新 Vault 地址：
```shell
curl "http://127.0.0.1:9180/apisix/admin/secrets/vault/jwt"; -X PUT \
- -H "X-API-KEY: ${admin_key}" \
+ -H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
- "uri": "https://127.0.0.1:8200"，
+ "uri": "https://127.0.0.1:8200";,
"prefix": "kv/apisix",
"token": "root"
}'
```
-创建一个消费者 `jack`：
+创建消费者 `jack`：
```shell
curl "http://127.0.0.1:9180/apisix/admin/consumers"; -X PUT \
- -H "X-API-KEY: ${admin_key}" \
+ -H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"username": "jack"
}'
```
-为消费者创建 `jwt-auth` 凭证并引用密钥中的秘密：
+为消费者创建 `jwt-auth` 凭证并引用 Secret：
```shell
curl "http://127.0.0.1:9180/apisix/admin/consumers/jack/credentials"; -X PUT \
- -H "X-API-KEY: ${admin_key}" \
+ -H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"id": "cred-jack-jwt-auth",
"plugins": {
"jwt-auth": {
- "key": "$secret://vault/jwt/jack/jwt-key",
- "secret": "vault-hs256-secret"
+ "key": "jwt-vault-key",
+ "secret": "$secret://vault/jwt/jack/jwt-secret"
}
}
}'
```
-创建路由并启用 `jwt-auth`：
+创建启用 `jwt-auth` 的路由：
```shell
curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
- -H "X-API-KEY: ${admin_key}" \
+ -H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"id": "jwt-route",
"uri": "/get",
@@ -517,25 +512,25 @@ curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
}'
```
-在 Vault 中将 `jwt-auth` 键值设置为 `jwt-vault-key`：
+在 Vault 中将 `jwt-auth` 键值设置为 `vault-hs256-secret-that-is-very-long`：
```shell
-docker exec -i vault sh -c "VAULT_TOKEN='root'
VAULT_ADDR='http://0.0.0.0:8200' vault kv put kv/apisix/jack
jwt-key=jwt-vault-key"
+docker exec -i vault sh -c "VAULT_TOKEN='root'
VAULT_ADDR='http://0.0.0.0:8200' vault kv put kv/apisix/jack
jwt-secret=vault-hs256-secret-that-is-very-long"
```
-您应该看到类似于以下内容的响应：
+您应该会看到类似以下内容的响应：
```text
Success! Data written to: kv/apisix/jack
```
-要签发 JWT，您可以使用 [JWT.io 的调试器](https://jwt.io/#debugger-io) 或其他实用程序。如果您使用 [JWT.io
的调试器](https://jwt.io/#debugger-io)，请执行以下操作：
+要为 `jack` 颁发 JWT，您可以使用 [JWT.io 的 JWT 编码器](https://jwt.io) 或其他实用程序。如果您使用
[JWT.io 的 JWT 编码器](https://jwt.io)，请执行以下操作：
-* 在 __Algorithm__ 下拉列表中选择 __HS256__。
-* 将 __Verify Signature__ 部分中的密钥更新为 `vault-hs256-secret` 。
-* 使用消费者密钥 `jwt-vault-key` 更新有效 payload；并在 UNIX 时间戳中添加 `exp` 或 `nbf`。
+* 填写 `HS256` 作为算法。
+* 将 __Valid secret__ 部分中的密钥更新为 `vault-hs256-secret-that-is-very-long`。
+* 使用消费者密钥 `jwt-vault-key` 更新有效 payload；并添加 `exp` 或 `nbf` UNIX 时间戳。
- 您的有效 payload 应类似于以下内容：
+ 您的 payload 应类似于以下内容：
```json
{
@@ -544,67 +539,52 @@ Success! Data written to: kv/apisix/jack
}
```
-将生成的 JWT 复制到 __Encoded__ 部分并保存到变量中：
+复制生成的 JWT 并保存到变量：
-```text
-jwt_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJqd3QtdmF1bHQta2V5IiwibmJmIjoxNzI5MTMyMjcxfQ.faiN93LNP1lGSXqAb4empNJKMRWop8-KgnU58VQn1EE
+```shell
+export
jwt_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJqd3QtdmF1bHQta2V5IiwibmJmIjoxNzI5MTMyMjcxfQ.i2pLj7QcQvnlSjB7iV5V522tIV43boQRtee7L0rwlkQ
```
-使用令牌作为标头发送请求：
+发送带有令牌作为标头的请求：
```shell
curl -i "http://127.0.0.1:9080/get"; -H "Authorization: ${jwt_token}"
```
-您应该收到类似于以下内容的 `HTTP/1.1 200 OK` 响应：
-
-```text
-{
- "args": {},
- "headers": {
- "Accept": "*/*",
- "Authorization":
"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJqd3QtdmF1bHQta2V5IiwiZXhwIjoxNjk1MTM4NjM1fQ.Au2liSZ8eQXUJR3SJESwNlIfqZdNyRyxIJK03L4dk_g",
- ...
- },
- ...
-}
-```
+您应该会收到 `HTTP/1.1 200 OK` 响应。
-### 使用 RS256 算法签署 JWT
+### 使用 RS256 算法签名 JWT
-以下示例演示了在实施 JWT 进行消费者身份验证时如何使用非对称算法（例如 RS256）来签名和验证 JWT。您将使用
[openssl](https://openssl-library.org/source/) 生成 RSA 密钥对，并使用
[JWT.io](https://jwt.io/#debugger-io) 生成 JWT，以更好地了解 JWT 的组成。
+以下示例演示了如何在实现 JWT 消费者身份验证时使用非对称算法（例如 RS256）对 JWT 进行签名和验证。您将使用
[openssl](https://openssl-library.org/source/) 生成 RSA 密钥对，并使用
[JWT.io](https://jwt.io) 生成 JWT，以便更好地理解 JWT 的组成。
-生成 2048 位的 RSA 私钥并提取对应的 PEM 格式的公钥：
+生成一个 2048 位 RSA 私钥，并提取相应的 PEM 格式公钥：
```shell
openssl genrsa -out jwt-rsa256-private.pem 2048
openssl rsa -in jwt-rsa256-private.pem -pubout -out jwt-rsa256-public.pem
```
-您应该会看到在当前工作目录中生成了 `jwt-rsa256-private.pem` 和 `jwt-rsa256-public.pem` 。
+您应该看到在当前工作目录中生成的 `jwt-rsa256-private.pem` 和 `jwt-rsa256-public.pem`。
-访问 [JWT.io 的调试器](https://jwt.io/#debugger-io) 并执行以下操作：
+访问 [JWT.io 的 JWT 编码器](https://jwt.io) 并执行以下操作：
-* 在 __Algorithm__ 下拉列表中选择 __RS256__。
-* 将 key 复制并粘贴到 __Verify Signature__ 部分。
-* 使用与您想要使用的消费者密钥匹配的 `key` 更新有效 payload；以及 UNIX 时间戳中的 `exp` 或 `nbf`。
+* 填写 `RS256` 作为算法。
+* 将私钥内容复制并粘贴到 __SIGN JWT: PRIVATE KEY__ 部分。
+* 使用消费者密钥 `jack-key` 更新有效负载；并添加 `exp` 或 `nbf` UNIX 时间戳。
-配置应类似于以下内容：
+ 您的 payload 应类似于以下内容：
-<br />
-<div style={{textAlign: 'center'}}>
-<img
- src="https://static.apiseven.com/uploads/2024/12/12/SRe7AXMw_jwt_token.png";
- alt="complete configuration of JWT generation on jwt.io"
- width="70%"
-/>
-</div>
-<br />
+ ```json
+ {
+ "key": "jack-key",
+ "nbf": 1729132271
+ }
+ ```
-复制左侧的 JWT 并保存到环境变量中：
+复制生成的 JWT 并保存到变量：
```shell
-jwt_token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJqYWNrLWtleSIsImV4cCI6MTczNDIzMDQwMH0.XjqM0oszmCggwZs-8PUIlJv8wPJON1la2ET5v70E6TCE32Yq5ibrl-1azaK7IreAer3HtnVHeEfII2rR02v8xfR1TPIjU_oHov4qC-A4tLTbgqGVXI7fCy2WFm3PFh6MEKuRe6M3dCQtCAdkRRQrBr1gWFQZhV3TNeMmmtyIfuJpB7cp4DW5pYFsCcoE1Nw6Tz7dt8k0tPBTPI2Mv9AYfMJ30LHDscOaPNtz8YIk_TOkV9b9mhQudUJ7J_suCZMRxD3iL655jTp2gKsstGKdZa0_W9Reu4-HY3LSc5DS1XtfjuftpuUqgg9FvPU0mK_b0wT_Rq3lbYhcHb9GZ72qiQ
+export
jwt_token=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJqYWNrLWtleSIsIm5iZiI6MTcyOTEzMjI3MX0.K-I13em84kAcyH1jfIJl7ls_4jlwg1GzEzo5_xrDu-3wt3Xa3irS6naUsWpxX-a-hmcZZxRa9zqunqQjUP4kvn5e3xg2f_KyCR-_ZbwqYEPk3bXeFV1l4iypv6z5L7W1Niharun-dpMU03b1Tz64vhFx6UwxNL5UIZ7bunDAo_BXZ7Xe8rFhNHvIHyBFsDEXIBgx8lNYMq8QJk3iKxZhZZ5Om7lgYjOOKRgew4WkhBAY0v1AkO77nTlvSK0OEeeiwhkROyntggyx-S-U222ykMQ6mBLxkP4Cq5qHwXD8AUcLk5mhEij-3QhboYnt7yhKeZ3wDSpcjDvvL2aasC25ng
```
创建一个消费者 `jack`：
@@ -628,8 +608,8 @@ curl
"http://127.0.0.1:9180/apisix/admin/consumers/jack/credentials"; -X PUT \
"jwt-auth": {
"key": "jack-key",
"algorithm": "RS256",
- "public_key": "-----BEGIN PUBLIC
KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAnE0h4k/GWfEbYO/yE2MPjHtNKDLNz4mv1KNIPLxY2ccjPYOtjuug+iZ4MujLV59YfrHriTs0H8jweQfff3pRSMjyEK+4qWTY3TeKBXIEa3pVDeoedSJrgjLBVio6xH7et8ir+QScScfLaJHGB4/l3DDGyEhO782a9teY8brn5hsWX5uLmDJvxtTGAHYi847XOcx2UneW4tZ8wQ6JGBSiSg5qAHan4dFZ7CpixCNNqEcSK6EQ7lKOLeFGG8ys/dHBIEasU4oMlCuJH77+XQQ/shchy+vm9oZfP+grLZkV+nKAd8MQZsid7ZJ/fiB/BmnhGrjtIfh98jwxSx4DgdLhdwIDAQAB\n-----END
PUBLIC KEY-----",
- "private_key": "-----BEGIN PRIVATE
KEY-----\nMIIEvwIBADANBgkqhkiG9w0BAQEFAASCBKkwggSlAgEAAoIBAQCcTSHiT8ZZ8Rtg7/ITYw+Me00oMs3Pia/Uo0g8vFjZxyM9g62O66D6Jngy6MtXn1h+seuJOzQfyPB5B99/elFIyPIQr7ipZNjdN4oFcgRrelUN6h51ImuCMsFWKjrEft63yKv5BJxJx8tokcYHj+XcMMbISE7vzZr215jxuufmGxZfm4uYMm/G1MYAdiLzjtc5zHZSd5bi1nzBDokYFKJKDmoAdqfh0VnsKmLEI02oRxIroRDuUo4t4UYbzKz90cEgRqxTigyUK4kfvv5dBD+yFyHL6+b2hl8/6CstmRX6coB3wxBmyJ3tkn9+IH8GaeEauO0h+H3yPDFLHgOB0uF3AgMBAAECggEARpY68Daw0Funzq5uN70r/3iLztSqx8hZpQE
[...]
+ "public_key": "-----BEGIN PUBLIC
KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAoTxe7ZPycrEP0SK4OBA2\n0OUQsDN9gSFSHVvx/t++nZNrFxzZnV6q6/TRsihNXUIgwaOu5icFlIcxPL9Mf9UJ\na5/XCQExp1TxpuSmjkhIFAJ/x5zXrC8SGTztP3SjkhYnQO9PKVXI6ljwgakVCfpl\numuTYqI+ev7e45NdK8gJoJxPp8bPMdf8/nHfLXZuqhO/btrDg1x+j7frDNrEw+6B\nCK2SsuypmYN+LwHfaH4Of7MQFk3LNIxyBz0mdbsKJBzp360rbWnQeauWtDymZxLT\nATRNBVyl3nCNsURRTkc7eyknLaDt2N5xTIoUGHTUFYSdE68QWmukYMVGcEHEEPkp\naQIDAQAB\n-----END
PUBLIC KEY-----"
+ # highlight-end
}
}
}'
@@ -637,9 +617,9 @@ curl
"http://127.0.0.1:9180/apisix/admin/consumers/jack/credentials"; -X PUT \
:::tip
-您应该在开始行之后和结束行之前添加换行符，例如`-----BEGIN PRIVATE KEY-----\n......\n-----END PRIVATE
KEY -----`。
+您应该在起始行之后和结束行之前添加换行符，例如 `-----BEGIN PUBLIC KEY-----\n......\n-----END PUBLIC
KEY-----`。
-关键内容可以直接拼接。
+密钥内容可以直接连接。
:::
@@ -669,21 +649,11 @@ curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
curl -i "http://127.0.0.1:9080/headers"; -H "Authorization: ${jwt_token}"
```
-您应该收到类似于以下内容的 `HTTP/1.1 200 OK` 响应：
-
-```json
-{
- "headers": {
- "Accept": "*/*",
- "Authorization":
"eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJqYWNrLWtleSIsImV4cCI6MTczNDIzMDQwMH0.XjqM0oszmCggwZs-8PUIlJv8wPJON1la2ET5v70E6TCE32Yq5ibrl-1azaK7IreAer3HtnVHeEfII2rR02v8xfR1TPIjU_oHov4qC-A4tLTbgqGVXI7fCy2WFm3PFh6MEKuRe6M3dCQtCAdkRRQrBr1gWFQZhV3TNeMmmtyIfuJpB7cp4DW5pYFsCcoE1Nw6Tz7dt8k0tPBTPI2Mv9AYfMJ30LHDscOaPNtz8YIk_TOkV9b9mhQudUJ7J_suCZMRxD3iL655jTp2gKsstGKdZa0_W9Reu4-HY3LSc5DS1XtfjuftpuUqgg9FvPU0mK_b0wT_Rq3lbYhcHb9GZ72qiQ",
- ...
- }
-}
-```
+您应该会收到 `HTTP/1.1 200 OK` 响应。
### 将消费者自定义 ID 添加到标头
-以下示例演示了如何将消费者自定义 ID 附加到 `Consumer-Custom-Id` 标头中经过身份验证的请求，该标头可用于根据需要实现其他逻辑。
+以下示例演示了如何在 `Consumer-Custom-Id` 标头中将消费者自定义 ID 附加到已验证的请求，该 ID 可用于根据需要实现其他逻辑。
创建一个带有自定义 ID 标签的消费者 `jack`：
@@ -708,7 +678,7 @@ curl
"http://127.0.0.1:9180/apisix/admin/consumers/jack/credentials"; -X PUT \
"plugins": {
"jwt-auth": {
"key": "jack-key",
- "secret": "jack-hs256-secret"
+ "secret": "jack-hs256-secret-that-is-very-long"
}
}
}'
@@ -734,13 +704,13 @@ curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
}'
```
-要为 `jack` 签发 JWT，您可以使用 [JWT.io 的调试器](https://jwt.io/#debugger-io)
或其他实用程序。如果您使用的是 [JWT.io 的调试器](https://jwt.io/#debugger-io)，请执行以下操作：
+要为 `jack` 颁发 JWT，您可以使用 [JWT.io 的 JWT 编码器](https://jwt.io) 或其他实用程序。如果您使用
[JWT.io 的 JWT 编码器](https://jwt.io)，请执行以下操作：
-* 在 __Algorithm__ 下拉菜单中选择 __HS256__。
-* 将 __Verify Signature__ 部分中的密钥更新为 `jack-hs256-secret` 。
-* 使用消费者密钥 `jack-key` 更新有效 payload；并在 UNIX 时间戳中添加 `exp` 或 `nbf` 。
+* 填写 `HS256` 作为算法。
+* 将 __Valid secret__ 部分中的密钥更新为 `jack-hs256-secret-that-is-very-long`。
+* 使用消费者密钥 `jack-key` 更新有效 payload；并添加 `exp` 或 `nbf` UNIX 时间戳。
- 您的有效 payload 应类似于以下内容：
+ 您的 payload 应类似于以下内容：
```json
{
@@ -749,31 +719,31 @@ curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
}
```
-将生成的 JWT 复制到 __Encoded__ 部分并保存到变量中：
+复制生成的 JWT 并保存到变量：
-```text
-jwt_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJqYWNrLWtleSIsIm5iZiI6MTcyOTEzMjI3MX0.0VDKUzNkSaa_H5g_rGNbNtDcKJ9fBGgcGC56AsVsV-I
+```shell
+export
jwt_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJqYWNrLWtleSIsIm5iZiI6MTcyOTEzMjI3MX0.UEPXy5jpid624T1XpfjM0PLY73LZPjV3Qt8yZ92kVuU
```
-使用 `Authorization` 标头中的 JWT 向路由发送请求：
+为了验证，使用 `Authorization` 标头中的 JWT 向路由发送请求：
```shell
curl -i "http://127.0.0.1:9080/headers"; -H "Authorization: ${jwt_token}"
```
-您应该看到类似于以下内容的 `HTTP/1.1 200 OK` 响应，其中附加了 `X-Consumer-Custom-Id`：
+您应该会看到类似以下内容的 `HTTP/1.1 200 OK` 响应：
```json
{
"headers": {
"Accept": "*/*",
- "Authorization":
"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE3MjY2NDk2NDAsImtleSI6ImphY2sta2V5In0.kdhumNWrZFxjUvYzWLt4lFr546PNsr9TXuf0Az5opoM",
+ "Authorization":
"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJqYWNrLWtleSIsIm5iZiI6MTcyOTEzMjI3MX0.UEPXy5jpid624T1XpfjM0PLY73LZPjV3Qt8yZ92kVuU",
"Host": "127.0.0.1",
"User-Agent": "curl/8.6.0",
- "X-Amzn-Trace-Id": "Root=1-66ea951a-4d740d724bd2a44f174d4daf",
+ "X-Amzn-Trace-Id": "Root=1-6873b19d-329331db76e5e7194c942b47",
+ "X-Consumer-Custom-Id": "495aec6a",
"X-Consumer-Username": "jack",
"X-Credential-Identifier": "cred-jack-jwt-auth",
- "X-Consumer-Custom-Id": "495aec6a",
"X-Forwarded-Host": "127.0.0.1"
}
}
@@ -781,9 +751,9 @@ curl -i "http://127.0.0.1:9080/headers"; -H "Authorization:
${jwt_token}"
### 匿名消费者的速率限制
-以下示例演示了如何为普通消费者和匿名消费者配置不同的速率限制策略，其中匿名消费者不需要进行身份验证，并且配额较少。
+以下示例演示了如何为普通消费者和匿名消费者配置不同的速率限制策略，其中匿名消费者无需身份验证，且配额较少。
-创建一个普通消费者 `jack`，并配置 `limit-count` 插件，以允许 30 秒内的配额为 3：
+创建一个普通消费者 `jack`，并配置 `limit-count` 插件，允许在 30 秒内使用 3 个配额：
```shell
curl "http://127.0.0.1:9180/apisix/admin/consumers"; -X PUT \
@@ -810,7 +780,7 @@ curl
"http://127.0.0.1:9180/apisix/admin/consumers/jack/credentials"; -X PUT \
"plugins": {
"jwt-auth": {
"key": "jack-key",
- "secret": "jack-hs256-secret"
+ "secret": "jack-hs256-secret-that-is-very-long"
}
}
}'
@@ -855,13 +825,13 @@ curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
}'
```
-要为 `jack` 签发 JWT，您可以使用 [JWT.io 的调试器](https://jwt.io/#debugger-io)
或其他实用程序。如果您使用的是 [JWT.io 的调试器](https://jwt.io/#debugger-io)，请执行以下操作：
+要为 `jack` 颁发 JWT，您可以使用 [JWT.io 的 JWT 编码器](https://jwt.io) 或其他实用程序。如果您使用
[JWT.io 的 JWT 编码器](https://jwt.io)，请执行以下操作：
-* 在 __Algorithm__ 下拉菜单中选择 __HS256__。
-* 将 __Verify Signature__ 部分中的密钥更新为 `jack-hs256-secret`。
-* 使用角色 `user` 、权限 `read` 和消费者密钥 `jack-key` 以及 UNIX 时间戳中的 `exp` 或 `nbf` 更新有效
payload。
+* 填写 `HS256` 作为算法。
+* 将 __Valid secret__ 部分中的密钥更新为 `jack-hs256-secret-that-is-very-long`。
+* 使用消费者密钥 `jack-key` 更新有效 payload；并添加 `exp` 或 `nbf` UNIX 时间戳。
- 您的有效 payload 应类似于以下内容：
+ 您的 payload 应类似于以下内容：
```json
{
@@ -873,7 +843,7 @@ curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \
将生成的 JWT 复制到 __Encoded__ 部分并保存到变量中：
```shell
-jwt_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJqYWNrLWtleSIsIm5iZiI6MTcyOTEzMjI3MX0.hjtSsEILpko14zb8-ibyxrB2tA5biYY9JrFm3do69vs
+export
jwt_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJqYWNrLWtleSIsIm5iZiI6MTcyOTEzMjI3MX0.UEPXy5jpid624T1XpfjM0PLY73LZPjV3Qt8yZ92kVuU
```
为了验证速率限制，请使用 jack 的 JWT 连续发送五个请求：
![https://static.apiseven.com/uploads/2024/12/12/SRe7AXMw_jwt_token.png"](https://static.apiseven.com/uploads/2024/12/12/SRe7AXMw_jwt_token.png"){kind=link}