Plugin JWT Auth

Plugin JWT Auth (tên kỹ thuật jwt-auth, nhóm Authentication) bảo vệ Route / Service bằng JSON Web Token (JWT). Plugin lấy token từ request và kiểm chứng token trước khi cho request đi tiếp tới backend.

Luồng JWT cần đủ 2 phần:

Phần	Vai trò	Cấu hình ở đâu
JWT Credential trên Consumer	Danh tính và khóa ký token (Key, Algorithm, Secret / Public Key).	Quản lý JWT Credential
Plugin JWT Auth trên Route / Service	Nơi API Gateway lấy token từ request và kiểm chứng.	Trang này

Trường hợp sử dụng

• Chỉ cho phép ứng dụng hoặc đối tác đã được cấp JWT gọi API.
• Kết hợp với plugin Rate Limiting để giới hạn số request theo từng Consumer.

cảnh báo

Tạo trước một Consumer có JWT Credential. Nếu không, sau khi bật plugin mọi request tới Route / Service đều bị từ chối vì không có token hợp lệ.

Tạo plugin JWT Auth

Để tạo plugin JWT Auth, bạn thực hiện các bước sau:

1. Chọn API Gateway → Plugin ở menu bên trái, chọn API Gateway ở góc trên bên phải, nhấn New plugin, rồi chọn JWT Auth trong popup Add plugin. Bạn cũng có thể thêm từ tab Plugins của Route / Service, xem Thêm Plugin.

2. Nhập Display Name tại mục Basic Information. Description điền sẵn Verify and authenticate JSON Web Tokens., bạn có thể sửa. Xem Basic Information.

3. Chọn mục Configuration. Form hiển thị sẵn 1 thuộc tính bắt buộc:

Attribute	Bắt buộc	Mô tả
header	Y	Tên HTTP header chứa JWT trong request. Mặc định Authorization.

Nhấn Attribute (N) để bật thêm các thuộc tính khác nếu cần:

Attribute	Bắt buộc	Mô tả
query	N	Tên query param chứa JWT, ưu tiên thấp hơn header. Mặc định jwt.
cookie	N	Tên cookie chứa JWT, ưu tiên thấp hơn query. Mặc định jwt.
hide_credentials	N	Bật để API Gateway không chuyển header / query / cookie chứa JWT xuống backend. Mặc định false.
key_claim_name	N	Claim trong payload JWT dùng để tìm đúng credential / Consumer. Giá trị claim phải khớp Key của JWT Credential. Mặc định iss.
claims_to_verify	N	Các claim cần kiểm tra hiệu lực thời gian: exp, nbf. Mặc định exp.
maximum_expiration	N	Thời gian sống tối đa cho phép của token (giây). 0 là không giới hạn. Mặc định 0.
anonymous	N	Consumer ẩn danh được dùng khi xác thực thất bại, để vẫn cho phép truy cập. Mặc định để trống.
run_on_preflight	N	Chạy plugin cả với request preflight OPTIONS (CORS). Mặc định false.
use_jwks	N	Dùng JSON Web Key Set (JWKS) của Identity Provider để kiểm chứng chữ ký, thay cho Secret / Public Key của JWT Credential. Mặc định false.

Ví dụ sau khi bật thêm key_claim_name, form và JSON có thêm thuộc tính này với giá trị iss:

4. Chọn mục Scope, chọn Global hoặc Scoped rồi gán Route / Service cần bảo vệ. Xem Scope.

5. Nhấn Create. Thông báo Plugin created successfully hiển thị và plugin JWT Auth xuất hiện trong danh sách với cột Applied to đúng phạm vi đã chọn.

Cấu hình mẫu

Cấu hình mặc định, chỉ lấy token từ header Authorization:

{
  "header": "Authorization"
}

Tìm Consumer theo claim iss trong token:

{
  "header": "Authorization",
  "key_claim_name": "iss"
}

Lấy token từ header Authorization và không chuyển header chứa token xuống backend:

{
  "header": "Authorization",
  "hide_credentials": true
}

Kiểm tra thêm claim nbf (token chưa tới thời điểm có hiệu lực thì từ chối) bên cạnh exp:

{
  "header": "Authorization",
  "claims_to_verify": "exp,nbf"
}

Cho phép client gửi token qua query param hoặc cookie (ví dụ trang web nhúng không đặt được header), đồng thời chặn token có thời gian sống quá 1 giờ:

{
  "header": "Authorization",
  "query": "jwt",
  "cookie": "jwt",
  "maximum_expiration": "3600"
}

Dùng JWKS của Identity Provider để kiểm chứng chữ ký, thay cho Secret / Public Key khai trên JWT Credential:

{
  "header": "Authorization",
  "use_jwks": true,
  "run_on_preflight": false
}

mẹo

Giữ run_on_preflight là false khi Route có dùng CORS. Trình duyệt gửi request preflight OPTIONS không kèm header Authorization. Nếu bật true, preflight bị trả 401 và lời gọi API từ trình duyệt thất bại, dù token của request thật hợp lệ.

Kiểm tra hoạt động

Sau khi tạo plugin, dùng một Consumer có JWT Credential để tạo token kiểm thử:

• Gọi API qua Route / Service được bảo vệ không kèm token: nhận 401 Unauthorized, plugin đang chặn đúng.
• Gọi lại kèm header Authorization: Bearer <jwt> (hoặc query / cookie nếu đã cấu hình), với token ký đúng thuật toán, đúng Secret, và claim theo key_claim_name khớp Key của JWT Credential: nhận 200, request tới được backend.

Lỗi thường gặp

Lỗi	Nguyên nhân	Cách xử lý
Nhận 401 dù đã kèm token	Claim theo key_claim_name trong token không khớp Key của JWT Credential	Sửa token cho claim khớp Key, hoặc sửa key_claim_name.
Nhận 401 dù đã kèm token	Token ký bằng Secret khác với Secret đã lưu trên JWT Credential	Ký lại token bằng đúng Secret.
Nhận 401 dù đã kèm token	Thuật toán ký token khác Algorithm trên JWT Credential	Ký lại token bằng đúng thuật toán.
Gọi API từ trình duyệt bị lỗi CORS / 401 ở request OPTIONS	run_on_preflight đang là true	Đổi run_on_preflight về false.

Bước tiếp theo

• Quản lý JWT Credential
• Plugin Rate Limiting