Skip to main content

Users, Groups, Roles & Organizations

Summary​

Keymate's identity domain connects four core entities: users, groups, roles, and Organizations. Users receive assignments to Organizations and departments, each assignment carrying its own set of roles. Groups provide a way to manage collections of users within an organizational boundary. Roles exist at multiple levels — realm-wide, application-specific, and department-scoped — and the platform resolves a user's effective role set based on their active organizational assignment and the department hierarchy.

Why It Exists​

Enterprise systems need to model complex organizational relationships where a single user holds different responsibilities in different departments. A flat user-role mapping cannot capture this complexity. By linking role assignments to organizational positions and supporting hierarchical role inheritance through the department tree, Keymate enables fine-grained access control that mirrors real organizational structures.

Where It Fits in Keymate​

These entity relationships form the data layer that feeds authorization decisions. The identity model defines the user as a subject. The organization model defines the hierarchical structure. This page describes how they connect. Token issuance reads these relationships to assemble claims, and the authorization layer evaluates policies against the resulting role set.

Boundaries​

This page covers the relationships between users, groups, roles, and Organizations, and how roles resolve. It does not cover:

How It Works​

User-to-Organization Assignments​

A user connects to an Organization through an assignment. Each assignment links the user to a specific department within the Organization and carries its own role set and attributes. A user can hold multiple assignments — one per department or across multiple Organizations — enabling cross-departmental operation. One assignment can be marked as the default, determining the initial context when the user logs in.

Role Levels​

The platform supports roles at three levels:

  • Realm-wide roles apply across the entire identity realm regardless of Organization. These represent global permissions such as system administration.
  • Application-specific roles are scoped to a particular application (OAuth client). Organizations define which application roles are available within their boundary.
  • Department-assigned roles are granted to a user through their organizational assignment. These roles are specific to the user's position within a particular department.

Role Resolution Through the Hierarchy​

When the platform resolves a user's effective roles for a given organizational context, it considers:

  1. Roles directly assigned to the user on their department assignment
  2. Roles defined on the department itself (department-level roles)
  3. Roles inherited from parent departments up the hierarchy

This hierarchical resolution ensures that a user in a sub-department inherits the roles defined at parent levels, while department-specific roles can further refine or extend the set.

Groups and Organizational Scoping​

Groups provide a mechanism for managing collections of users. In Keymate, groups can be mapped to Organizations, enabling Organization-scoped group membership. When a group is mapped to an Organization, it becomes visible and manageable within that Organization's administrative boundary. Groups follow the identity server's standard group model and support hierarchical nesting.

Application Assignment​

Organizations define which applications (OAuth clients) are available within their boundary. When an Organization receives an application assignment, the application's roles become available for assignment to users within that Organization. This prevents users from receiving roles for applications that their Organization does not use.

Diagram​

Example Scenario​

Scenario​

An administrator assigns a user to the Tax Audit department within a government Organization. The department has pre-defined roles for auditors. The user also receives a direct role granting access to a specialized reporting application.

Input​

  • Actor: Administrator assigning a user to the Tax Audit department
  • Resource: User assignment in the Tax Audit department
  • Action: Create assignment with department roles and one direct application role
  • Context: The Tax Audit department inherits two global roles from its parent department and defines three department-specific roles

Expected Outcome​

  • Applied — The user's effective role set in the Tax Audit context includes: the two inherited parent roles, the three department-specific roles, and the one directly assigned application role
  • Why: Role resolution combines directly assigned roles, department-level roles, and inherited roles from the parent hierarchy to produce the complete effective role set

Common Misunderstandings​

  • "Roles are global across all Organizations" — No. Application-specific roles are only available in Organizations that have the corresponding application assigned. Department roles are scoped to the department hierarchy.

  • "A user sees all groups in the system" — No. Groups mapped to an Organization are visible within that Organization's boundary. Unmapped groups follow the identity server's standard visibility rules.

  • "Removing a parent department's role removes it from all child departments" — The platform resolves role inheritance at query time. Changing the parent's role set affects all child departments in subsequent role resolution, but it does not modify the child department's own role definitions.

warning

A user's effective roles depend on their active organizational assignment. The same user may have different roles in different departments. Design your authorization logic to read roles from the active token context rather than assuming a single global role set.

Design Notes / Best Practices​

  • Assign roles at the highest appropriate level in the department hierarchy to reduce redundant role assignments on child departments.
  • Use application assignment on Organizations to restrict which application roles are available. This prevents accidental role grants for applications that the Organization does not use.
  • Mark one assignment as the default for each user to provide a predictable initial context at login.
tip

When a user needs temporary access to a department they are not assigned to, create a new assignment rather than modifying existing ones. Assignments are the unit of organizational access — adding and removing them is the intended workflow.

  • Modeling a user who operates across multiple departments with different roles in each
  • Restricting application access to specific Organizations via application assignment
  • Inheriting baseline roles from parent departments to all sub-departments
  • Managing user collections through Organization-scoped groups

Identity Model

Core identity primitives that users build on

Org-Unit-Aware Identity

Department hierarchy and organizational context

Organization Model

Tenant and department hierarchy structure

Token Claims & Context

How resolved roles appear in access tokens