ADR-0001. JWKS issuer duy nhất làm trust root 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 | identity-team, platform-architect |
| 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:
- Shared HMAC secret — mọi service dùng cùng một secret; đối xứng.
- Asymmetric (JWKS) — một issuer ký, các service khác xác minh bằng public key.
Quyết định
@nx/identity là đơn vị duy nhất có thẩm quyền ký. Sử dụng ES256 (ECDSA over P-256) và publish public key tại GET /jw-certs (định dạng JWKS RFC 7517). Mọi service khác kế thừa VerifierApplication từ @nx/core — fetch /jw-certs lúc boot, cache theo kid, và xác minh chữ ký tại chỗ.
Hiện không có issuer phụ, federation, hay key isolation theo từng merchant.
Hệ quả
| Ưu | Nhược |
|---|---|
| Sister service không cần shared secret | Single point of trust — nếu signing key bị lộ, mọi JWT đều có thể bị giả mạo |
| Bất đối xứng: lộ public key không quan trọng | Xoay key về mặt vận hành phức tạp (cần cache sister có nhận biết kid) |
| Định dạng chuẩn (JWKS / JWS / JWT) — tương tác được | Một key duy nhất cho mọi merchant — không có tenant isolation |
| Sister service không phụ thuộc auth vào identity per-request | Identity là critical path toàn nền tảng (mức ưu tiên alert HIGH) |
Phương án đã xem xét
| Phương án | Ưu | Nhược | Lý do từ chối |
|---|---|---|---|
| Shared HMAC secret | Đơn giản | Bất kỳ secret nào lộ đều khiến mọi thứ tổn hại; xoay key cần restart đồng bộ | Vận hành mong manh |
| Signing key theo từng merchant | Tenant isolation | Phức tạp khổng lồ trong logic xác minh phía sister; bùng nổ số lượng key | Quá sớm; multi-tenant key isolation đã loại khỏi scope |
| Ký theo từng service | Phi tập trung | Trust giữa các service sụp đổ; mỗi service phải biết key của mọi service khác | Không |
| IdP ngoài (Auth0, Cognito) | Outsourced | Vendor lock-in; latency; chi phí | Cần kiểm soát nội bộ ngữ nghĩa role/permission |
Tham chiếu
@nx/corelớp cơ sởIssuerApplicationvàVerifierApplicationJWKSIssuerTokenService(dùng bởiAuthenticationService.generateToken)- RFC 7517 (JWKS), RFC 7519 (JWT), RFC 7515 (JWS)