Skip to main content

Organization Hierarchy

Summary​

Tenants contain a hierarchical department structure where each department carries its own role mappings, custom attributes, and external system identifiers. Departments form a parent-child tree that mirrors real-world organizational structures. Keymate also supports department templates and template groups that allow reusable department structures to be defined and cloned when provisioning new Tenants.

Why It Exists​

Enterprises organize people into departments, divisions, and teams. Authorization decisions often depend on where a user sits within this structure — a finance department member needs different access than an engineering department member. The Organization Hierarchy captures this structure so that role assignments, attributes, and policies can be scoped to specific organizational units.

Where It Fits in Keymate​

The Organization Hierarchy operates within the Tenant Model. Each Tenant contains its own independent department tree. User assignments (covered in Membership & Application Assignment) link users to specific departments within a Tenant. Role assignments at the department level feed into Delegated Administration and Org-Aware Tokens & Sessions.

Boundaries​

What this concept covers:

  • Department hierarchy (parent-child tree) within a Tenant
  • Role mappings per department (realm-level and client-level)
  • Custom attributes on departments
  • External identifiers for integration with external systems
  • Department templates and template groups

What this concept does not cover:

How It Works​

Department Hierarchy​

Each department belongs to a single Tenant and can optionally reference a parent department, forming a tree structure. A Tenant can have multiple root departments (departments with no parent), and each root can have an arbitrary depth of child departments.

Role Mappings per Department​

Every department carries its own role mappings at two levels:

  • Realm-level roles — roles that apply across all applications within the Tenant
  • Client-level roles — roles scoped to a specific application

These role mappings define what permissions are available to users assigned to that department. Department-level roles work alongside Tenant-level and user-level roles to form the complete role hierarchy described in Delegated Administration.

Custom Attributes​

Departments support key-value attributes for storing organizational metadata. These attributes can carry information such as cost center codes, location identifiers, or compliance classifications. Downstream systems and policies can reference these attributes during authorization decisions.

External Identifiers​

Each department can carry external identifiers that map it to corresponding entities in external systems — such as HR platforms, ERP systems, or directory services. External identifiers enable bidirectional synchronization between Keymate's organizational structure and external sources of truth.

Department Templates​

A department template defines a reusable department structure, including role mappings, attributes, and external identifiers. Templates allow platform administrators to define standard department configurations once and apply them across multiple Tenants.

Template Groups​

Template groups collect multiple department templates into a single unit that can be cloned as a whole. When a template group is cloned, all department templates within the group are instantiated, preserving the hierarchy and configuration defined in the templates. This mechanism powers the Tenant Onboarding flow.

Diagram​

Example Scenario​

Scenario​

An organization structures its engineering division with separate backend and frontend teams, each requiring different application access.

Input​

  • Actor: Tenant administrator for Acme Corp
  • Resource: Engineering department with two child departments
  • Action: Create a department hierarchy with role mappings
  • Context: Backend team needs API access roles; frontend team needs portal access roles

Expected Outcome​

  • Result: Three departments created — Engineering (root), Backend Team (child), Frontend Team (child) — each with distinct role mappings
  • Why: The hierarchy mirrors the real organizational structure. Users assigned to the Backend Team inherit that department's roles, while Frontend Team members receive a different set of roles. Both groups fall under the Engineering root department.

Common Misunderstandings​

  • "Departments must follow a single hierarchy." — A Tenant can have multiple root departments, creating parallel organizational trees within the same Tenant.
  • "Department roles automatically cascade to child departments." — Each department carries its own role mappings. Parent department roles do not automatically propagate to child departments.
  • "Templates replace manual department creation." — Templates are optional. Departments can be created manually or provisioned from templates, depending on the use case.
warning

Department role mappings are independent at each level. If a parent department has a role, child departments do not automatically inherit it. Assign roles explicitly at each department level where they are needed.

Design Notes / Best Practices​

  • Use external identifiers to maintain synchronization with HR or directory systems rather than duplicating organizational data.
  • Define department templates for common organizational patterns (e.g., standard division structures) to reduce provisioning effort.
  • Keep department hierarchies reasonably shallow — deep nesting increases management complexity without proportional benefit.
tip

Use template groups to provision entire organizational structures at once. Clone a template group during Tenant Onboarding to set up departments, roles, and attributes in a single operation.

  • Modeling a corporate division structure with scoped roles per department
  • Synchronizing department hierarchies with an external HR system via external identifiers
  • Provisioning standard department structures across multiple Tenants using template groups

Tenant Model

The Tenant entity that contains departments.

Delegated Administration

Role assignment at Tenant, department, and user levels.

Membership & Application Assignment

How users are assigned to departments.

Tenant Onboarding

Template cloning for department provisioning.