Multi-tenant authorization
Multi-tenant authorization is how SecureAuth Connect separates decisions, data, and policies across tenants in a single deployment. This page describes the isolation model, where you attach per-tenant policies, and when to reach for a multi-tenant authorizer.
The isolation model
SecureAuth's multi-tenant model is built on three layers:
- Tenant. The top-level boundary. Policies, identity pools, and permission systems created in one tenant are not visible to another.
- Workspace. A logical environment inside a tenant. Each workspace has its own clients, scopes, policies, and authentication context. Workspaces are the natural home for per-tenant application surfaces in a B2B or B2B2C product.
- Identity pool. A user population that can be attached to one or more workspaces. Identity data and permission system schemas live at the identity pool level.
Authorization decisions are always evaluated in the context of a specific tenant and workspace. A policy attached in workspace A never runs against a request for workspace B, even if both workspaces belong to the same tenant.
Per-tenant policies
There are two patterns for attaching policies in a multi-tenant deployment:
One workspace per tenant
Each customer gets their own workspace. Policies attached at the workspace level apply to that customer only. This is the cleanest fit for B2B SaaS where each customer wants to configure their own authentication and authorization rules.
Pros:
- Strong isolation. Each customer's policies are independently versioned, attached, and audited.
- Customers can be given workspace-admin access to author their own policies.
- Per-tenant SLAs and branding flow naturally out of the workspace boundary.
Trade-offs:
- More workspaces to manage. Declarative configuration and automation become important at scale.
- Global rules must be applied per workspace, either through shared policy templates or through declarative imports.
One workspace with tenant-aware policies
Every customer shares a single workspace. Policies read a tenant identifier from the token or request context and branch on it.
Pros:
- Fewer workspaces to manage.
- Global rules live in one place.
Trade-offs:
- Policies must carry tenant-handling logic, which increases complexity and the cost of mistakes.
- Weaker isolation: a bug in a shared policy can affect every tenant at once.
- Per-tenant audit is harder because the tenant identifier, not the workspace boundary, is what separates decisions.
For most B2B and B2B2C workloads, one workspace per tenant is the recommended starting point. Move toward tenant-aware policies only when operational scale forces it and you have automation that can manage per-tenant configuration through code.
Multi-tenant permission systems
A permission system is a tenant-wide resource: once created, it is visible across every workspace in the tenant. You can create multiple permission systems per tenant, for example one per identity pool or one dedicated to a single application.
For multi-tenant deployments, the decision is whether to:
- Share one permission system across tenants and namespace the relationships using object-type prefixes or a tenant attribute. Simpler to operate, weaker isolation.
- Create a permission system per tenant. Stronger isolation, more configuration to manage.
See Permission systems for the configuration model.
Multi-tenant authorizers
Multi-tenant authorizers are a specific deployment of a SecureAuth authorizer that runs in the system tenant and protects APIs that span multiple tenants. Reach for a multi-tenant authorizer when:
- You run on-premises or in a private cloud and need a shared gateway that protects APIs for every tenant.
- Your APIs are common across tenants and you want centrally administered policies applied uniformly.
- You want to avoid deploying one authorizer instance per tenant.
Per-tenant authorizers are still appropriate when workloads are tenant-isolated at the network level or when the gateway is dedicated to a single tenant.
See Authorizers for the list of supported authorizer targets and the multi-tenant deployment note.
Shared vs dedicated resources
A rough guide for multi-tenant deployments:
| Resource | Shared is fine when… | Dedicated is better when… |
|---|---|---|
| Workspace | Tenants run identical configuration and you have a way to express tenant identity in policies | Tenants need independent policies, branding, or scopes |
| Identity pool | Users are pooled across tenants (consumer product) | Each tenant owns its own user directory |
| Permission system | Object types and relations are uniform across tenants | Each tenant has a distinct authorization model |
| Authorizer | Gateway is shared across tenants and policies are centrally managed | Each tenant's gateway is network-isolated or tenant-dedicated |