API Gateway:jwt-auth plugin

Authentication configuration

The following table describes the fields for each item in consumers.

• The following table describes the fields for each item in from_headers.

  Name	Data type	Required	Default value	Description
  name	string	Required	-	The request header from which the JWT is extracted.
  value_prefix	string	required	-	The prefix to remove from the header value. The remaining part is treated as the JWT.

• The following table describes the fields for each item in claims_to_headers.

  Name	Data type	Required	Default value	Description
  claim	string	Required	-	A specified field in the JWT payload. The value must be a string or unsigned integer.
  header	string	Required	-	The request header to populate with the extracted claim value and forward to the backend.
  override	bool	Optional	true	If true, overwrites the request header if it has the same name. If false, appends the value as a duplicate request header.

• The following table describes the fields for each item in remote_jwks.

  Name	Data type	Required	Default value	Description
  uri	string	Required	-	The request URL.
  service	string	Required	-	Example for a Kubernetes service: foo.default.svc.cluster.local. Example for a Nacos service: foo.DEFAULT-GROUP.public.nacos. For a DNS service named test, enter test.dns. For a static IP service named test, enter test.static.
  port	bool	Required	-	The service port.
  timeout	bool	Optional	3000	The service request timeout in milliseconds.
  ttl	bool	Optional	30000	The cache duration in milliseconds.

Authorization configuration (optional)

Configure global authentication and route-level authorization

This example enables global JWT authentication at the instance level and restricts route-level access to specific consumers.

consumers:
- name: consumer1
  issuer: abcd
  jwks: |
    {
      "keys": [
        {
          "kty": "oct",
          "kid": "123",
          "k": "hM0k3AbXBPpKOGg__Ql2Obcq7s60myWDpbHXzgKUQdYo7YCRp0gUqkCnbGSvZ2rGEl4YFkKqIqW7mTHdj-bcqXpNr-NOznEyMpVPOIlqG_NWVC3dydBgcsIZIdD-MR2AQceEaxriPA_VmiUCwfwL2Bhs6_i7eolXoY11EapLQtutz0BV6ZxQQ4dYUmct--7PLNb4BWJyQeWu0QfbIthnvhYllyl2dgeLTEJT58wzFz5HeNMNz8ohY5K0XaKAe5cepryqoXLhA-V-O1OjSG8lCNdKS09OY6O0fkyweKEtuDfien5tHHSsHXoAxYEHPFcSRL4bFPLZ0orTt1_4zpyfew",
          "alg": "HS256"
        }
      ]
    }
- name: consumer2
  issuer: abc
  jwks: |
    {
      "keys": [
        {
          "kty": "RSA",
          "e": "AQAB",
          "use": "sig",
          "kid": "123",
          "alg": "RS256",
          "n": "i0B67f1jggT9QJlZ_8QL9QQ56LfurrqDhpuu8BxtVcfxrYmaXaCtqTn7OfCuca7cGHdrJIjq99rz890NmYFZuvhaZ-LMt2iyiSb9LZJAeJmHf7ecguXS_-4x3hvbsrgUDi9tlg7xxbqGYcrco3anmalAFxsbswtu2PAXLtTnUo6aYwZsWA6ksq4FL3-anPNL5oZUgIp3HGyhhLTLdlQcC83jzxbguOim-0OEz-N4fniTYRivK7MlibHKrJfO3xa_6whBS07HW4Ydc37ZN3Rx9Ov3ZyV0idFblU519nUdqp_inXj1eEpynlxH60Ys_aTU2POGZh_25KXGdF_ZC_MSRw"
        }
      ]
    }

allow:
- consumer1

allow:
- consumer2

Enable at the gateway instance level but disable for a specific route

Configure the plugin at the instance level as follows:

global_auth: true
consumers:
- name: consumer1
  issuer: abcd
  jwks: |
    {
      "keys": [
        {
          "kty": "oct",
          "kid": "123",
          "k": "hM0k3AbXBPpKOGg__Ql2Obcq7s60myWDpbHXzgKUQdYo7YCRp0gUqkCnbGSvZ2rGEl4YFkKqIqW7mTHdj-bcqXpNr-NOznEyMpVPOIlqG_NWVC3dydBgcsIZIdD-MR2AQceEaxriPA_VmiUCwfwL2Bhs6_i7eolXoY11EapLQtutz0BV6ZxQQ4dYUmct--7PLNb4BWJyQeWu0QfbIthnvhYllyl2dgeLTEJT58wzFz5HeNMNz8ohY5K0XaKAe5cepryqoXLhA-V-O1OjSG8lCNdKS09OY6O0fkyweKEtuDfien5tHHSsHXoAxYEHPFcSRL4bFPLZ0orTt1_4zpyfew",
          "alg": "HS256"
        }
      ]
    }
- name: consumer2
  issuer: abc
  jwks: |
    {
      "keys": [
        {
          "kty": "RSA",
          "e": "AQAB",
          "use": "sig",
          "kid": "123",
          "alg": "RS256",
          "n": "i0B67f1jggT9QJlZ_8QL9QQ56LfurrqDhpuu8BxtVcfxrYmaXaCtqTn7OfCuca7cGHdrJIjq99rz890NmYFZuvhaZ-LMt2iyiSb9LZJAeJmHf7ecguXS_-4x3hvbsrgUDi9tlg7xxbqGYcrco3anmalAFxsbswtu2PAXLtTnUo6aYwZsWA6ksq4FL3-anPNL5oZUgIp3HGyhhLTLdlQcC83jzxbguOim-0OEz-N4fniTYRivK7MlibHKrJfO3xa_6whBS07HW4Ydc37ZN3Rx9Ov3ZyV0idFblU519nUdqp_inXj1eEpynlxH60Ys_aTU2POGZh_25KXGdF_ZC_MSRw"
        }
      ]
    }

For the route-b route, configure the plugin as follows:

_disable_: true

In this example, route-b is the route name entered when you create the gateway route. Because _disable_ is set to true, when a request matches this route, the plugin is disabled. No JWT authentication is performed, and all users are allowed access.

For requests that do not match the route-b route, JWT authentication is performed because global_auth is set to true at the instance level. Both consumer1 and consumer2 are allowed access.

Enable at the domain name level but disable for a specific route

Configure the plugin at the instance level as follows:

consumers:
- name: consumer1
  issuer: abcd
  jwks: |
    {
      "keys": [
        {
          "kty": "oct",
          "kid": "123",
          "k": "hM0k3AbXBPpKOGg__Ql2Obcq7s60myWDpbHXzgKUQdYo7YCRp0gUqkCnbGSvZ2rGEl4YFkKqIqW7mTHdj-bcqXpNr-NOznEyMpVPOIlqG_NWVC3dydBgcsIZIdD-MR2AQceEaxriPA_VmiUCwfwL2Bhs6_i7eolXoY11EapLQtutz0BV6ZxQQ4dYUmct--7PLNb4BWJyQeWu0QfbIthnvhYllyl2dgeLTEJT58wzFz5HeNMNz8ohY5K0XaKAe5cepryqoXLhA-V-O1OjSG8lCNdKS09OY6O0fkyweKEtuDfien5tHHSsHXoAxYEHPFcSRL4bFPLZ0orTt1_4zpyfew",
          "alg": "HS256"
        }
      ]
    }
- name: consumer2
  issuer: abc
  jwks: |
    {
      "keys": [
        {
          "kty": "RSA",
          "e": "AQAB",
          "use": "sig",
          "kid": "123",
          "alg": "RS256",
          "n": "i0B67f1jggT9QJlZ_8QL9QQ56LfurrqDhpuu8BxtVcfxrYmaXaCtqTn7OfCuca7cGHdrJIjq99rz890NmYFZuvhaZ-LMt2iyiSb9LZJAeJmHf7ecguXS_-4x3hvbsrgUDi9tlg7xxbqGYcrco3anmalAFxsbswtu2PAXLtTnUo6aYwZsWA6ksq4FL3-anPNL5oZUgIp3HGyhhLTLdlQcC83jzxbguOim-0OEz-N4fniTYRivK7MlibHKrJfO3xa_6whBS07HW4Ydc37ZN3Rx9Ov3ZyV0idFblU519nUdqp_inXj1eEpynlxH60Ys_aTU2POGZh_25KXGdF_ZC_MSRw"
        }
      ]
    }

For the route-b route, configure the plugin as follows:

_disable_: true

For the *.example.com domain name, configure the plugin as follows:

allow:
- consumer1
- consumer2

In this example, route-b is the route name entered when you create the gateway route. Because _disable_ is set to true, when a request matches this route, the plugin is disabled. No JWT authentication is performed, and all users are allowed access.

In this example, *.example.com is used to match the request's domain name. When the domain name matches, callers with the name consumer1 or consumer2 are allowed access. Other callers are denied access.

Rules are matched sequentially: the first match is applied and no further rules are evaluated. Route rules take priority over domain name rules, so you can enable the plugin for a domain name but disable it for a specific route under that domain.