Skip to main content

Tenant Model

Summary​

A Tenant represents an organizational boundary in Keymate. Each Tenant carries its own role mappings (realm and client roles), group associations, application assignments, and configurable properties. The Tenant model extends Keycloak's Organization concept with these additional capabilities, forming the container for all organizational configuration.

Why It Exists​

Each organization using the platform needs an isolated context with its own configuration. Roles that apply to one organization may not apply to another. Applications available to one organization may not be licensed for another. The Tenant model provides the structure for managing these per-organization configurations without duplicating infrastructure.

Where It Fits in Keymate​

The Tenant model sits between the Multi-Tenant IAM foundation and the more specific concepts like Organization Hierarchy and Membership & Application Assignment. It defines what a Tenant contains; the other concepts define how those contents are structured and managed.

Boundaries​

What this concept covers:

  • The structure and capabilities of a Tenant entity
  • Role mappings, group associations, and application assignments at the Tenant level
  • Property templates for typed Tenant metadata

What this concept does not cover:

How It Works​

Tenant Identity and Metadata​

Each Tenant has a unique identity within the realm. The Tenant wraps a Keycloak Organization and extends it with Keymate-specific capabilities. Basic metadata — name, identifier, and status — is stored on the Tenant.

Role Mappings​

A Tenant can carry both realm-level and client-level role mappings. These roles define what permissions are available within the Tenant's boundary. Roles assigned at the Tenant level serve as the baseline for all users and departments within that Tenant.

Group Associations​

Tenants can be associated with groups. Group associations allow Tenant-wide policies and access controls to be applied through Keymate's Group Model.

Application Assignments​

Each Tenant maintains a set of assigned applications drawn from the platform's application catalog. An application must be assigned to a Tenant before the Tenant's users can access it. Applications carry a type (API, web, or resource server), a status (active or deprecated), and an assignability flag that controls whether the application can be assigned to Tenants.

Property Templates​

Tenants support configurable properties defined through property templates. Each property template specifies a name and a data type — string, numeric, date, or boolean. Property templates allow platform administrators to define a consistent metadata schema that all Tenants can populate with their own values.

Diagram​

Example Scenario​

Scenario​

A platform administrator configures a new Tenant for Acme Corp, assigning roles, applications, and custom properties.

Input​

  • Actor: Platform administrator
  • Resource: New Tenant for Acme Corp
  • Action: Configure Tenant with role mappings, application assignments, and property values
  • Context: Acme Corp needs access to the portal and API applications, with custom properties for region and contract type

Expected Outcome​

  • Result: Tenant created with two realm roles, one client role, two assigned applications, and two populated property values
  • Why: The Tenant model stores all configuration within the Tenant boundary. Users assigned to this Tenant inherit the Tenant-level role baseline, can access the assigned applications, and operate within the context defined by the Tenant's properties.

Common Misunderstandings​

  • "Tenant roles automatically apply to all users." — Tenant-level roles define what is available within the Tenant. Users receive roles through their individual assignments and department memberships, not automatically from the Tenant.
  • "All applications are visible to all Tenants." — Applications must be explicitly assigned to a Tenant. Unassigned applications are not accessible to the Tenant's users.
  • "Property templates are optional metadata." — Property templates define a structured schema for Tenant configuration. They enforce data types and provide a consistent contract for Tenant-specific metadata.
warning

Deprecated applications remain assigned to Tenants that already use them but cannot be newly assigned to additional Tenants. Review application status before planning new Tenant configurations.

Design Notes / Best Practices​

  • Define property templates at the platform level before provisioning Tenants to ensure consistent metadata across all organizations.
  • Use the assignability flag on applications to control which applications are available for Tenant assignment.
  • Separate realm-level roles (cross-application) from client-level roles (application-specific) when configuring Tenant role mappings.
tip

Use Tenant Onboarding templates to pre-configure role mappings and property schemas, reducing manual configuration when provisioning new Tenants.

  • Configuring per-Tenant role mappings and application catalogs for a SaaS platform
  • Defining typed property templates for regulatory or contractual Tenant metadata
  • Assigning different application sets to Tenants based on licensing agreements

Multi-Tenant IAM

Foundational tenant isolation within a shared realm.

Organization Hierarchy

Department structures within a Tenant.

Membership & Application Assignment

User assignments and application catalogs.

Tenant Onboarding

Templates and cloning for Tenant provisioning.