Multi-Tenant Access Control: Three Layers That Must Stay Separate

01Three questions, three layers

Each layer narrows what the one outside it allows, and none of them can widen the layer outside it.

02The tenant boundary comes first and is not a permission

The tenant boundary is not something a role grants. Every tenant-owned model carries a global scope that filters by the current tenant, and if no tenant is bound the query throws instead of running. Roles never widen it. Code that genuinely needs every tenant, such as the platform super admin’s tools, must call an explicitly named escape hatch that stands out in review.

That ordering matters for everything below: record scope runs after the tenant filter. In the words of Omnitech’s own code, record scope “decides whose rows within the tenant, never which tenant”. A misconfigured role can at worst show a user too much of their own tenant; it can never show another tenant. How the boundary is built and tested is covered in Multi-tenant isolation.

Roles are per tenant too. Omnitech uses Spatie’s laravel-permission with its “teams” feature keyed on tenant_id, so a role called “Sales Manager” in one workspace is a different role from one with the same name in another. That setting is forced in code rather than left in the package’s config file, so a package upgrade can’t quietly turn it off.

config([
    'permission.teams' => true,
    'permission.column_names.team_foreign_key' => 'tenant_id',
]);

03Permissions from one registry

Every permission in Omnitech comes from a single registry class. The registry’s own comment states the reason: there is no second place to register a permission, which is how the legacy system ended up with capabilities that existed in code but never in the UI.

The registry has two kinds of entry:

new Module('deals', 'Deals', 'Sales', extras: [
    'move_stage'    => 'Move stage',
    'reopen_closed' => 'Reopen closed deals',
]);

// deals.view, deals.create, deals.edit, deals.delete,
// deals.move_stage, deals.reopen_closed

• Modules (22 of them, grouped by area: Sales, Service, Revenue and others). Each module gets the four standard actions (view, create, edit, delete) plus extras that only make sense for that module: converting a lead, merging companies, moving a deal’s stage, reopening a closed deal, logging time, sending a contract for signature.
• Capabilities (12 of them): sensitive actions that cut across modules, each with a risk label. Revealing stored client credentials is labelled high risk. Placing calls and sending mass email are labelled metered because they cost money. Exports are logged and always stay within the user’s record scope. Permanent deletion is high risk because it bypasses the 30-day recycle bin.

The same registry feeds the seeder, the roles screen and the tests, so a permission can’t exist in one and be missing from another.

High-risk capabilities are meant to leave an audit trail. Today that trail is wired for one case, with more to follow: revealing a custom field whose value is protected by a capability. Each attempt is recorded with whether access was allowed, and the write is deliberately not wrapped in error handling. If the audit entry can’t be saved, the reveal fails. A reveal that couldn’t be recorded is treated as one that didn’t happen.

04Record scope is its own dimension

This is the layer most systems skip, and it is the one that came directly from experience. Omnitech replaced a Perfex CRM installation. In Perfex, how much a user could see was baked into permission names: view, view_own, and the vague minimal_access. Because visibility lived inside the permission, giving someone edit rights could quietly change what they could read.

Omnitech makes scope a separate setting per role and per module, with six levels:

05Rules that keep record scope predictable

• Scopes are ranked, and the widest wins. A user with several roles gets the broadest scope any of them grants for that module. The tenant’s Administrator role always resolves to All.
• “None” returns an empty list, not an error. A user with no access to a module sees an empty table, not a crash page.
• One resolver answers “whose records” for both the list and the single record. The list query and the per-record permission check call the same code. When those two drift apart you get a row that appears in a table and then refuses to open, or the reverse. Sharing one resolver makes that drift impossible rather than unlikely.
• Scope isn’t cached. Team and department membership is looked up per request, because a stale cache here would be a visibility bug and the lookups are cheap.
• Legacy permissions translate cleanly. During the migration, Perfex’s view maps to All, view_own to Own and minimal_access to Assigned, so existing staff kept exactly the access they had (how the migration was reconciled).

06How each layer is tested

Each layer has its own tests, so a change in one can’t silently weaken another.

• Tenant boundary: cross-tenant reads blocked, writes stamped with the tenant, queries without a tenant throw, and one test that discovers every tenant-owned model automatically and checks each is isolated, so new models are covered the day they are written.
• Permissions: roles and permissions tests, plus policy tests per area (deals, tickets, pipelines, custom fields).
• Record scope: scoping tests per model (leads, deals, companies and contacts, tickets, activities) and a dedicated test for the assignee side of the scope model.

07A permission registry template

Fill in the module rows before you write the first policy. If a permission can’t be placed in a row, it doesn’t belong in the code yet. The table is for modules, and its example rows show the shape; capabilities get a sheet of their own, described below it.

Capabilities get their own sheet with three columns: the capability, its risk label (high, metered, logged, commercial or scoped) and one sentence on why it is separate from the module actions. Permanent deletion, for example, is high risk because it bypasses the 30-day recycle bin.

08When to get help

If your platform mixes these layers, for example visibility encoded in permission names or roles that are global across tenants, the Platform Change-Readiness Scorecard will show it under tenant isolation and permission model. For a full review with a tenancy and security risk register, see SaaS architecture.