# ADR-004: Central SSO with Keycloak

| Field | Value |
| --- | --- |
| Status | Accepted |
| Date | 2025-06-01 |
| Deciders | Platform Architecture |
| Supersedes | — |
| Superseded by | — |

## Context

Platform staff, tenant staff, and multiple subsystem UIs need a single identity for the core SuperApp. Building a custom IdP is high risk.

## Decision

Keycloak (`superapp` realm, `torbatyar` theme) is the only central login UX for platform and tenant staff. Identity & Access Service acts as BFF for OIDC token exchange, mobile OTP handoff, and profile sync. End-customer auth for tenant-facing modules may remain local to that module's database when SSO is optional.

## Consequences

### Positive

- One login for staff across subsystems
- Standard OIDC/JWT validation in all services
- Themeable login without forking IdP core

### Negative

- Operational dependency on Keycloak
- Dual user records (Keycloak + Core/Identity) require linking (`keycloak_sub`)

## Alternatives Considered

1. Custom JWT-only auth without IdP
2. Auth0 / cloud IdP

## Related Documents

- [Identity Architecture](../identity-architecture.md)
- [Authorization Architecture](../authorization-architecture.md)
- [Services Contracts](../../reference/services-contracts.md)