Prompt
How do I set up role-based access control for a multi-tenant SaaS app?
Latest observation
Setting up role-based access control (RBAC) for a multi-tenant SaaS app is mostly about separating “who they are,” “what tenant they belong to,” and “what they’re allowed to do in that tenant.” The key is to avoid leaking permissions across tenants.
1) Start with the core model
For a multi-tenant app, every authorization check should consider:
- User: the authenticated person/service
- Tenant: the organization/account/workspace they’re operating in
- Role: the permission bundle assigned to that user in that tenant
- Resource: the thing being accessed (project, invoice, report, etc.)
A user can have:
- different roles in different tenants
- possibly multiple roles in the same tenant
- tenant-scoped permissions only, unless you explicitly support global/system roles
2) Use a tenant-scoped RBAC model
A simple, common schema:
Tables/entities
userstenantsrolespermissionsuser_tenant_roles(join table)role_permissions(join table)
Example relationships
usersbelong to manytenantsthroughuser_tenant_rolesrolesare either:- global templates (e.g. Admin, Member, Viewer), or
- tenant-specific custom roles
permissionsare atomic actions like:project.readproject.writebilling.managemembers.invite
Example join table columns
user_tenant_roles:
user_idtenant_idrole_id- optionally
resource_idif you want role assignment on a sub-scope created_at
3) Define permissions as actions, not pages
Good permissions are granular and action-based:
invoice.readinvoice.createinvoice.approveteam.member.removesettings.update
Avoid encoding UI concepts like “can see dashboard page” as your main access model. UI should reflect permissions, but authorization should be based on business actions.
4) Decide your scope hierarchy
Usually you’ll need one or more scopes:
Common scopes
- Global/system
- platform admins, support staff, internal ops
- Tenant
- the normal SaaS customer boundary
- Resource
- per project/team/folder inside a tenant
Example:
- Platform Admin: can access all tenants
- Tenant Admin: can manage everything in one tenant
- Project Manager: can manage one project within a tenant
- Viewer: read-only in tenant or project
If you support resource-level roles, your permission check should resolve from most specific scope outward:
- resource assignment
- tenant assignment
- global assignment
5) Enforce tenant isolation first, then permissions
A common safe pattern:
- Identify the current tenant from the request
- Verify the user is a member of that tenant
- Resolve the user’s role(s) in that tenant
- Check whether the role grants the required permission
- Apply resource-level constraints if relevant
Never rely only on the UI to filter tenants. Always enforce tenant boundaries on the backend.
6) Store tenant context explicitly in requests
Every request should include tenant context in a secure way, for example:
- subdomain:
acme.yourapp.com - path:
/tenants/acme/projects/123 - header:
X-Tenant-Id - selected tenant in session/token
Then validate that:
- the tenant exists
- the user belongs to it
- the resource belongs to that tenant
This prevents cross-tenant access bugs.
7) Keep roles simple and permissions composable
A good starting role set:
- Owner
- full tenant control, billing, delete tenant, manage members
- Admin
- manage most resources, not necessarily billing or tenant deletion
- Editor
- create/update business objects
- Viewer
- read-only
Then map roles to permissions:
| Permission | Viewer | Editor | Admin | Owner |
|---|---|---|---|---|
| project.read | ✓ | ✓ | ✓ | ✓ |
| project.write | ✓ | ✓ | ✓ | |
| member.invite | ✓ | ✓ | ||
| billing.manage | ✓ | |||
| tenant.delete | ✓ |
This is easier to maintain than ad hoc boolean flags.
8) Consider whether you need custom roles
If customers want their own roles, support:
- tenant-created roles
- role cloning from templates
- permission toggles per role
If you don’t need that flexibility, keep only predefined roles. Simpler is safer.
9) Model ownership separately from role
Ownership often needs different treatment than RBAC:
- “project owner”
- “document creator”
- “invoice assignee”
These can be:
- a field on the resource, or
- a resource-level permission grant
Example:
- A user may be
Editorin the tenant but can only delete documents they own.
That’s not pure RBAC anymore; it’s RBAC + resource ownership checks.
10) Add policy checks in one centralized place
Don’t scatter authorization logic everywhere.
Create a shared authorization layer:
- middleware / guards
- policy service
can(user, action, resource, tenant)helper
Example policy flow:
can(user, "project.update", project)- policy service checks tenant membership and role permissions
- resource ownership rules apply if needed
This keeps logic consistent and testable.
11) Use least privilege by default
Default new users to the minimal role:
- often
ViewerorMember
Grant elevated permissions only when necessary:
- admin approval for role changes
- audit logging for permission grants/revocations
Also protect sensitive actions:
- billing changes
- tenant deletion
- role/permission changes
- data export
12) Audit everything important
Log:
- role assignment changes
- permission changes
- tenant membership changes
- sensitive resource access if required
- failed authorization attempts for debugging/security
Audit fields:
- actor user ID
- tenant ID
- target user/resource
- old role/new role
- timestamp
- request ID
13) Make it testable
Create tests for:
- same user in multiple tenants with different roles
- cross-tenant access denied
- resource belonging to another tenant denied
- owner/admin/editor/viewer differences
- role changes taking effect immediately
- deleted/inactive tenant access denied
Authorization bugs in SaaS apps are often tenant-boundary bugs, so test those heavily.
14) Example implementation pattern
A typical request authorization sequence:
- Authenticate user
- Resolve tenant
- Fetch membership:
user_tenant_roles where user_id=? and tenant_id=? - Collect permissions from assigned role(s)
- Check action permission
- If resource-specific, verify resource.tenant_id == tenant_id
- If needed, apply additional ownership/policy rules
Pseudo-code:
def can(user, tenant_id, action, resource=None):
if not is_member(user.id, tenant_id):
return False
roles = get_roles_for_user_in_tenant(user.id, tenant_id)
permissions = get_permissions_for_roles(roles)
if action not in permissions:
return False
if resource is not None and resource.tenant_id != tenant_id:
return False
return True
15) Common pitfalls to avoid
- Not scoping by tenant everywhere
- Using only frontend checks
- Hardcoding roles in many places
- Confusing authentication with authorization
- Letting a user’s role in one tenant apply to another
- Making permissions too broad
- Forgetting to secure background jobs / APIs / webhooks
- Not testing cross-tenant leakage
16) When to consider ABAC or policy engines
If your rules become complex, RBAC alone may not be enough. Consider:
- ABAC (attribute-based access control)
- policy engines like OPA, Cedar, or framework-specific policy layers
This helps when access depends on:
- resource ownership
- department
- subscription plan
- region
- document status
- time-based rules
A common approach is:
- RBAC for baseline permissions
- ABAC for contextual exceptions
Recommended starting architecture
If you want a practical baseline:
- Tenant-scoped roles: Owner, Admin, Editor, Viewer
- Atomic permissions mapped to roles
- Central policy service
- Tenant membership required for all tenant resources
- Resource ownership checks where needed
- Audit logs for sensitive changes
If you want, I can also give you:
- a database schema example,
- a Node/Express implementation,
- a Django or Rails version, or
- a diagram showing tenant/role/permission relationships.