Skip to content

Keycloak Realms ​

Microtec uses two Keycloak realms to isolate authentication contexts for different user populations. Each realm has distinct client configurations, identity providers, and token policies.


Realm Overview ​

RealmNameUsersDomain
ERPmicrotecTenant employees using the ERP systemauth.{env-domain}/realms/microtec
Business OwnerbusinessownerTenant administrators and business ownersauth.{env-domain}/realms/businessowner

microtec Realm (ERP) ​

Purpose ​

The microtec realm authenticates all regular ERP users: accountants, inventory managers, HR staff, and other employees who use day-to-day ERP functionality. It is multi-tenant aware — each user belongs to a tenant group that scopes their data access.

Clients ​

Client IDTypeUsage
erp-homePublic (SPA)ERP home and navigation shell (port 4401)
apps-accountingPublic (SPA)Accounting module (port 4402)
apps-hrPublic (SPA)HR module (port 4403)
apps-financePublic (SPA)Finance module (port 4404)
apps-salesPublic (SPA)Sales module (port 4405)
apps-purchasePublic (SPA)Purchase module (port 4406)
apps-inventoryPublic (SPA)Inventory module (port 4407)
app-distributionPublic (SPA)Distribution module (port 4408)
fixed-assetsPublic (SPA)Fixed Assets module (port 4409)
erp-backendConfidentialBackend services (JWT introspection)
zap-scannerService accountOWASP ZAP authenticated scans (stage only)

Client Configuration (SPA Clients) ​

All Angular SPA clients share the same configuration pattern:

json
{
  "clientId": "apps-accounting",
  "protocol": "openid-connect",
  "publicClient": true,
  "standardFlowEnabled": true,
  "implicitFlowEnabled": false,
  "directAccessGrantsEnabled": false,
  "pkceCodeChallengeMethod": "S256",
  "redirectUris": [
    "https://erp.microtecstage.com/*",
    "http://localhost:4402/*"
  ],
  "webOrigins": [
    "https://erp.microtecstage.com",
    "http://localhost:4402"
  ],
  "attributes": {
    "backchannel.logout.url": "https://gateway.microtecstage.com/logout/backchannel",
    "backchannel.logout.session.required": "true"
  }
}

PKCE Required

All SPA clients use PKCE (S256) with the Authorization Code flow. Implicit flow is disabled. This prevents token leakage via the URL fragment and is required by current OAuth 2.0 security best practices.

Token Configuration ​

SettingValue
Access token lifetime15 minutes
Refresh token lifetime8 hours (aligned with working day)
SSO session max8 hours
Offline accessDisabled
Token signing algorithmRS256

Claims in microtec Tokens ​

The erp-policy-mapper SPI (custom Keycloak extension) adds the following claims to tokens:

json
{
  "sub": "keycloak-user-uuid",
  "iss": "https://auth.microtecstage.com/realms/microtec",
  "aud": "apps-accounting",
  "exp": 1705312800,
  "preferred_username": "ahmed.ali",
  "email": "ahmed.ali@acmecorp.com",
  "given_name": "Ahmed",
  "family_name": "Ali",
  "tenant_id": "ACME_Corp",
  "roles": ["Accountant", "AccountingManager"],
  "permissions": ["Accounting.Read", "Accounting.Write", "Accounting.Approve"]
}

See RBAC Policies for how roles maps to permissions.


businessowner Realm ​

Purpose ​

The businessowner realm authenticates tenant administrators and business owners who manage subscriptions, configure tenant settings, onboard users, and access cross-tenant administrative functions via the Business Owner portal.

Clients ​

Client IDTypeUsage
bussiness-ownersPublic (SPA)BO Portal Angular app (port 4301)
bo-backendConfidentialBO backend services
accountBuilt-in KeycloakAccount management console (DISABLED — see note)

account-console Client Is Disabled

The Keycloak built-in account-console client is disabled in both realms. Users cannot self-manage their Keycloak account via the Keycloak UI. Account management (password reset, profile updates) is handled through the Microtec BO portal using the Keycloak Admin REST API, not the Keycloak account console.

This is intentional — the account console exposes Keycloak internals to end users and was disabled during realm provisioning (see ConfigureRealmClients step in the Keycloak provisioning automation).

Token Configuration ​

SettingValue
Access token lifetime30 minutes (BO sessions are longer-lived)
Refresh token lifetime24 hours
SSO session max24 hours
MFAOptional (configurable per tenant)

Claims in businessowner Tokens ​

json
{
  "sub": "keycloak-user-uuid",
  "iss": "https://auth.microtecstage.com/realms/businessowner",
  "preferred_username": "owner@acmecorp.com",
  "tenant_id": "ACME_Corp",
  "roles": ["TenantOwner"],
  "managed_tenants": ["ACME_Corp", "ACME_Branch"]
}

Identity Providers ​

Both realms support external IdP federation for enterprise SSO:

IdPRealmFlow
Microsoft Entra ID (Azure AD)BothOIDC federation
Google WorkspacemicrotecOIDC federation
SAML 2.0 EnterprisemicrotecSAML IdP (per-tenant config)

Authentication flow priority (configured in erp-policy-mapper SPI):

FlowPriorityTrigger
MAC address flow10Corporate device on internal network
Cookie/session flow20Existing Keycloak session
IdP redirect flow30External IdP configured for user's email domain
Username/password40 (fallback)Default

Realm Provisioning ​

Realms are provisioned automatically via the Keycloak Provisioning Automation (see KeycloakProviders/). The provisioning sequence:

  1. Create realm with token lifetimes and security policies
  2. Create and configure all clients (disable account-console, enable account)
  3. Import client scopes and protocol mappers
  4. Configure authentication flows with correct priorities
  5. Register erp-policy-mapper SPI for permission claim injection
  6. Set up identity providers (if configured for the environment)

Backchannel Logout

Backchannel logout is configured on all SPA clients and verified in the provisioning code. When a user logs out from any ERP app, Keycloak sends a backchannel logout request to https://gateway.{domain}/logout/backchannel. The Gateway service broadcasts this to all internal services to invalidate session caches. This prevents stale sessions persisting in Redis after logout.

Internal Documentation — Microtec