Skip to main content

Multi-Tenant IAM

Summary​

Keymate provides multi-tenant identity and access management by isolating Tenants within a shared realm. Each Tenant operates as an independent organizational boundary with its own users, departments, roles, groups, and applications. Multiple Tenants share platform infrastructure while maintaining strict data and access separation.

Why It Exists​

B2B, B2B2C, and G2C platforms serve multiple organizations from shared infrastructure. Each organization requires its own users, roles, and application access — isolated from other organizations on the same platform. Without Tenant isolation, one organization's configuration changes, user data, or access policies could affect another.

Keymate's multi-tenant model addresses this by treating each Tenant as a self-contained organizational boundary within a single realm, avoiding the operational overhead of managing separate realms per organization.

Where It Fits in Keymate​

Multi-tenant IAM is the foundational concept in the Organization Model. Every other organization-model concept — Tenant Model, Organization Hierarchy, Delegated Administration, and Org-Aware Tokens & Sessions — builds on Tenant isolation.

Boundaries​

What this concept covers:

  • Tenant as an organizational boundary within a shared realm
  • Per-Tenant scoping of users, departments, roles, groups, and applications
  • The relationship between Tenants and the underlying Keycloak Organization concept

What this concept does not cover:

  • Infrastructure-level isolation (separate databases, network segmentation) — see deployment documentation
  • Single-tenant deployment models
  • How roles and groups are assigned within a Tenant — see Delegated Administration

How It Works​

Tenant as Organizational Boundary​

A Tenant in Keymate wraps the Keycloak Organization concept and extends it with additional capabilities: role mappings, group associations, application assignments, and configurable properties. Each Tenant acts as a self-contained organizational boundary.

Shared Realm with Per-Tenant Scoping​

All Tenants exist within a single Keycloak realm. The platform scopes data access by Tenant — queries for users, departments, and applications always operate within a Tenant context. A user in one Tenant cannot see or interact with resources belonging to another Tenant unless explicitly granted cross-Tenant access.

Explicit User Assignment​

Users belong to Tenants through explicit assignments, not through automatic discovery or domain matching. Each assignment links a user to a specific Tenant and department, and carries its own role mappings and attributes. A user can hold assignments in multiple Tenants, but each assignment is independent.

Per-Tenant Application Catalog​

Each Tenant maintains its own set of assigned applications. Platform administrators register applications in a shared catalog, and Tenant administrators assign specific applications to their Tenant. Users within the Tenant can access only the applications assigned to that Tenant.

Diagram​

Example Scenario​

Scenario​

Two organizations — Acme Corp and Beta Inc — share a platform. Each operates independently with its own departments, users, and applications.

Input​

  • Actor: Platform administrator
  • Resource: Shared platform realm
  • Action: Provision two Tenants with separate departments and application assignments
  • Context: Acme Corp needs access to a reporting application; Beta Inc needs access to an analytics application

Expected Outcome​

  • Result: Two isolated Tenants created within the same realm
  • Why: Each Tenant has its own department structure, user assignments, and application catalog. Acme Corp users see the reporting application; Beta Inc users see the analytics application. Neither Tenant's users can access the other Tenant's resources.

Common Misunderstandings​

  • "Each Tenant requires a separate Keycloak realm." — No. Keymate hosts multiple Tenants within a single realm, reducing operational complexity while maintaining strict isolation.
  • "Users are automatically visible to all Tenants." — No. Users belong to Tenants through explicit assignments. A user without an assignment to a Tenant has no visibility or access within that Tenant.
  • "Multi-tenancy means shared data with filtering." — Keymate enforces Tenant boundaries at the organizational model level, not through query-time filtering alone. Each Tenant's roles, groups, and applications are structurally scoped.
warning

A user can hold assignments in multiple Tenants. Each assignment is independent — roles granted in one Tenant do not carry over to another.

Design Notes / Best Practices​

  • Use the Tenant Model to understand the full set of capabilities available on each Tenant (roles, groups, applications, properties).
  • Assign applications to Tenants through administrative action rather than making all applications globally visible.
  • Use Org-Aware Tokens & Sessions to ensure downstream services know which Tenant context the user is operating in.
tip

When a user holds assignments in multiple Tenants, use the default assignment mechanism to determine which Tenant context applies when no explicit selection is made. See Membership & Application Assignment for details.

  • Provisioning isolated Tenants for a B2B platform serving multiple enterprises
  • Migrating from a multi-realm architecture to a shared-realm multi-tenant model
  • Evaluating Keymate's multi-tenancy capabilities for a G2C platform

Tenant Model

Roles, groups, applications, and properties that define a Tenant.

Organization Hierarchy

Hierarchical department structures within a Tenant.

Delegated Administration

Scoped administration at Tenant, department, and user levels.

Org-Aware Tokens & Sessions

Token exchange that embeds organizational context.