Tenant Membership & Application Assignment
Summary
Tenant membership in Keymate is an explicit relationship — each user is assigned to a specific Tenant and department through a user assignment record that carries roles, attributes, and a default assignment flag. Application assignment controls which applications a Tenant can access, drawn from a platform-wide application catalog. Together, membership and application assignment define the access boundary for every user within a Tenant.
Why It Exists
Multi-tenant platforms must control both who belongs to each Tenant and what applications are available within that Tenant. Without explicit membership, users could access Tenants they do not belong to. Without application assignment, all applications would be visible to all Tenants, undermining per-Tenant licensing and access control.
Where It Fits in Keymate
Membership builds on the Tenant Model and Organization Hierarchy by linking users to specific positions within the organizational structure. Application assignment connects the Tenant model to the platform's application catalog. Both feed into Org-Aware Tokens & Sessions, which embeds the active assignment into access tokens.
Boundaries
What this concept covers:
- User assignment to a Tenant and department
- Roles and attributes on user assignments
- Default assignment selection
- Application catalog structure (types, status, assignability)
- Tenant-level application assignment
What this concept does not cover:
- How role mappings cascade across levels — see Delegated Administration
- How assignment context appears in tokens — see Org-Aware Tokens & Sessions
- How Tenants are provisioned with initial applications — see Tenant Onboarding
How It Works
User Assignment
A user assignment links a user to a specific Tenant and department. Each assignment record carries:
- Tenant identifier — which Tenant the user belongs to
- Department identifier — which department within the Tenant
- Roles — per-assignment role mappings specific to this user in this context
- Attributes — key-value metadata attached to the assignment
- Default flag — whether this is the user's default assignment
A single user can hold multiple assignments across different Tenants or within different departments of the same Tenant. Each assignment is independent — roles and attributes in one assignment do not affect another.
Default Assignment
One assignment per user can be marked as the default. The default assignment determines which Tenant and department context applies when the user authenticates without explicitly selecting one. Users and administrators can change the default assignment.
Application Catalog
The platform maintains a central application catalog. Each application in the catalog has:
| Property | Description |
|---|---|
| Type | API, web, or resource server |
| Status | Active or deprecated |
| Assignability | Whether the application can be assigned to Tenants |
Active, assignable applications are available for Tenant administrators to assign to their Tenants. Deprecated applications remain functional for Tenants that already use them but are not available for new assignments.
Tenant Application Assignment
Tenant administrators or platform administrators assign applications from the catalog to a Tenant. Once assigned, the Tenant's users can access that application subject to their individual roles and permissions. Unassigned applications are not accessible to the Tenant's users.
Diagram
Example Scenario
Scenario
Jane Doe works across two Tenants and needs different roles in each. The platform administrator assigns specific applications to each Tenant.
Input
- Actor: Platform administrator and Tenant administrator
- Resource: User assignments and application catalog
- Action: Create assignments for Jane Doe in two Tenants; assign applications to each Tenant
- Context: Acme Corp uses the portal and reporting API; Beta Inc uses the legacy tool
Expected Outcome
- Result: Jane Doe has three assignments (two in Acme Corp, one in Beta Inc), each with distinct roles. Acme Corp users can access the portal and reporting API. Beta Inc users can access the legacy tool.
- Why: Each assignment is independent, carrying its own roles and attributes. Application assignment is per-Tenant, so users in each Tenant see only the applications assigned to their Tenant.
Common Misunderstandings
- "A user can belong to only one Tenant." — Users can hold assignments in multiple Tenants. Each assignment is independent and carries its own roles and attributes.
- "Assigning an application to a Tenant gives all users access." — Application assignment makes the application available within the Tenant. Individual user access still depends on the user's roles and policies.
- "The default assignment cannot be changed." — Users and administrators can change the default assignment at any time.
When a user holds multiple assignments, the active assignment determines which organizational context appears in tokens. Ensure downstream services check the organizational claims in the token rather than assuming a fixed Tenant context.
Design Notes / Best Practices
- Mark the most frequently used assignment as the default to reduce friction during authentication.
- Use the assignability flag on applications to prevent experimental or internal applications from being assigned to production Tenants.
- Review deprecated applications periodically and remove their assignments from Tenants that no longer need them.
Use Org-Aware Tokens & Sessions to understand how the active assignment is selected and embedded into access tokens during a user session.
Related Use Cases
- Assigning a user to multiple Tenants with different roles in each
- Managing a per-Tenant application catalog with active and deprecated applications
- Setting a default assignment for users who primarily operate in one organizational context