API Overview — GIW POC Identity Platform

Status: POC · Version: 0.1.0 · Date: 2026-09-21 Spec: openapi.yaml (OpenAPI 3.0.3, validated)

1. What this platform proves

Four things, end to end, on a laptop:

1. A customer can register, log in and log out against Keycloak, and receive an OIDC session.
2. An employee can be authenticated by Employee ID + CCCD, where Keycloak — not the portal — calls the HR Verification API and grants a session only on MATCH + ACTIVE.
3. After either path, the Wi-Fi Portal obtains a decision from the Entitlement Service and only then asks the Session Service to open access.
4. The CCCD never reaches a token, a log, a database row or an error message.

2. API architecture — the portal owns the UI

There is no Keycloak-rendered page anywhere in this platform. The Wi-Fi Portal serves its own screens and calls Galaxy ID over the token and admin APIs.

Browser ──▶ Portal API ──┬──▶ Galaxy ID (Keycloak)   authenticate
   (sid cookie)          ├──▶ Entitlement Service    decide
                         └──▶ Session Service        enforce
                                     │
                      Keycloak ──────┴──▶ HR Verification API

The browser talks to exactly one host — the portal — and holds one opaque cookie. It never sees a token, a Keycloak URL, or the address of any downstream system.

Why not the redirect flow

An Authorization Code redirect is the textbook answer, and it is the wrong one here:

• The captive network assistant (the mini-browser iOS and macOS pop up on a captive Wi-Fi) handles redirects to a third-party origin badly and does not persist cookies reliably. A redirect-based login fails in exactly the place this product lives.
• Brand continuity: bouncing a Vietjet passenger to a Keycloak page, then back, is a visible seam in a 30-second journey.

What that costs, stated plainly

This is not a blessed pattern. RFC 9700 (OAuth 2.0 Security Best Current Practice) states the password grant MUST NOT be used, and it records no first-party exception. Direct Grant is used only as a constrained POC workaround for captive-portal UX validation. Production authentication architecture remains TBC and should prefer modern browser-based OIDC/federation where operationally feasible.

What did not change, and must not:

• Keycloak still makes every authentication decision. The portal has no password store and no HR credential.
• Keycloak still calls HR for employee verification, through a custom direct-grant authenticator. The portal only relays two form fields.
• Tokens stay server-side.

Standard vs Galaxy-built

Standard endpoints in use, reference only:

The employee flow has no special endpoint. It is the ordinary token endpoint on a second confidential client whose direct_grant flow is overridden to employee-direct-grant. Keycloak's authenticator reads employeeId and citizenId from the request and calls HR.

3. Separation of concerns

Keycloak            identity and authentication        WHO you are
HR Verification     employment status                  ARE you staff, and active
Entitlement         access decision                    WHAT you may have
Session / Network   access enforcement                 TURN IT ON

Two rules follow, and both are enforced in code, not just prose:

• Keycloak never opens the network. It issues a token and stops. The portal must go and get an entitlement.
• Session Service never decides. POST /sessions/{id}/grant returns 422 ENTITLEMENT_DENIED if no entitlementId is supplied (ADR-008).

4. Components

Node services carry no npm dependencies on purpose. A POC that handles a CCCD should be auditable line by line, without a transitive dependency tree.

5. Identity linking — POC strategy

When an employee authenticates, the custom authenticator resolves a Keycloak user in this order:

1. A user carrying the attribute employee_ref equal to the HR reference.
2. Otherwise a user whose username is the lowercased reference (emp-12345).
3. Otherwise a new user is provisioned.

If step 1 finds more than one user sharing an employee_ref, the flow fails with IDENTITY_LINK_CONFLICT rather than guessing.

Deliberately not implemented: automatic merge with a pre-existing CUSTOMER account matched by email or phone. Silently merging two identities is irreversible and is a production decision, not a POC convenience. Tracked as T-LINK in §8.

Production: TBC. Requires a decision on whether Galaxy ID holds one subject with two roles, or two linked subjects. Relates to ADR-002.

6. Correlation

Every request carries or generates X-Correlation-ID, and it is echoed on every response. One id spans:

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

It is generated as corr-<uuid4>. It is never derived from a CCCD, an employee id or any personal data — a correlation id ends up in logs and dashboards by design.

7. POC assumptions

Everything in this table is a guess made to get the stack running. None is a production SLA.

8. Open questions

9. Reading order for reviewers

1. This document
2. API-MATRIX.md — everything on one page
3. API-SEQUENCES.md — the three flows as diagrams
4. TOKEN-CLAIMS.md — the token contract
5. DATA-CLASSIFICATION.md — where every field lives and dies
6. API-SECURITY.md — controls, and what is missing
7. ERROR-CATALOG.md
8. API-REVIEW-CHECKLIST.md — bring your objections here