Skip to main content

Org-Unit-Aware Identity

Summary​

Keymate makes identity Organization-aware by linking users to specific positions within a department hierarchy. A user does not hold a flat relationship to an Organization — instead, the user receives an assignment to a particular department (organizational unit) within the hierarchy. This assignment determines which roles apply, which attributes are active, and which context flows into the access token. The platform supports unlimited hierarchical nesting, role inheritance through the department tree, and runtime context switching between assignments.

Why It Exists​

Real organizations are not flat. A government agency has directorates, divisions, and branches. A company has business units, departments, and teams. Users operate within specific parts of this hierarchy, and their effective permissions depend on their position. Org-unit-aware identity captures this reality by making the department — not the Organization — the unit of access. This enables authorization decisions that reflect where a user sits in the organizational tree, not which Organization they belong to.

Where It Fits in Keymate​

The organization model defines the hierarchical structure of departments within a Tenant. Org-unit-aware identity connects users to specific positions in this hierarchy. The resulting context feeds into token issuance as department claims and into token exchange for runtime context switching. The authorization layer evaluates policies against the department context to produce department-scoped access decisions.

Boundaries​

This page covers how department hierarchy shapes identity context and role inheritance. It does not cover:

How It Works​

Department Assignments​

When a user is assigned to a department, the platform creates an assignment record that captures:

  • The target department within the organizational hierarchy
  • The roles granted to the user in that department
  • Custom attributes specific to this assignment
  • Whether this is the user's default assignment

A user can hold multiple department assignments across the hierarchy. For example, a user might be assigned to both the "Tax Audit" and "Compliance" departments, each with different role sets.

Hierarchical Department Structure​

Departments form a tree with unlimited nesting. Each department has a parent (except the root), enabling structures like:

  • Organization (root)
    • Regional Directorate
      • Tax Division
        • Audit Branch
      • Collection Division

The platform traverses this hierarchy for role resolution, administrative scoping, and context-based queries.

Role Inheritance Through the Hierarchy​

The department hierarchy enables role inheritance. When the platform resolves a user's effective roles for a department context:

  1. It collects roles from the user's direct assignment to the department
  2. It collects roles defined on the department itself
  3. It walks up the hierarchy to collect roles from each ancestor department

This means a role defined at the "Regional Directorate" level automatically applies to all users in its child departments (Tax Division, Audit Branch, etc.) unless overridden at a lower level.

Organization Ticket and Active Context​

When a user selects a department context (at login or via token exchange), the platform creates a session-bound ticket that records the active assignment. This ticket links the user's session to a specific department position and becomes the source of truth for the department context carried in the access token. Only one department context is active per session.

External System Mapping​

Departments can carry external identifiers that map to equivalent structures in external systems. This enables synchronization scenarios where the platform's department hierarchy mirrors an external directory or HR system, and user assignments can be mapped or reconciled across systems.

Diagram​

Example Scenario​

Scenario​

A user is assigned to the Audit Branch within the Tax Division. The Tax Division defines an "auditor" role, and the Regional Directorate defines a "staff" role. The user also receives a "senior auditor" role directly on their Audit Branch assignment. The user authenticates and selects the Audit Branch context.

Input​

  • Actor: User with an Audit Branch assignment
  • Resource: Access token issuance
  • Action: Authenticate and select Audit Branch as active context
  • Context: Audit Branch has no department-level roles; Tax Division defines "auditor"; Regional Directorate defines "staff"; user has direct "senior auditor" assignment role

Expected Outcome​

  • Applied — The user's access token carries three roles for the Audit Branch context: "staff" (inherited from Regional Directorate), "auditor" (inherited from Tax Division), and "senior auditor" (directly assigned)
  • Why: Role resolution walks up the hierarchy from Audit Branch through Tax Division to Regional Directorate, collecting roles at each level and combining them with the user's directly assigned roles

Common Misunderstandings​

  • "A user can be active in multiple departments simultaneously" — No. The organization ticket system enforces a single active department context per session. Switching departments requires a token exchange that revokes the previous token.

  • "Department deletion removes the user's identity" — No. Deleting a department removes assignments to that department, but the user identity and assignments to other departments remain intact.

  • "Role inheritance flows downward automatically without configuration" — Role inheritance resolves at query time based on the hierarchy. Roles must be defined on a department or its ancestors — the platform does not auto-generate roles for child departments.

warning

When a department's position in the hierarchy changes (re-parenting), the role inheritance path changes for all users assigned to that department and its children. Verify role resolution after restructuring the hierarchy.

Design Notes / Best Practices​

  • Model your department hierarchy to reflect real organizational reporting lines. The hierarchy drives role inheritance, so a well-structured tree reduces redundant role assignments.
  • Assign broad baseline roles at higher levels (directorate, division) and specific operational roles at lower levels (branch, team). This layered approach keeps role administration manageable.
  • Use external identifiers on departments to maintain alignment with external HR or directory systems. This simplifies user assignment synchronization.
tip

When onboarding a new organizational structure, use department templates to pre-define the hierarchy and role sets. Templates ensure consistent configuration and reduce manual setup errors.

  • Modeling multi-level government agency structures with role inheritance
  • Switching user context between departments during a work session
  • Synchronizing department hierarchies with external HR systems
  • Enforcing department-scoped data access in downstream services

Users, Groups, Roles & Organizations

How roles resolve across organizational levels

Token Exchange Model

Department context switching via token exchange

Scoped Administration Model

Administrative delegation within the hierarchy

Organization Model

Tenant and department hierarchy definitions