ADR-0001: Identity, Access Management, and Device Registration Architecture

1. Keycloak as the Single Source of Truth for IAM

Keycloak is the authoritative source for identity and access control across the platform. All authentication and authorisation decisions are delegated to Keycloak. The Quarkus backend (gps-api) is the sole OIDC resource server and the single API surface for external consumers.

Frontend clients (mobile, web) and the support console are separate OIDC clients that obtain tokens and call gps-api. Internal services that interact directly at the database layer are outside the Keycloak authorisation scope and authenticate to Postgres using dedicated database credentials.

2. Authorization Services over Groups for Device-Level Access

Device-level access control will use Keycloak Authorization Services (resource-based permissions) rather than a group-per-device hierarchy.

3. Keycloak Groups for Logical User Collections Only

Keycloak groups are retained exclusively for logical collections of users, not for device access. Examples:

• support-engineers — users permitted to impersonate other users

• org-admins — users with administrative rights within a Keycloak Organisation

• beta-users — users enrolled in feature flag cohorts

This keeps the group namespace small, bounded, and human-meaningful.

4. Keycloak Organizations for Enterprise Identity Federation

Enterprise customers will use Keycloak Organizations (GA in Keycloak 26 / RHBK) to federate their own IDP for authentication while Keycloak remains the authoriser.

• Enterprise users authenticate via their corporate IDP; Keycloak brokers the identity

• Org membership flows into tokens and is used to evaluate org-scoped device policies

• Devices owned by or shared with an organisation are accessible to org members based on their org role

5. Impersonation for Support Engineers

Keycloak's built-in impersonation capability is used for support engineer troubleshooting. Members of the support-engineers group are granted the impersonation role scoped appropriately within Keycloak.

Because all permissions are evaluated against the token subject, an impersonating support engineer receives a token that represents the target user. The backend requires no special casing — the impersonating engineer sees exactly what the target user sees, inheriting their device access policies automatically.

6. Two-Phase Device Lifecycle

Device registration is split into two distinct phases, each with its own saga, Kafka event, and set of downstream consumers.

7. Kafka Event Schemas

All events must be self-contained — consumers must not need to call back into the registration service or Keycloak to act on them. A schema registry (Avro or Protobuf) must be used to enforce these contracts across all consumers.

Positive

• Authorization Services resources scale significantly better than a group-per-device hierarchy for the anticipated data volumes

• Impersonation is handled at the identity layer — no application-level special casing required

• Two-phase registration cleanly separates device identity (platform concern) from ownership (user concern), making each saga independently testable and failure-resilient

• Per-device Keycloak service accounts give each device a cryptographically distinct identity with no shared credential risk across the fleet

• Token caching with 401-triggered refresh is resilient to clock drift and extended offline periods without requiring time-synchronisation on embedded hardware

• BLE proximity detection provides a seamless association UX with no manual code entry required, while falling back gracefully to manual claim codes

• HMAC-derived rotating BLE advertisement codes prevent passive enumeration of device identities

• Kafka decouples the registration service from downstream consumers, improving resilience

• The single resource server client model is a clean fit for one cohesive API surface

• Internal services retain the least-privilege DB role pattern without polluting the OIDC model

Negative / Risks

• Keycloak Authorization Services is more complex to set up than group-based access; resource and policy provisioning requires careful design and more Admin API surface

• Per-device Keycloak clients at fleet scale (millions of devices) introduces a large number of clients in the realm — Keycloak's client management at this scale should be load-tested early, particularly client lookup and token issuance performance

• Every device platform registration involves multiple sequential Keycloak API calls — the registration service must be load-tested at realistic fleet onboarding volumes

• Keycloak Organizations is a maturing feature; interaction with Authorization Services policy evaluation requires early prototype validation

• NV memory encryption (ESP32 flash encryption) must be enforced for production devices — the client secret stored in NV is the long-term credential and must be protected accordingly

• Internal services writing directly to Postgres can cause drift between data state and Keycloak authorization state — any internal service operation with authorization implications must also update the corresponding Keycloak resource/policy via the registration service or a dedicated IAM sync pathway

• HMAC-derived claim code validation requires the registration service to maintain or derive the same time-windowed nonce — clock skew between device and server must be accounted for in the validation window

Neutral

• The quarkus-keycloak-authorization extension handles the evaluation side well; the provisioning side (resource/policy CRUD) requires direct Admin REST API calls

• Schema registry adoption (Avro/Protobuf) is an additional infrastructure component but is strongly recommended given the multi-consumer event model

• BLE advertisement integration requires the mobile app to handle the rotating claim code derivation client-side and submit it through the standard association flow — no additional backend surface is required