# Identity Architecture

## Layers (mandatory separation)

| Layer | Who | Central Keycloak SSO |
| --- | --- | --- |
| Platform core | Platform admin, tenant owner/staff | Required |
| Subsystem staff UIs | Cafe panel, CRM, … | Required — same JWT |
| Tenant end-customer | e.g. digital menu guest | Optional — may be local to module DB |

## Central Login

Keycloak realm `superapp`, theme `torbatyar`:

- Tab: password (username/email/mobile + password)
- Tab: mobile OTP (Identity `/auth/mobile/*` → handoff → `/auth/callback`)

Frontend `/login` and `/register` redirect to Keycloak. Admin login uses the same SSO path.

## Core Users

Table `users` in `core_platform_db`: `mobile` (unique, required), `mobile_verified`, `keycloak_sub`, `current_tenant_id`, platform role.

`UserService.resolve_current` maps:

- Local OTP JWT → `users.id`
- Keycloak JWT → `users.keycloak_sub` (JIT link/create when possible)

## Identity Service

Database `identity_access_db`. Profiles hold Keycloak subject, mobile verification, optional `core_user_id`. OTP SMS is delegated to Core (`CoreOtpClient`) — no duplicate SMS logic.

## Mobile Mandate

Mobile is mandatory and OTP-verified ([ADR-005](adr/ADR-005.md)).

## Related Documents

- [Authorization Architecture](authorization-architecture.md)
- [ADR-004](adr/ADR-004.md) · [ADR-005](adr/ADR-005.md) · [ADR-007](adr/ADR-007.md)
- [Services Contracts](../reference/services-contracts.md)
- [Identity service README](../../backend/services/identity-access/README.md)