Skip to main content

Tenant-Scoped Identity

Summary​

Keymate enforces Tenant-level isolation across all identity operations. Every identity entity — user assignments, attribute definitions, attribute values, role assignments, group mappings, and application assignments — belongs to a specific Tenant within a realm. This dual-level scoping (realm + Tenant) ensures that identity data belonging to one Tenant is invisible and inaccessible from another Tenant's administrative and operational boundary, even when multiple Tenants coexist within the same identity server realm.

Why It Exists​

Multi-Tenant platforms must guarantee that one Tenant's identity data does not leak to another. Without Tenant-scoped isolation, a Tenant administrator could view or modify users, roles, and attributes belonging to a different Tenant. Tenant-scoped identity ensures that each Tenant operates within a self-contained boundary — its own users, its own attribute definitions, its own role assignments — while sharing the underlying infrastructure.

Where It Fits in Keymate​

Tenant scoping is the isolation layer that sits between the shared identity infrastructure and the per-Tenant identity experience. The identity model defines what an identity contains. The organization model defines the Tenant and department hierarchy. Tenant-scoped identity ensures that all identity operations respect Tenant boundaries. Token claims carry the Tenant context so that downstream services can enforce Tenant isolation in their own data access.

Boundaries​

This page covers how Tenant boundaries isolate identity data and operations. It does not cover:

How It Works​

Dual-Level Scoping​

Two dimensions scope every identity entity:

  1. Realm — the identity server's top-level administrative boundary. A realm contains the shared configuration for authentication flows, identity providers, and session policies.
  2. Tenant — a Keymate-specific isolation boundary within a realm. Each Tenant represents a distinct organizational entity (a government agency, a company, a division) with its own identity data.

This dual-level design allows multiple Tenants to share a realm's authentication infrastructure while maintaining strict data separation at the Tenant level.

What Tenant Scoping Isolates​

Tenant boundaries apply to:

  • User organizational assignments — a user's assignment to a department belongs to a specific Tenant. The same user can have separate assignments in different Tenants, each with its own roles and attributes.
  • Attribute definitions — Tenant-scoped attribute definitions are visible and usable only within the defining Tenant. A global-scoped definition is shared across all Tenants.
  • Attribute values — values assigned to users carry a Tenant reference. A user's "clearance level" in Tenant A is independent of their "clearance level" in Tenant B.
  • Role assignments — roles granted through organizational assignments are bound to the Tenant context. The same realm role can be assigned differently per Tenant.
  • Group mappings — groups mapped to Organizations within a Tenant are managed within that Tenant's boundary.
  • Application assignments — which applications are available to an Organization is a Tenant-scoped decision.
  • Department templates — templates for creating department structures are defined per Tenant.

Cross-Tenant User Identity​

A single user (one subject identifier) can hold assignments across multiple Tenants. The user's core profile (name, email, authentication credentials) is shared at the realm level, but their organizational context, roles, attributes, and group memberships are Tenant-specific. The platform does not merge or combine cross-Tenant data — each Tenant sees only its own assignments for a user.

Tenant Context in Tokens​

When a user authenticates and selects an organizational context, the resulting access token carries the Tenant identifier. Downstream services use this Tenant context to scope their own data access, queries, and authorization decisions. The token never contains data from a Tenant other than the active one.

Diagram​

Example Scenario​

Scenario​

A government platform hosts two agencies (Tenant A and Tenant B) within the same realm. A user works for both agencies and has different roles and clearance levels in each. An administrator in Tenant A queries the user's identity.

Input​

  • Actor: Tenant A administrator
  • Resource: User identity data
  • Action: View user's assignments, roles, and attributes
  • Context: Administrator is authenticated within Tenant A's administrative boundary

Expected Outcome​

  • Applied — The administrator sees the user's assignments, roles, and attributes within Tenant A only. Tenant B data (the user's separate assignment, different roles, and different clearance level) is invisible.
  • Why: Tenant-scoped identity ensures that all identity queries filter by the active Tenant context. The administrator's session carries the Tenant A scope, and the platform enforces this boundary on all returned data.

Common Misunderstandings​

  • "Tenant isolation means separate user accounts per Tenant" — No. A single user (one set of credentials) can hold assignments in multiple Tenants. Isolation applies to organizational data (assignments, roles, attributes), not to the user's authentication identity.

  • "Global attribute definitions bypass Tenant isolation" — Global-scoped definitions are visible across Tenants, but the values assigned to users are still Tenant-scoped. A global "employee ID" definition can exist, while each Tenant assigns its own values independently.

  • "Administrators can query users across Tenants" — No. A Tenant administrator sees only the users who have assignments within their Tenant. Users without assignments in that Tenant are invisible to its administrators.

warning

When designing services that consume identity data, always filter by the Tenant identifier from the access token. Relying on the user identifier alone without Tenant scoping can expose data across Tenant boundaries.

Design Notes / Best Practices​

  • Define attributes at the Tenant scope unless you have a genuine cross-Tenant need. Tenant-scoped definitions prevent unintended attribute leakage.
  • Design user provisioning workflows to create assignments per Tenant rather than duplicating user accounts. One user with multiple assignments is preferable to multiple users with identical credentials.
  • Enforce Tenant context propagation through the entire service chain. Every service that accesses identity data should validate the Tenant context from the token or request.
tip

Use global attribute definitions for attributes that every Tenant requires (such as standard HR fields). Use Tenant-scoped definitions for attributes unique to a specific Tenant's domain.

  • Hosting multiple independent organizations within a shared identity infrastructure
  • Supporting users who work across organizational boundaries
  • Isolating sensitive identity attributes per Tenant for compliance
  • Restricting administrative visibility to Tenant-specific identity data

Identity Model

Core identity representation that Tenant scoping isolates

Org-Unit-Aware Identity

Department hierarchy within a Tenant boundary

Organization Model

Tenant and department hierarchy definitions

Scoped Administration Model

How admin authority delegates within a Tenant