Delegated Administration
Summary
Keymate supports delegated administration by assigning roles at three levels: Tenant, department, and user assignment. This layered approach allows platform administrators to delegate management of organizational contexts to Tenant administrators, who can further delegate to department leads. Each level carries both realm-level and client-level role mappings, enabling fine-grained administrative scoping.
Why It Exists
Platform administrators cannot manage every Tenant's internal structure. As the number of Tenants grows, administrative tasks — managing departments, assigning users, configuring roles — must be delegated to people within each Tenant. Delegated administration provides the role structure to scope administrative authority without granting platform-wide access.
Where It Fits in Keymate
Delegated administration builds on the Tenant Model (Tenant-level roles), Organization Hierarchy (department-level roles), and Membership & Application Assignment (user-assignment-level roles). The effective role set for a user combines roles from all three levels and is reflected in tokens through Org-Aware Tokens & Sessions.
Boundaries
What this concept covers:
- Role assignment at Tenant, department, and user assignment levels
- Realm-level vs. client-level roles at each level
- How the three levels compose to define effective administrative authority
What this concept does not cover:
- Policy evaluation and enforcement — see Policy Evaluation Model
- How roles appear in tokens — see Org-Aware Tokens & Sessions
- Role definitions and management — see Groups
How It Works
Role Assignment Levels
Keymate assigns roles at three organizational levels, each scoped to a different part of the hierarchy:
| Level | Scope | Use Case |
|---|---|---|
| Tenant | Applies across the entire Tenant | Tenant-wide administrative roles |
| Department | Applies within a specific department | Department management and team-specific roles |
| User Assignment | Applies to a specific user within a department | Individual user permissions and overrides |
Realm Roles vs. Client Roles
At each level, roles can be assigned as:
- Realm roles — roles that apply across all applications within the Tenant. Use realm roles for cross-cutting administrative capabilities.
- Client roles — roles scoped to a specific application. Use client roles for application-specific administrative functions.
Role Composition
When a user operates within an organizational context, the platform resolves roles from all applicable levels:
- Tenant-level roles — baseline roles available to all members of the Tenant
- Department-level roles — roles specific to the user's active department
- User-assignment-level roles — roles assigned directly to the user's assignment
The combination of these roles forms the user's effective role set for authorization decisions within that organizational context.
Administrative Delegation Pattern
A typical delegation pattern works as follows:
- Platform administrator assigns Tenant-level administrative roles to a Tenant administrator
- Tenant administrator creates departments and assigns department-level roles to department leads
- Department lead manages user assignments within their department, assigning user-level roles as needed
Each level can manage only the scope it controls — a department lead cannot modify Tenant-level configuration, and a Tenant administrator cannot modify other Tenants.
Diagram
Example Scenario
Scenario
A platform administrator delegates Tenant management to a Tenant administrator, who delegates department management to a department lead.
Input
- Actor: Platform administrator → Tenant administrator → department lead
- Resource: Acme Corp Tenant, Engineering department, user assignments
- Action: Assign administrative roles at each level
- Context: Platform admin creates Acme Corp with a tenant-admin role; tenant admin creates Engineering department with dept-manager role; department lead assigns user-level roles
Expected Outcome
- Result: Three-level delegation chain established. The Tenant administrator manages Acme Corp's departments and applications. The department lead manages Engineering team membership and user-level roles. Neither can operate outside their delegated scope.
- Why: Each role assignment level limits administrative authority to the appropriate organizational boundary. The Tenant administrator cannot affect other Tenants, and the department lead cannot modify Tenant-level configuration.
Common Misunderstandings
- "Tenant-level roles override department-level roles." — Roles at each level are additive, not overriding. A user's effective role set is the combination of all applicable levels.
- "Department leads can modify Tenant settings." — Department-level administrative roles scope authority to the department. Tenant-level operations require Tenant-level roles.
- "All users in a Tenant share the same roles." — Roles vary by department and individual assignment. Two users in the same Tenant but different departments can have entirely different effective role sets.
Roles at each level are independent. Granting a Tenant-level role does not automatically assign it at the department or user level. Assign roles explicitly at the level where they are needed.
Design Notes / Best Practices
- Define a clear administrative role taxonomy before provisioning Tenants: platform-level, Tenant-level, department-level, and user-level administrative roles.
- Use realm roles for cross-application administrative capabilities and client roles for application-specific administrative functions.
- Limit the number of administrative role assignments at the Tenant level. Prefer department-level delegation for day-to-day management tasks.
Use Tenant Onboarding templates to pre-configure standard department-level roles, reducing manual role assignment during Tenant provisioning.
Related Use Cases
- Delegating Tenant management to a customer-appointed administrator in a B2B platform
- Assigning department-scoped administrative roles to team leads
- Building a three-tier administrative hierarchy: platform → Tenant → department