Appearance
Keycloak Identity Platform
Microtec ERP uses a customized Keycloak 26.2.4 instance as the central identity and access management platform. It is extended with 7 proprietary Java SPI extensions to support multi-tenant ERP workflows, Google-style account switching, and automated realm provisioning.
Deployment
Keycloak runs as a containerized workload inside the Public Container Apps Environment (CAE), alongside the API Gateway. It is internet-facing with HTTPS ingress and handles all authentication flows for ERP and Business Owner portals.
Realm Architecture
Keycloak hosts two separate realms to isolate ERP tenant users from Business Owner portal administrators.
| Realm | Purpose | Apps |
|---|---|---|
microtec | ERP tenant users | All 9 MFE apps (accounting, HR, finance, sales, purchase, inventory, distribution, fixed-assets, erp-home) |
businessowner | BO portal admins | bussiness-owners app (port 4301) |
Why Two Realms?
Separating realms enforces complete isolation of user pools, token policies, and session management between tenant users and platform administrators. A Business Owner admin cannot inadvertently access ERP user sessions and vice versa.
Custom SPI Extensions
Seven Java SPI (Service Provider Interface) extensions are deployed as JAR files into Keycloak's providers/ directory:
| # | Extension | Type | Purpose |
|---|---|---|---|
| 1 | keycloak-multiaccount | Authenticator + REST | Google-style tenant switching without logout |
| 2 | keycloak-seeding | EventListener + REST | Auto-provision realms/clients/roles on startup |
| 3 | phone-email-authenticator | Authenticator | Login via phone number or email |
| 4 | tenant-mapper | Protocol Mapper | Inject tenant context into JWT claims |
| 5 | role-sync | EventListener | Sync Keycloak roles to ERP permission tables |
| 6 | audit-event-listener | EventListener | Emit auth events to Azure Service Bus |
| 7 | custom-theme-provider | Theme | RTL-aware Arabic/English UI themes |
Authentication Flow Priority
The default browser authentication flow for the microtec realm uses three sequential execution steps. Priority determines the order in which each authenticator is attempted:
| Step | Authenticator | Priority | Description |
|---|---|---|---|
| 1 | MAC (Multi-Account Cookie) | 10 | Checks AES-256-GCM encrypted cookie for active account session |
| 2 | Cookie | 20 | Standard Keycloak browser session cookie check |
| 3 | Identity Provider Redirector | 30 | Redirects to configured external IdP (Azure AD, Google, etc.) |
Priority Order is Critical
MAC must run at priority 10 (before standard Cookie at 20). If Cookie runs first, it intercepts multi-tenant sessions before the account switcher can activate the correct tenant context. This was a known production bug fixed in Session 16.
Custom Authentication Flow: phone-email-authenticator
The phone-email-authenticator flow replaces the standard username/password form to allow login with either an email address or a phone number:
Environment-Specific Configuration
| Config Key | Value |
|---|---|
| Keycloak version | 26.2.4 |
| Container image | Custom build with SPIs bundled |
| CAE type | Public (internet-facing ingress) |
| Min replicas | 1 |
| Max replicas | 3 |
| CPU | 1.0 vCPU |
| Memory | 2Gi |
| Health probe path | /health/ready (port 9000) |
| Admin console | Disabled in production |
Related Documentation
- Multi-Account SPI — Google-style tenant switching details
- Seeding SPI — Automated realm provisioning
- Realm Configuration — Client IDs, token lifetimes, OIDC settings
- Infrastructure: Container Apps — CAE deployment
- Auth Architecture — Token flow and authorization patterns