Reference: Keycloak Multiple Realms
The current approach uses a single partners realm with groups to represent each
organisation. As identified in the research, groups-in-a-single-realm carries
security risks — a misconfiguration could expose one organisation's user directory
to another.
This plan migrates to per-org Keycloak realms with subdomain-based routing.
partners realm (groups: maple-surgery, oak-practice)
→ identity broker → veripath realm → booking app
→ staff-manager (auth.veripath.co.uk/staff/)
maple-surgery.gp.veripath.co.uk
→ booking app (single codebase, single DB)
→ TenantMiddleware resolves "maple-surgery" → PartnerOrg lookup
→ Dynamic OIDC backend → Keycloak realm "maple-surgery"
→ Data scoped by org_id from JWT
oak-practice.gp.veripath.co.uk
→ same pattern → Keycloak realm "oak-practice"
Veripath manages all realms via the Keycloak master admin. Each org gets access
to their own realm's admin console for user management.
Add PartnerOrg model
slug, name, keycloak_realm, is_activeTenant model (which represents GP/Dental sectors)Update TenantMiddleware
Tenant found by subdomain, check PartnerOrgrequest.partner_org with the matched orgrequest.tenant to the GP Tenant for existing functionalityCreate dynamic OIDC backend
OIDCAuthenticationBackend extending mozilla-django-oidcrequest.partner_org.keycloak_realmveripath realm URLs for existing GP/Dental tenantsAdd org_id scoping
org_id in their JWTorg_idCreate per-org realms
maple-surgery realm with gp-booking-app OIDC clientoak-practice realm with gp-booking-app OIDC clientMigrate existing users
jane.smith and john.doe from partners realm to their own realmsorg_id, position)Rewrite /opt/onboard-partner.sh
PartnerOrg row in the booking app databaseNginx wildcard subdomain
*.gp.veripath.co.uk to the server_name directive for gp.veripath.co.ukStaff Manager — multi-realm support
/staff/{realm}/)Cleanup
veripath realmpartners realm| Component | Realm | Notes |
|---|---|---|
| gp.veripath.co.uk | veripath | Existing GP tenant, unchanged |
| dental.veripath.co.uk | veripath | Existing Dental tenant, unchanged |
| AES Portal | veripath | Dev/admin access only |
| AES service accounts | veripath | Machine-to-machine, unchanged |
| Booking app database | — | Single shared DB |
| Staff Manager URL | — | Retained at auth.veripath.co.uk |
maple-surgery realm, test with existing codepartners realm