API Security — GIW POC Identity Platform

Status: POC · Date: 2026-09-21

This document states what is implemented, and — more usefully for a reviewer — what is not.

DIRECT GRANT / PASSWORD GRANT = POC-ONLY IMPLEMENTATION. Not a production architecture, not a production Galaxy ID flow, not a production employee authentication recommendation. The browser / Authorization Code + PKCE path is retained as PRODUCTION CANDIDATE. Full comparison and migration path: ../docs/AUTH-STRATEGY.md.

1. Grant choice — read this first

The portal renders its own UI and calls Galaxy ID over the token API. There is no browser redirect and no Keycloak-rendered page. That is a deliberate decision with real costs; a reviewer should accept or reject it explicitly rather than discover it in the code.

Why

A captive portal is the one place the redirect flow genuinely breaks. 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 login that depends on a redirect fails exactly where this product lives.

What it costs

No standards exception is being claimed here. RFC 9700 (OAuth 2.0 Security BCP) states the password grant MUST NOT be used, and OAuth 2.1 removes it. There is no first-party carve-out in either document, and this POC does not invoke one.

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.

Tracked as T-GRANT. If corporate IdP federation is ever required for employees — which ADR-003 recommends over CCCD — a redirect path has to come back for that journey.

Confidential, not public

A public client with Direct Access Grants enabled lets anyone on the network replay the grant with no client authentication whatsoever. The portal is a server-side application, so it can hold a secret, and it does. The secret is applied by bootstrap from OIDC_API_CLIENT_SECRET and never written into realm-export.json.

Mode B is retained, not deleted

wifi-portal and wifi-portal-employee — public clients, PKCE S256 enforced, standard flow on, Direct Grant off — remain in the realm with their employee-browser flow and the giw-employee-verify authenticator. Nothing in the POC calls them.

They are kept because Authorization Code + PKCE is the path an Enterprise IdP federates into, and ADR-003 recommends exactly that in place of CCCD. Five automated tests assert they still work, so the path cannot rot unnoticed.

Tokens never reach the browser

Tokens live in a server-side map. The browser holds an opaque sid cookie: HttpOnly, SameSite=Strict, Max-Age=3600. The map is reaped every 5 minutes so it cannot grow without bound.

SameSite=Strict, not Lax: the portal has no cross-site entry point by design, so there is nothing to relax for.

2. Token validation

The Entitlement Service performs full validation before reading a single claim:

Identity is taken from the token, never from the body. A body subjectId that contradicts sub returns 403; a contradicting userType is logged and ignored. Without this, the portal could assert its own entitlements and the service would be decorative.

3. Service-to-service authentication

The HR API key is never written to realm-export.json. It reaches Keycloak through the environment variable GIW_HR_API_KEY, so the repository carries no secret. .env is git-ignored; .env.example holds placeholders only.

4. Transport

Shipping this POC's transport configuration to a shared environment would put a CCCD on the wire in clear text.

5. Brute force and rate limiting

The employee-form counter is per authentication session, so it is bypassable by restarting the flow. It raises the cost of a CCCD guessing attack but does not stop one. A production control must be per employeeId and per source, enforced centrally.

6. Account and credential enumeration

Three deliberate design choices:

1. HR returns a byte-identical body for "unknown employee" and "wrong CCCD".
2. Comparison is crypto.timingSafeEqual, and the HR handler scans every record even after a match, so response time does not reveal a hit.
3. The authenticator renders the same message (employeeVerifyFailed) for both.

A test asserts the two responses are deep-equal. If someone later "improves" the error messages, that test fails.

7. Replay protection

Authorization-code, state and nonce protections no longer apply: there is no authorization code in this architecture. That is a reduction in the number of moving parts, not a gap — but it also removes the defence-in-depth those mechanisms provided.

8. Secrets

.env.example contains placeholder values marked change-me. They are weak on purpose so the stack boots unattended, and they must be replaced before the stack leaves a laptop.

9. Audit

All logs are single-line JSON with a correlationId, so one journey is one grep.

10. Security headers

Portal responses carry X-Frame-Options: DENY, X-Content-Type-Options: nosniff, Referrer-Policy: no-referrer, Cache-Control: no-store. Keycloak sets its own.

Not yet set: Content-Security-Policy on portal pages, and Strict-Transport-Security (meaningless over plain HTTP).

11. Known gaps — read this before approving anything

11b. Security boundary — who knows what

On "clear sensitive values immediately after the request"

JavaScript strings are immutable. A password or CCCD read from a request body cannot be zeroed — there is no memset. What is actually guaranteed:

1. The value is read into a local and passed straight to the outbound request.
2. It is never assigned to a field, session object, cache or closure that outlives the request.
3. It goes out of scope when the handler returns, left to the garbage collector.
4. No log statement in the portal takes it as an argument.

Points 2–4 are enforceable and enforced, with automated tests behind 4. Point 1 is not a wipe and this document will not pretend otherwise. A language with controlled memory would do better — one more reason Mode A is POC-only.

Inside Keycloak the same holds: EmployeeVerification keeps the CCCD in a local, hands it to HrVerificationClient, and never writes it to a field, user attribute, auth-session note, event detail or log line. HrVerificationClient logs e.getClass().getSimpleName() on failure, never e.getMessage(), because some transport stacks echo the request body into the exception message.

12. CCCD — the standing objection

This POC implements Employee ID + CCCD because the task order asked for it, and it contains the data as tightly as the design allows: transient, unlogged, unstored, untokenised, with automated tests enforcing all four.

That is containment, not endorsement. ADR-003 and decision D3 both currently say: remove CCCD from employee verification and use corporate IdP federation (OIDC) with company-email OTP as fallback. Nothing in this POC changes that recommendation.

Employee ID + CCCD = POC verification approach. Production: TBC — requires Legal + Security + HR review.