Keycloak (Galaxy ID) — đặc tả tích hợp

Trạng thái: POC · Ngày: 22/09/2026 · Realm: galaxy-id-poc

Đây không phải bản đặc tả lại OIDC. Mọi endpoint dưới đây là chuẩn Keycloak / OAuth 2.0. Tài liệu này ghi chính xác những gì portal gọi: client nào, tham số gì, nhận về gì, lỗi nào — để đội tích hợp không phải đọc ngược mã nguồn.

Hợp đồng gốc: {issuer}/.well-known/openid-configuration

DIRECT GRANT = POC ONLY. RFC 9700 nói password grant MUST NOT be used. Đường production ứng viên là browser OIDC / federation — xem ../docs/AUTH-STRATEGY.md.

1. Địa chỉ

Hai biến riêng, không gộp. iss trong token là địa chỉ hướng trình duyệt; portal lại gọi qua mạng nội bộ. Gộp lại là lỗi captive portal kinh điển: token phát ra một issuer, dịch vụ kiểm theo issuer khác, mọi thứ trông như sai chữ ký.

2. Bốn client

Vì sao confidential: client public bật Direct Access Grants nghĩa là bất kỳ ai trong mạng cũng phát lại được grant mà không cần xác thực client. Portal chạy phía máy chủ nên giữ được secret.

Secret nạp bằng OIDC_API_CLIENT_SECRET qua bootstrap, không nằm trong realm-export.json.

3. Các lời gọi

3.1 Đăng nhập khách hàng

POST {internal}/protocol/openid-connect/token
Content-Type: application/x-www-form-urlencoded
X-Correlation-ID: corr-...

grant_type=password
client_id=wifi-portal-api
client_secret={OIDC_API_CLIENT_SECRET}
username={email}
password={password}
scope=openid profile email

Ba nguyên nhân đầu trả về y hệt nhau. Keycloak cố ý không phân biệt, và portal cũng không. Phân biệt là mở cửa cho dò tài khoản.

Timeout: 5000 ms.

3.2 Xác minh CBNV

POST {internal}/protocol/openid-connect/token

grant_type=password
client_id=wifi-portal-employee-api
client_secret={OIDC_API_CLIENT_SECRET}
username={employeeId}          ← Keycloak bắt buộc có, authenticator bỏ qua
password=n/a                   ← Keycloak bắt buộc có, authenticator bỏ qua
employeeId={employeeId}        ← authenticator đọc cái này
citizenId={citizenId}          ← authenticator đọc cái này
scope=openid profile

CCCD gửi bằng trường riêng, không dùng tham số password. Proxy, APM agent và công cụ báo lỗi đều đối xử đặc biệt với password của password grant — CCCD phải tránh xa cơ chế đó.

Luồng bên trong Keycloak:

token endpoint
  → direct_grant flow = employee-direct-grant
  → EmployeeDirectGrantAuthenticator
      validate định dạng
      → POST http://mock-hr-api:3001/api/v1/employees/verify
      → MATCH + ACTIVE + eligible?
      → tìm/tạo user theo employee_ref
      → set 4 attribute
  → phát token

Timeout: 12000 ms — phải lớn hơn hrTimeoutMs × hrMaxAttempts (3000 × 2). Đặt nhỏ hơn thì portal timeout trước và báo nhầm là "Galaxy ID sập" trong khi lỗi thật nằm ở HR.

3.3 Đăng ký

Hai bước, đều là API chuẩn của Keycloak.

Bước 1 — lấy token service account:

POST {internal}/protocol/openid-connect/token

grant_type=client_credentials
client_id=wifi-portal-api
client_secret={OIDC_API_CLIENT_SECRET}

Bước 2 — tạo user:

POST {admin}/users
Authorization: Bearer {service_account_token}
Content-Type: application/json

{
  "username": "an.nguyen@example.test",
  "email": "an.nguyen@example.test",
  "emailVerified": true,
  "enabled": true,
  "firstName": "An",
  "lastName": "Nguyen",
  "attributes": { "user_type": ["CUSTOMER"], "member_tier": ["NONE"] },
  "credentials": [{ "type": "password", "value": "...", "temporary": false }]
}

Quyền của service account: chỉ manage-users và view-users trong realm-management. Cố ý không dùng realm-admin — portal không được phép sửa client, flow hay cấu hình realm.

emailVerified: true là dối trá có chủ ý ở POC vì chưa có máy chủ mail. Production phải xác minh thật.

3.4 Làm mới token

POST {internal}/protocol/openid-connect/token

grant_type=refresh_token
client_id={client đã phát token ban đầu}
client_secret={OIDC_API_CLIENT_SECRET}
refresh_token={refresh_token}

Phải dùng đúng client đã phát token. Dùng client khác là invalid_grant.

3.5 Đăng xuất

POST {internal}/protocol/openid-connect/logout

client_id={client}
client_secret={OIDC_API_CLIENT_SECRET}
refresh_token={refresh_token}

Back-channel, không có vòng qua trình duyệt. Portal thu hồi phiên mạng trước, rồi mới gọi cái này — nếu gọi IdP hỏng thì mạng đã tắt rồi.

Lỗi ở bước này không chặn người dùng: token sẽ tự hết hạn.

3.6 JWKS — Entitlement Service dùng

GET {internal}/protocol/openid-connect/certs

Cache 5 phút. Gặp kid lạ thì ép nạp lại đúng một lần.

4. Hợp đồng claim

Chi tiết đầy đủ: TOKEN-CLAIMS.md

Bốn claim đầu do client scope giw-identity ánh xạ. Scope này tạo bằng Admin API trong bootstrap, không khai trong realm-export.json.

Bẫy đã gặp thật: khai mảng clientScopes trong bản import realm đầy đủ sẽ thay thế toàn bộ scope mặc định của Keycloak, làm mất profile/email/roles/basic khỏi mọi token. Đừng khai ở đó.

member_tier là mock. GalaxyJoy chưa tồn tại. Claim này mang sẵn để bảng quyết định DMN có chiều loyalty khi nghiệp vụ cần — hiện chưa luật nào đọc tới nó.

Cấm xuất hiện trong token

citizenId · cccd · citizen_id · nationalId · mật khẩu · dữ liệu HR thô.

Có test tự động quét mọi claim, mọi user record, mọi event log và log của cả 5 container.

5. Cấu hình realm

6. Hai custom authenticator

Cả hai dùng chung lớp EmployeeVerification — một nơi quyết định, để hai đường không lệch nhau về xử lý CCCD.

Cấu hình qua AuthenticatorConfig, fallback sang biến môi trường GIW_HR_*. Không ghi hrApiKey vào realm-export.json.

7. Dữ liệu mock

Toàn bộ tổng hợp. .test là TLD dành riêng theo RFC 6761, vĩnh viễn không resolve được.

Khách hàng — mật khẩu Passw0rd!23

Nhân viên — 20 bản ghi trong mock-hr-api/src/employees.json

Ba nhóm đáng chú ý:

① HDBANK và VIKKI — công ty trong tập đoàn nhưng chưa nằm trong EMPLOYEE_COMPANIES. HR nói đủ điều kiện, Entitlement vẫn từ chối. Đây là chỗ để nghiệp vụ nhìn thấy quyết định "công ty nào được dùng" nằm ở đâu, và sửa nó trong bảng DMN chứ không phải trong mã.

② ON_LEAVE, PROBATION, TERMINATED — nền tảng Wi-Fi coi tất cả là "không ACTIVE", không mã hoá từ vựng nội bộ của HR. HR đổi tên trạng thái thì Wi-Fi không phải sửa.

③ Các bản ghi biên — mã 3 ký tự, mã 30 ký tự, CCCD 9 số. Để validate không bị viết chặt tay theo một định dạng duy nhất.

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

Liên quan

API-OVERVIEW.md · TOKEN-CLAIMS.md · API-SECURITY.md · ../docs/AUTH-STRATEGY.md · DMN-DECISION-SPEC.md