Skip to main content
Version: 2.11

jwt-auth

Summary#

Name#

jwt-auth is an authentication plugin that need to work with consumer. Add JWT Authentication to a service or route.

The consumer then adds its key to the query string parameter, request header, or cookie to verify its request.

For more information on JWT, refer to JWT for more information.

Attributes#

NameTypeRequirementDefaultValidDescription
keystringrequireddifferent consumer have different value, it's unique. different consumer use the same key, and there will be a request matching exception.
secretstringoptionalencryption key. if you do not specify, the value is auto-generated in the background.
public_keystringoptionalRSA public key, required when algorithm attribute selects RS256 algorithm.
private_keystringoptionalRSA private key, required when algorithm attribute selects RS256 algorithm.
algorithmstringoptional"HS256"["HS256", "HS512", "RS256"]encryption algorithm.
expintegeroptional86400[1,...]token's expire time, in seconds
base64_secretbooleanoptionalfalsewhether secret is base64 encoded

API#

This plugin will add /apisix/plugin/jwt/sign to sign. You may need to use interceptors to protect it.

How To Enable#

  1. set a consumer and config the value of the jwt-auth option
curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '{    "username": "jack",    "plugins": {        "jwt-auth": {            "key": "user-key",            "secret": "my-secret-key"        }    }}'

jwt-auth uses the HS256 algorithm by default, and if you use the RS256 algorithm, you need to specify the algorithm and configure the public key and private key, as follows:

curl http://127.0.0.1:9080/apisix/admin/consumers -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '{    "username": "kerouac",    "plugins": {        "jwt-auth": {            "key": "user-key",            "public_key": "-----BEGIN PUBLIC KEY-----\n……\n-----END PUBLIC KEY-----",            "private_key": "-----BEGIN RSA PRIVATE KEY-----\n……\n-----END RSA PRIVATE KEY-----",            "algorithm": "RS256"        }    }}'
  1. add a Route or add a Service, and enable the jwt-auth plugin
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '{    "methods": ["GET"],    "uri": "/index.html",    "plugins": {        "jwt-auth": {}    },    "upstream": {        "type": "roundrobin",        "nodes": {            "39.97.63.215:80": 1        }    }}'

You can use APISIX Dashboard to complete the above operations through the web console.

  1. Add a Consumer through the web console:

create a consumer

then add jwt-auth plugin in the Consumer page: enable jwt plugin

  1. Create a Route or Service object and enable the jwt-auth plugin:

enable jwt from route or service

Test Plugin#

get the token in jwt-auth plugin:#

  • without extension payload:
$ curl http://127.0.0.1:9080/apisix/plugin/jwt/sign?key=user-key -iHTTP/1.1 200 OKDate: Wed, 24 Jul 2019 10:33:31 GMTContent-Type: text/plainTransfer-Encoding: chunkedConnection: keep-aliveServer: APISIX web server
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1c2VyLWtleSIsImV4cCI6MTU2NDA1MDgxMX0.Us8zh_4VjJXF-TmR5f8cif8mBU7SuefPlpxhH0jbPVI
  • with extension payload:
$ curl -G --data-urlencode 'payload={"uid":10000,"uname":"test"}' http://127.0.0.1:9080/apisix/plugin/jwt/sign?key=user-key -iHTTP/1.1 200 OKDate: Wed, 21 Apr 2021 06:43:59 GMTContent-Type: text/plain; charset=utf-8Transfer-Encoding: chunkedConnection: keep-aliveServer: APISIX/2.4
eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1bmFtZSI6InRlc3QiLCJ1aWQiOjEwMDAwLCJrZXkiOiJ1c2VyLWtleSIsImV4cCI6MTYxOTA3MzgzOX0.jI9-Rpz1gc3u8Y6lZy8I43RXyCu0nSHANCvfn0YZUCY

try request with token#

  • without token:
$ curl http://127.0.0.1:9080/index.html -iHTTP/1.1 401 Unauthorized...{"message":"Missing JWT token in request"}
  • request header with token:
$ curl http://127.0.0.1:9080/index.html -H 'Authorization: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1c2VyLWtleSIsImV4cCI6MTU2NDA1MDgxMX0.Us8zh_4VjJXF-TmR5f8cif8mBU7SuefPlpxhH0jbPVI' -iHTTP/1.1 200 OKContent-Type: text/htmlContent-Length: 13175...Accept-Ranges: bytes
<!DOCTYPE html><html lang="cn">...
  • request params with token:
$ curl http://127.0.0.1:9080/index.html?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1c2VyLWtleSIsImV4cCI6MTU2NDA1MDgxMX0.Us8zh_4VjJXF-TmR5f8cif8mBU7SuefPlpxhH0jbPVI -iHTTP/1.1 200 OKContent-Type: text/htmlContent-Length: 13175...Accept-Ranges: bytes
<!DOCTYPE html><html lang="cn">...
  • request cookie with token:
$ curl http://127.0.0.1:9080/index.html --cookie jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJrZXkiOiJ1c2VyLWtleSIsImV4cCI6MTU2NDA1MDgxMX0.Us8zh_4VjJXF-TmR5f8cif8mBU7SuefPlpxhH0jbPVI -iHTTP/1.1 200 OKContent-Type: text/htmlContent-Length: 13175...Accept-Ranges: bytes
<!DOCTYPE html><html lang="cn">...

Disable Plugin#

When you want to disable the jwt-auth plugin, it is very simple, you can delete the corresponding json configuration in the plugin configuration, no need to restart the service, it will take effect immediately:

$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '{    "methods": ["GET"],    "uri": "/index.html",    "id": 1,    "plugins": {},    "upstream": {        "type": "roundrobin",        "nodes": {            "39.97.63.215:80": 1        }    }}'