Tổng quan API — GIW POC Identity Platform

Trạng thái: POC · Phiên bản: 0.1.0 · Ngày: 21/09/2026 Đặc tả: openapi.yaml (OpenAPI 3.0.3, đã validate)

1. Nền tảng này chứng minh điều gì

Bốn điều, chạy trọn luồng, trên một máy tính xách tay:

1. Khách hàng đăng ký, đăng nhập và đăng xuất với Keycloak, nhận về một phiên OIDC.
2. Cán bộ nhân viên được xác thực bằng mã nhân viên + CCCD, trong đó Keycloak — không phải portal — gọi HR Verification API và chỉ cấp phiên khi MATCH + ACTIVE.
3. Sau cả hai đường, Wi-Fi Portal lấy quyết định từ Entitlement Service, rồi mới yêu cầu Session Service mở truy cập.
4. CCCD không bao giờ lọt vào token, log, bản ghi cơ sở dữ liệu hay thông báo lỗi.

2. Kiến trúc API — portal làm chủ giao diện

Không có trang nào do Keycloak render trong nền tảng này. Wi-Fi Portal tự phục vụ màn hình của nó và gọi Galaxy ID qua token API và admin API.

Browser ──▶ Portal API ──┬──▶ Galaxy ID (Keycloak)   xác thực
   (sid cookie)          ├──▶ Entitlement Service    quyết định
                         └──▶ Session Service        thực thi
                                     │
                      Keycloak ──────┴──▶ HR Verification API

Trình duyệt chỉ nói chuyện với đúng một host — portal — và giữ đúng một cookie mờ. Nó không bao giờ thấy token, không biết địa chỉ Keycloak, cũng không biết địa chỉ của bất kỳ hệ thống phía sau nào.

Vì sao không dùng luồng redirect

Authorization Code redirect là câu trả lời trong sách giáo khoa, và ở đây nó sai:

• Captive network assistant (trình duyệt mini mà iOS và macOS bật lên trên Wi-Fi captive) xử lý redirect sang origin bên thứ ba rất tệ và không giữ cookie đáng tin. Đăng nhập kiểu redirect hỏng đúng ở nơi sản phẩm này sống.
• Tính liền mạch thương hiệu: đẩy hành khách Vietjet sang một trang Keycloak rồi quay lại là một vết nối nhìn thấy được trong hành trình 30 giây.

Cái giá phải trả, nói thẳng

Đây không phải là một mẫu được khuyến nghị. RFC 9700 (OAuth 2.0 Security Best Current Practice) nói password grant MUST NOT be used, và không ghi nhận ngoại lệ first-party nào. Direct Grant chỉ được dùng như một giải pháp tạm thời có giới hạn cho POC, nhằm kiểm chứng trải nghiệm captive portal. Kiến trúc xác thực cho production vẫn TBC và nên ưu tiên OIDC/federation chạy trên trình duyệt khi điều kiện vận hành cho phép.

Những gì không thay đổi, và không được phép thay đổi:

• Keycloak vẫn ra mọi quyết định xác thực. Portal không có kho mật khẩu, không có credential của HR.
• Keycloak vẫn gọi HR để xác minh nhân viên, qua một direct-grant authenticator tuỳ biến. Portal chỉ chuyển tiếp hai ô trên form.
• Token nằm lại phía server.

Chuẩn sẵn có và phần Galaxy tự xây

Các endpoint chuẩn đang dùng, chỉ để tham chiếu:

Luồng nhân viên không có endpoint riêng. Nó vẫn là token endpoint thông thường, trên một confidential client thứ hai mà flow direct_grant bị ghi đè thành employee-direct-grant. Authenticator của Keycloak đọc employeeId và citizenId từ request rồi gọi HR.

3. Phân tách trách nhiệm

Keycloak            danh tính và xác thực              BẠN LÀ AI
HR Verification     tình trạng lao động                CÓ PHẢI NHÂN VIÊN, CÒN LÀM VIỆC KHÔNG
Entitlement         quyết định quyền truy cập          ĐƯỢC DÙNG GÌ
Session / Network   thực thi quyền truy cập            BẬT LÊN

Hai quy tắc rút ra, và cả hai được cưỡng chế bằng code chứ không chỉ bằng văn bản:

• Keycloak không bao giờ mở mạng. Nó phát token rồi dừng. Portal phải tự đi lấy entitlement.
• Session Service không bao giờ quyết định. POST /sessions/{id}/grant trả 422 ENTITLEMENT_DENIED nếu không có entitlementId (ADR-008).

4. Các thành phần

Các service Node không có dependency npm nào, có chủ đích. Một POC xử lý CCCD thì phải đọc kiểm được từng dòng, không phải lần theo một cây dependency bắc cầu.

5. Liên kết danh tính — chiến lược cho POC

Khi một nhân viên xác thực, authenticator tuỳ biến tìm user Keycloak theo thứ tự này:

1. User mang attribute employee_ref bằng đúng reference mà HR trả về.
2. Nếu không có, user có username là reference viết thường (emp-12345).
3. Nếu vẫn không có, tạo user mới.

Nếu bước 1 tìm thấy nhiều hơn một user cùng employee_ref, luồng thất bại với IDENTITY_LINK_CONFLICT thay vì đoán.

Cố ý không làm: tự động gộp với một tài khoản CUSTOMER đã có, khớp theo email hoặc số điện thoại. Gộp hai danh tính một cách im lặng là việc không thể hoàn tác, và là quyết định cho production chứ không phải tiện tay trong POC. Theo dõi ở T-LINK §8.

Production: TBC. Cần quyết định Galaxy ID giữ một subject với hai vai trò, hay hai subject liên kết nhau. Liên quan ADR-002.

6. Correlation

Mọi request đều mang hoặc tự sinh X-Correlation-ID, và nó được trả lại trên mọi response. Một id đi suốt:

Portal → Keycloak → Custom Authenticator → HR API → Entitlement → Session

Sinh theo dạng corr-<uuid4>. Nó không bao giờ được dẫn xuất từ CCCD, mã nhân viên hay bất kỳ dữ liệu cá nhân nào — một correlation id sẽ nằm trong log và dashboard, đó là thiết kế.

7. Giả định của POC

Mọi thứ trong bảng này là phỏng đoán đặt ra để dựng được stack. Không có gì là SLA production.

8. Câu hỏi còn mở

9. Thứ tự đọc cho người review

1. Tài liệu này
2. API-MATRIX.md — mọi thứ trên một trang
3. API-SEQUENCES.md — ba luồng dưới dạng sơ đồ
4. TOKEN-CLAIMS.md — hợp đồng token
5. DATA-CLASSIFICATION.md — từng trường dữ liệu sống ở đâu và chết ở đâu
6. API-SECURITY.md — các biện pháp, và những gì còn thiếu
7. ERROR-CATALOG.md
8. API-REVIEW-CHECKLIST.md — mang phản biện của bạn tới đây