jwt-logout

Use scenarios

JWTs are stateless tokens that remain valid until they expire. The jwt-logout plug-in lets you forcibly invalidate a specific JWT before expiration.

How it works

• If the request path suffix matches the path in the plug-in configuration, the logoff mechanism is triggered. The ApsaraDB for Redis instance records the JWT for logoff. The Redis key consists of the configured prefix and the key-value pair extracted from the current JWT payload.

• If the JWT payload in the request matches the characteristics of a key stored in the ApsaraDB for Redis instance, the JWT is treated as invalid and the request is rejected.

• The default key expiration time is calculated from the exp field in the JWT payload, so the key persists until the JWT expires.

Example

Plug-in configuration:

redis:
  service: redis.dns
  port: 6379
jwks: |
  {
    "keys": [
      {
        "kty": "oct",
        "kid": "123",
        "k": "hM0k3AbXBPpKOGg__Ql2Obcq7s60myWDpbHXzgKUQdYo7YCRp0gUqkCnbGSvZ2rGEl4YFkKqIqW7mTHdj-bcqXpNr-NOznEyMpVPOIlqG_NWVC3dydBgcsIZIdD-MR2AQceEaxriPA_VmiUCwfwL2Bhs6_i7eolXoY11EapLQtutz0BV6ZxQQ4dYUmct--7PLNb4BWJyQeWu0QfbIthnvhYllyl2dgeLTEJT58wzFz5HeNMNz8ohY5K0XaKAe5cepryqoXLhA-V-O1OjSG8lCNdKS09OY6O0fkyweKEtuDfien5tHHSsHXoAxYEHPFcSRL4bFPLZ0orTt1_4zpyfew",
        "alg": "HS256"
      }
    ]
  }
logout:
  path: "/jwt_logout"
  key: ["jti"]
  error_status: 401
  error_body: |
    {"message":"invalid token"}

1. Trigger a logoff.

   curl  http://xxx.hello.com/test/jwt_logout -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiJ4eHh4IiwiaXNzIjoiYWJjZCIsInN1YiI6InRlc3QiLCJhdWQiOiJ3d3cudGVzdC5jb20iLCJpYXQiOjE2NjU2NjA1MjcsImV4cCI6MTg2NTY3MzgxOX0.tmKF6qc1mOWNyCCzBOT2XKNoEGeEgr3EbhTKAQfq1io'
   
   # The following result is returned:
   {"message": "logout success"}

   Token payload:

   {
       "jti": "xxxx",
       "iss": "abcd",
       "sub": "test",
       "aud": "www.test.com",
       "iat": 1665660527,
       "exp": 1865673819
   }

   In this case, the key higress_jwt_logout_jti##xxxx is stored in the ApsaraDB for Redis instance.

2. After the logoff, access with the same JWT is rejected.

   curl  http://xxx.hello.com/test/abc -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiJ4eHh4IiwiaXNzIjoiYWJjZCIsInN1YiI6InRlc3QiLCJhdWQiOiJ3d3cudGVzdC5jb20iLCJpYXQiOjE2NjU2NjA1MjcsImV4cCI6MTg2NTY3MzgxOX0.tmKF6qc1mOWNyCCzBOT2XKNoEGeEgr3EbhTKAQfq1io'
   
   # The following result is returned:
   {"message":"invalid token"}

Use scenarios

When an account is logged on to multiple devices with JWT authentication, different JWTs may be issued on each device. The jwt-logout plug-in can restrict the account to a single active device at a time.

How it works

• When a request arrives, the system extracts the JWT and constructs a Redis key from the configured prefix and the key-value pair in the JWT payload. It then queries the corresponding value in the ApsaraDB for Redis instance. If the stored value does not match the current JWT, the request is rejected.

• If no value exists, the current JWT is written to the Redis key. The default key expiration time is calculated from the exp field in the JWT payload, so the key persists until the JWT expires. During the JWT's validity period, requests using other JWTs with the same payload characteristics are rejected.

• If the request suffix matches the path in the plug-in configuration, the forced logon mechanism is triggered and the current JWT overwrites the associated Redis key. The previously logged-on JWT with the same payload characteristics is invalidated, ensuring single-device logon.

Example

Plug-in configuration:

redis:
  service: redis.dns
  port: 6379
jwks: |
  {
    "keys": [
      {
        "kty": "oct",
        "kid": "123",
        "k": "hM0k3AbXBPpKOGg__Ql2Obcq7s60myWDpbHXzgKUQdYo7YCRp0gUqkCnbGSvZ2rGEl4YFkKqIqW7mTHdj-bcqXpNr-NOznEyMpVPOIlqG_NWVC3dydBgcsIZIdD-MR2AQceEaxriPA_VmiUCwfwL2Bhs6_i7eolXoY11EapLQtutz0BV6ZxQQ4dYUmct--7PLNb4BWJyQeWu0QfbIthnvhYllyl2dgeLTEJT58wzFz5HeNMNz8ohY5K0XaKAe5cepryqoXLhA-V-O1OjSG8lCNdKS09OY6O0fkyweKEtuDfien5tHHSsHXoAxYEHPFcSRL4bFPLZ0orTt1_4zpyfew",
        "alg": "HS256"
      }
    ]
  }
login:
  path: "/jwt_login"
  key: ["iss","aud","sub"]
  error_status: 403
  error_body: |
    {"message":"already login on other device"}

1. Perform a successful logon operation.

   curl  http://xxx.hello.com/test/abc -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiJ6enp6IiwiaXNzIjoiYWJjZCIsImF1ZCI6Ind3dy5leGFtcGxlLmNvbSIsInN1YiI6InRlc3QiLCJpYXQiOjE2NjU2NjA1MjcsImV4cCI6MTg2NTY3MzgxOX0.WljMr5ucxfLF8SmeaaL25c0QG3IX04HoD0als9gglYg'

   Token payload:

   {
       "jti": "zzzz",
       "iss": "abcd",
       "aud": "www.example.com",
       "sub": "test",
       "iat": 1665660527,
       "exp": 1865673819
   }

   In this case, the key higress_jwt_login_iss#aud#sub##abcd#www.example.com#abcd is stored in the ApsaraDB for Redis instance and the value is the same as that in the current JWT.

2. Reject the request when a different JWT with the same payload characteristics is used.

   curl  http://xxx.hello.com/test/abc -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEyMyJ9.eyJqdGkiOiJ5eXl5eSIsImlzcyI6ImFiY2QiLCJhdWQiOiJ3d3cuZXhhbXBsZS5jb20iLCJzdWIiOiJ0ZXN0IiwiaWF0IjoxNjY1NjYwNTI5LCJleHAiOjE4NjU2NzM4MTl9.6vi6eKPWSKHQxfzBPrj3-SWI4Q5zGtWhqp38JIN3FEo'
   
   # The following result is returned:
   {"message":"already login on other device"}

   Token payload:

   {
       "jti": "yyyyy",
       "iss": "abcd",
       "aud": "www.example.com",
       "sub": "test",
       "iat": 1665660527,
       "exp": 1865673819
   }

   The payload characteristics match those of the JWT in Step 1, but the jti field differs. Therefore, the request is rejected.

3. Perform a forced logon.

   curl  http://xxx.hello.com/test/jwt_login -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEyMyJ9.eyJqdGkiOiJ5eXl5eSIsImlzcyI6ImFiY2QiLCJhdWQiOiJ3d3cuZXhhbXBsZS5jb20iLCJzdWIiOiJ0ZXN0IiwiaWF0IjoxNjY1NjYwNTI5LCJleHAiOjE4NjU2NzM4MTl9.6vi6eKPWSKHQxfzBPrj3-SWI4Q5zGtWhqp38JIN3FEo'
   
   # The following result is returned:
   {"message":"login success"}

   In this case, the key higress_jwt_login_iss#aud#sub##abcd#www.example.com#abcd is stored in the ApsaraDB for Redis instance and the value is replaced by the value in the current JWT.

   Use the current JWT to successfully access the page.

   curl  http://xxx.hello.com/test/abc -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEyMyJ9.eyJqdGkiOiJ5eXl5eSIsImlzcyI6ImFiY2QiLCJhdWQiOiJ3d3cuZXhhbXBsZS5jb20iLCJzdWIiOiJ0ZXN0IiwiaWF0IjoxNjY1NjYwNTI5LCJleHAiOjE4NjU2NzM4MTl9.6vi6eKPWSKHQxfzBPrj3-SWI4Q5zGtWhqp38JIN3FEo'

   If you use the JWT in Step 1, a failure message is returned.

   curl  http://xxx.hello.com/test/abc -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEyMyJ9.eyJqdGkiOiJ4eHh4IiwiaXNzIjoiYWJjZCIsImF1ZCI6Ind3dy5leGFtcGxlLmNvbSIsInN1YiI6InRlc3QiLCJpYXQiOjE2NjU2NjA1MjcsImV4cCI6MTg2NTY3MzgxOX0.P0WtBTHJzUJvklu9q8XSRszfPbgojrZHg7t4ZaYfKGo'
   
   # The following result is returned:
   {"message":"already login on other device"}