ADR-0001. JWKS issuer duy nhất làm gốc tin cậy của nền tảng
| Trường | Giá trị |
|---|---|
| Trạng thái | Accepted |
| Ngày | 2026-01-08 |
| Người quyết định | Phat Nguyen |
| Thay thế | - |
Bối cảnh
- BANA có 10+ backend service đều cần xác thực user.
- Mỗi service cần xác minh JWT mà không phải gọi về trung tâm trên mỗi request.
- Hai mẫu:
- Secret HMAC dùng chung - mọi service dùng cùng một secret; đối xứng.
- Bất đối xứng (JWKS) - một issuer ký, các service khác xác minh bằng khoá công khai.
Quyết định
@nx/identity là đơn vị duy nhất có thẩm quyền ký. Nó dùng ES256 (ECDSA trên P-256) và công bố khoá công khai tại GET /jw-certs (định dạng JWKS RFC 7517). Mọi service khác kế thừa VerifierApplication từ @nx/core - tải /jw-certs lúc khởi động, cache theo kid, và xác minh chữ ký tại chỗ.
Hiện không có issuer phụ, liên kết liên miền (federation), hay cô lập khoá theo từng merchant.
Hệ quả
| Ưu | Nhược |
|---|---|
| Service anh em không cần secret dùng chung | Điểm tin cậy duy nhất - nếu khoá ký bị lộ, mọi JWT đều có thể bị giả mạo |
| Bất đối xứng: lộ khoá công khai không quan trọng | Xoay khoá về mặt vận hành phức tạp (cần cache phía service anh em có nhận biết kid) |
| Định dạng chuẩn (JWKS / JWS / JWT) - có thể tương tác | Một khoá duy nhất cho mọi merchant - không cô lập theo tenant |
| Service anh em không phụ thuộc xác thực vào identity trên từng request | Identity là đường tới hạn của toàn nền tảng (mức ưu tiên cảnh báo HIGH) |
Phương án đã xem xét
| Phương án | Ưu | Nhược | Lý do từ chối |
|---|---|---|---|
| Secret HMAC dùng chung | Đơn giản | Bất kỳ secret nào lộ đều khiến mọi thứ tổn hại; xoay khoá cần khởi động lại đồng bộ | Vận hành mong manh |
| Khoá ký theo từng merchant | Cô lập theo tenant | Phức tạp khổng lồ trong logic xác minh phía service anh em; bùng nổ số lượng khoá | Quá sớm; cô lập khoá đa tenant đã loại khỏi scope |
| Ký theo từng service | Phi tập trung | Tin cậy giữa các service sụp đổ; mỗi service phải biết khoá của mọi service khác | Không khả thi |
| IdP bên ngoài (Auth0, Cognito) | Thuê ngoài | Phụ thuộc nhà cung cấp; độ trễ; chi phí | Cần kiểm soát nội bộ ngữ nghĩa role/permission |
Tham chiếu
@nx/corecác lớp cơ sởIssuerApplicationvàVerifierApplicationJWKSIssuerTokenService(dùng bởiAuthenticationService.generateToken)- RFC 7517 (JWKS), RFC 7519 (JWT), RFC 7515 (JWS)