Tenant Membership & Application Assignment
Summary
Tenant membership in Keymate is an explicit, independently managed relationship between a subject and a Tenant or organization hierarchy target. Role assignments and template entitlements can be anchored to that membership without becoming fields owned by the membership record. Application assignment controls which applications a Tenant can access, drawn from a platform-wide application catalog.
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
- Membership-bound roles and attributes
- 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 organization hierarchy target. The membership provides:
- Tenant identifier — which Tenant the user belongs to
- Department identifier — which department within the Tenant
- Membership identifier — the stable anchor used by membership-scoped authorization facts
- 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. Creating a new membership is additive and does not mean "replace every old organization membership."
Roles are managed by the role domain and reference the concrete membership identifier. Direct grants commonly use the membership as both assignment boundary and membership anchor. Organization-template materialization can use a different assignment/source identifier while retaining the same concrete membership anchor. Lifecycle cleanup must therefore select role rows by the exact membership identifier rather than by source-specific assignment identifiers.
Membership and Role Lifecycle
The target KEOPS invariant is:
membership is disabled or removed
→ revoke every durable role assignment anchored to that exact membership
→ preserve every other membership and its roles
This cascade covers both direct grants and organization-template-sourced grants. Membership-management continues to own membership state, role-management owns role persistence and role events, and KEOPS owns the cross-domain transaction.
Exact-membership role cleanup is tracked by KEOPS #320. Shared active/effective membership validation across direct, bulk, and template role-assignment paths is tracked by #321. Until the relevant releases are deployed, operators must not assume that changing membership state has already repaired historical stale role rows.
Disabling or removing membership A does not disable membership B, even when B belongs to the same user. Likewise, creating B does not implicitly disable A. An application that needs a replace-style business workflow must issue explicit lifecycle commands and handle their normal concurrency contracts; Keymate does not expose an atomic "replace organization" operation as part of this model.
Durable role cleanup also does not rewrite or automatically invalidate self-contained access tokens already issued for membership A. See Org-Aware Tokens & Sessions for the separate token and client-session lifecycle.
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 independent memberships (two in Acme Corp, one in Beta Inc), each able to anchor distinct role assignments. Acme Corp users can access the portal and reporting API. Beta Inc users can access the legacy tool.
- Why: Membership and role facts remain scoped by the concrete membership identifier. 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 memberships in multiple Tenants. Each membership is independent and can anchor its own role and attribute facts.
- "Creating a membership in organization B replaces organization A." — Membership creation is additive. Organization A changes only through an explicit lifecycle command.
- "Disabling membership A should remove every role the user has." — Cleanup is scoped to role assignments anchored to A. Roles anchored to other active memberships remain.
- "Role cleanup immediately invalidates every issued token." — Durable facts and issued-token enforcement have separate lifecycles.
- "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 memberships, organization context is selected per requesting authenticated client session under the planned generic runtime. Do not assume one global active context for the root SSO session.
Design Notes / Best Practices
- Mark the most frequently used assignment as the default to reduce friction during authentication.
- Treat the membership identifier as the lifecycle boundary for membership-scoped role facts.
- Use explicit disable/remove commands for an old membership; do not infer replacement from creation of a new membership.
- 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