GIW POC — Identity Platform custom APIs (0.1.0)

The portal forwards the credentials to Galaxy ID's token endpoint (OAuth 2.0 Resource Owner Password Credentials, confidential client), then obtains an entitlement and opens a network session before answering.

POC ONLY. Direct Grant is a constrained POC workaround; production auth architecture is TBC and should prefer browser OIDC/federation. See ../docs/AUTH-STRATEGY.md.

The portal never verifies a credential itself. It has no password store and no HR access; every authentication decision is Keycloak's.

The password is transited, never persisted and never logged. JavaScript strings are immutable so it cannot be zeroed; it goes out of scope when the request ends. That is the honest guarantee.

On success the response sets an opaque, HttpOnly, SameSite=Strict sid cookie. Tokens stay server-side.

Creates the account through Galaxy ID's Admin API using the portal's own service account (scoped to manage-users, deliberately not realm-admin), then performs an ordinary login.

Register-then-login on purpose: exactly one code path mints a session, so there is one place where credentials are checked and one place where an entitlement is issued.

POC ONLY. See ../docs/AUTH-STRATEGY.md. The production candidate for this journey is browser OIDC federating to an Enterprise IdP (ADR-003), which would also remove the CCCD.

The portal forwards both fields to Galaxy ID's token endpoint against a client bound to the custom employee-direct-grant flow. Keycloak then calls the HR Verification API and authenticates only on MATCH + ACTIVE.

The portal is a relay here, not a decision maker: it holds no HR credential and cannot verify anyone.

citizenId is sent as its own field, never as the OAuth password parameter — proxies, APM agents and error reporters treat password specially, and a CCCD must stay away from that machinery.

CCCD handling: transient. Not stored, not logged, not in any token, not echoed in any response. Enforced by automated tests.

Always 200. An unauthenticated caller gets {"authenticated": false} rather than a 401, because the entry screen asks this on every page load and an error status there is noise, not information.

The network session is re-read from the Session Service so an expiry or a revocation elsewhere shows up here.

Revokes the network session, then performs a back-channel logout against Galaxy ID, then drops the portal session and clears the cookie.

Revoke-first is deliberate: if the IdP call fails, access is already off. Always 200 — a logout that can fail is a logout users do not trust.

Confirms that the (employeeId, citizenId) pair matches an employee record and reports whether that employee is active and Wi-Fi eligible.

Read-only. No state changes, so a timed-out call is safe to retry. The Keycloak authenticator retries once by default.

No enumeration. "No such employee" and "wrong citizenId" return the byte-identical body {"verified":false,"active":false,"reason":"NOT_FOUND_OR_MISMATCH"}. Comparison is constant-time so response latency does not leak a match either.

Minimal disclosure. The response carries a verification verdict and an opaque employeeRef — never a name, department, salary band or contact detail.

Evaluates the caller's verified access token against POC policy and issues an entitlement.

The token is the input, not the body. user_type, employee_verified and company are read from the token after signature, issuer, audience and expiry checks. Body fields are treated as hints: a subjectId that contradicts the token's sub is a 403, and a contradicting userType is logged and ignored. A portal that could assert its own entitlements would make this service decorative.

Idempotent. Repeating a call with the same Idempotency-Key (or the same subject + session) returns the original entitlement with replayed: true rather than minting a second one.

Creates a session in state CREATED. Creation grants nothing: a session without an entitlement carries no access.

deviceRef is an opaque portal-issued handle. MAC addresses are not accepted: iOS 14+ and Android 15 randomise them per network, so a MAC is not a stable device identity and must never anchor metering.

Declarative and idempotent, matching the applyAccess verb in ADR-007: re-applying the same entitlementId is a no-op returning replayed: true.

Refuses with 422 if no entitlementId is supplied. This service never invents access: every grant traces to an entitlement (ADR-008).

Idempotent (revokeAccess in ADR-007). Revoking twice is a no-op.

Returns every configured member company. The webhook secret is never included — only hasSecret, saying whether one is set.

Full replace, not a merge. secret is write-only: supplying it stores a new webhook signing secret, omitting it leaves the current one in place, and no response anywhere returns it.

Removes configuration and secret. Users already imported from that company are not touched — deleting a connector is not a way to delete people.

GET {endpoint-origin}/health against each configured endpoint, using that company's timeout. Read-only; nothing is stored. This is how a misconfigured connector is found before an employee hits it at login.

Two modes, and the difference matters. preview works out what would happen and writes nothing; commit does it.

A row is matched in this order: CCCD link token → employee_ref → email → create. Order is not arbitrary — a CCCD identifies a person, an email identifies an inbox.

citizenId is converted to HMAC-SHA256(cccd, realm salt) on arrival and the raw value is dropped. It is not stored, not logged and not echoed in the response.

Import never sets employee_verified. A data load is not a verification; only a live HR check at login may set that.

A preview evaluates each row against the realm as it is now, not against earlier rows in the same file. Two rows sharing a CCCD therefore preview as two creates and commit as create + link. The counts differing between the two modes is expected.

Authenticated by HMAC over the raw body, not by a bearer token — the caller is a member company's HR system, not an operator.

X-GIW-Signature is base64(HMAC-SHA256(secret, "{timestamp}.{rawBody}")). Signing the bytes as received is the point: re-serialising the parsed object first would verify our own serialiser, not the sender.

Only events that change who can log in are applied. Events about what someone gets — a loyalty tier, a package purchase — are recorded and not applied, because writing a tier into Keycloak would make it a cache of the loyalty system, and a stale one.

POC limitation. Duplicate suppression and the event log are in memory. An event arriving while Keycloak restarts is lost, and the provider will retry a few times and give up — an employee whose departure nobody recorded. See ADR-012, T-WEBHOOK-DURABILITY.